Built-in tool reference

ToolBox().with_defaults() registers 8 tool groups (passing no arguments = all groups); with_subagent_provider() then appends the two sub-agent tools. The tables below list the registered name, purpose and parameters (including default values) of every built-in tool.

Browser tools need a browser engine

The browser group depends on Playwright; after installing it, run playwright install (in the image: playwright install chromium --with-deps). Startup is lazy at runtime: the worker thread and Chromium are only launched on the first call, browser contexts are isolated per agent identifier, and the default viewport is 1280×720.

system

Tool	Purpose	Parameters
system_info	Operating system and kernel, hostname, architecture, processor, timezone with UTC offset, locale, plus locale_env taken from LC_ALL/LANG; no other environment variables	none
datetime	Current system time and timezone (ISO format)	none

framework

Tool	Purpose	Parameters
ask_preference	Ask the user to pick from options (skips auto-confirmation, always asks a human)	question: str, choices: list[str], allow_extra: bool = False, default_choice: str \| None = None, title: str = "User Preference Query"
extract_compacted_tool_result	Retrieve the original text of a compacted tool result	toolcall_id: str

fs

Tool	Purpose	Parameters
temp_dir	Get the agent's own temporary directory (preferred over the system temp dir)	none
list_dir	List a directory	path: str, details: bool = False
file_info	Metadata (size, line count, text or binary, modified time); the file is read through to count lines	path: str
read_file	Read text by line range	path: str, line_offset: int = 0, line_limit: int \| None = None, include_line_numbers: bool = False
write_file	Create or overwrite a file (overwriting requires confirmation)	path: str, content: str = ""
mkdir	Create a directory	path: str
move	Move or rename (shutil.move semantics)	src: str, dst: str
copy	Copy (copy2 / copytree semantics, overwriting requires confirmation)	src: str, dst: str
delete	Delete a file or directory	path: str
request_image	Request an image into the context (requires the vision capability); optionally crops a relative region first and shrinks images whose long side exceeds 1000 px; URL images are downloaded before processing	src: str, crop: tuple[float, float, float, float] \| None = None ((x, y, w, h), every value a fraction in [0, 1])
glob	Find files recursively by name pattern, honours .gitignore	path: str = ".", name_pattern: str = "*", file_type: "file"\|"directory"\|"any" = "any", skip_ignored: bool = True
grep	Search by content, skips binary files, honours .gitignore, at most 100 matches	path: str, pattern: str, file_pattern: str = "*", include_content: bool = True, regex: bool = True, skip_ignored: bool = True

patch

Tool	Purpose	Parameters
apply_patch	Apply a unified diff; dry-run first, and on failure retry with limited fuzz plus diagnostics (wrong -p level, already applied, dangerous file name, etc.)	patch: str, reverse: bool = False, strip: int = 1, directory: str = "."

Pure git metadata diffs are not supported (renames, mode bits, binary patches).

cmd

Tool	Purpose	Parameters
bash	Run a command through bash (falling back to /bin/sh when absent); blocking, cancellable, stdout and stderr each truncated by max_output_size (head and tail kept)	command: str, timeout: float = 300, cd: str \| None = None, envs: dict[str, str] \| None = None, max_output_size: int \| None = 16000

A timeout is reported as RuntimeError and terminates the whole process group (SIGTERM first, SIGKILL after 5 seconds); the cd target must be inside the workspace. Not registered on Windows.

search

Tool	Purpose	Parameters
web_search	A sub-agent drives a browser to run the search and returns structured results; results carry a WARNING when the page could not actually be read	query: str, max_results: int = 5 (maximum 20)

browser

Tool	Purpose	Parameters
browser_page	Manage persistent pages	action: "list"\|"new"\|"navigate"\|"reload"\|"select"\|"close" = "list", page_id: str \| None = None, url: str \| None = None, wait_until = "domcontentloaded" (only takes effect on navigate / reload), timeout_ms: int = 15000
browser_resize	Set the viewport (CSS pixels)	width: int, height: int, page_id: str \| None = None
browser_snapshot	Read the page as accessibility / html / markdown, with paging support	page_id: str \| None = None, format: "accessibility"\|"html"\|"markdown" = "accessibility", selector: str \| None = None, start_char: int = 0, max_chars: int = 50000
browser_interact	Interact with the page using Playwright selectors	action: "click"\|"fill"\|"press"\|"select"\|"wait", selector: str \| None = None, value: str \| list[str] \| None = None, state = "visible", page_id: str \| None = None, timeout_ms: int = 15000
browser_evaluate	Execute JS in the page and return JSON-compatible data	expression: str, argument: JsonType = None, selector: str \| None = None, page_id: str \| None = None
browser_logs	Read captured console / error / request events (500-entry ring buffer)	page_id: str \| None = None, kind = "all", clear: bool = False
browser_screenshot	Take a screenshot (requires the vision capability); the image is deferred to a user message after the tool result	page_id: str \| None = None, selector: str \| None = None, clip: {x, y, width, height} \| None = None (all four keys are required), full_page: bool = False, save_to: str \| None = None, timeout_ms: int = 15000

selector, clip and full_page are mutually exclusive.

diagnostic

Tool	Purpose	Parameters
check_syntax	Validate syntax by parsing it (does not execute)	path: str, language: "python"\|"json"\|"bash"
diff_files	Diff two files; returns an empty string when they are identical	path_a: str, path_b: str
check_lint	Run mypy; when it is not installed it first asks for consent to run pip install mypy and returns as soon as the installation finishes, so this call runs no check and must be repeated	path: str, language: "python" = "python"

Sub-agents

Provided by ToolBox.with_subagent_provider(); see Sub-agents and cancellation for details.

Tool	Purpose	Parameters
agent_run	Spawn a sub-agent with a blank context to carry out a self-contained task	task: str, name: str \| None = None
agent_run_parallel	Run several tasks concurrently, returning results in input order	tasks: list[str], names: list[str] \| None = None