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	Overview of the operating system, architecture, timezone, locale and 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	Get metadata without reading the content (size, line count, text or binary, modified time)	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, over-long output truncated (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"、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 the next context round	page_id: str \| None = None、selector: str \| None = None、clip: dict \| None = None、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 (asks for consent before pip install mypy when it is not installed)	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