Skip to main content

Tool Reference

Tools are the capabilities available to the agent during a session. Some tools run silently; others require your approval before they execute, unless a permission rule says otherwise.

File I/O​

Read​

Read text files, images, and PDFs. Long lines are returned in full rather than clipped.

PDFs are processed client-side — pages are rendered locally and their embedded text extracted, with no network round-trip — and reads are bounded to a page range so large documents can be read in chunks.

When the active model has no vision support, reading an image returns its metadata (type and dimensions) instead of the image itself, so the agent knows the file exists and can inspect it programmatically.

Write​

Create or overwrite a file. Requires approval.

Edit​

Make exact string replacements in a file. Requires approval.

When the agent issues several Edit/Write calls for the same file in one batch, they run one at a time in call order, so later edits always see the result of earlier ones. Calls touching different files still run in parallel.

Glob​

Find files by glob pattern. Results are sorted by path and returned in pages of 100 files by default. A page ends at head_limit entries or the shared output budget, whichever comes first; pass the footer's next_offset back as offset to continue without skipping or repeating files. Set head_limit: 0 to remove the entry-count limit (the output budget still applies).

Glob returns matches found before its search deadline as a partial page with an explicit timeout footer. If it times out before finding anything, it fails with a suggestion to narrow the path or pattern. The default deadline is 20 seconds; set ANTE_FILE_SEARCH_TIMEOUT to a positive number of seconds to override it for both Glob and Grep.

Grep​

Search file contents with ripgrep regular expressions. Its modes return matching file paths (the default), match counts, or matching content lines. Results are sorted by path and paged at 250 entries by default; head_limit, offset, next_offset, and the output-budget behavior match Glob. Pages are always cut between complete entries, so a continuation never starts midway through a path, count, or content line.

Grep reports skipped unreadable, undecodable, oversized, or failed files in its footer. Like Glob, a timeout returns matches already found as a clearly marked partial page and becomes an error only when there are no matches to return.

Shell​

Bash​

Execute shell commands. Each call runs in a fresh non-interactive process — shell state does not persist between calls. The optional max_wait_ms field controls how long Ante waits for the command to finish inline (default 10000, clamped to 250–600000). Expiring that window never kills or times out the command: Ante returns a background handle under ~/.ante/run/jobs/<proc-id>/ with its pid, partial output, and growing status.json, stdout.txt, and stderr.txt files. Use a short window such as 250 for a server or watcher; do not append &, which is redundant and stripped automatically.

If the command finishes inside the window, Ante returns its output inline and explicitly discards the handle files. After a background handle has been returned, the job survives Ante restarts and is never collected while live; once settled, its directory is collected on a later startup after sitting unchanged for 24 hours. Interrupting a Bash call before it returns a handle terminates the whole process group, including child and grandchild processes. To stop an already-backgrounded job, send a signal to its process group with kill -- -<pid>. Requires approval.

Results begin with status: exited and an explicit exit_code, followed by separate stdout and stderr sections when those streams are non-empty. A background result instead begins with status: running and names its process id and handle files. Signal-terminated commands use the shell convention 128 + signal for the exit code.

For interactive programs and persistent shells, the agent drives durable named tmux sessions (ante-*) through ordinary Bash calls, guided by a bundled tmux skill — every keystroke it sends goes through normal Bash permission checks. Watch or type in any of those sessions with /term <name>.

Builtin​

Agent​

Spawn a sub-agent to handle a task autonomously. The agent picks which sub-agent to delegate to based on the task.

TodoWrite​

Track progress on multi-step work with a task list.

WebFetch​

Fetch a URL and return its contents directly for the active model to analyze, converting HTML to markdown. The input is URL-only; WebFetch does not run a second extraction model. Oversized responses spill to a local cache file the agent can read in slices instead of being truncated. Requests identify themselves as ante/<version>, and an unsuccessful HTTP response includes up to 2 KB of textual response-body detail when available. Requires approval.

WebSearch​

Search the web and return results with citations. Requires approval. Uses the provider's native web search, so it is available only on a provider that advertises supports_web_search (Anthropic, OpenAI, Gemini, Grok, OpenRouter, Antix, and Ali Coding Plan). On those providers it is added to the tool set automatically; on others it is not offered. A search is capped at 90 seconds — past that it fails with an error suggesting a narrower query instead of hanging the tool batch.

Opt-in tools​

These are not enabled by default. Turn them on with --include-tools.

ViewImage​

Read and analyze an image with a natural-language instruction.

MCP tools​

Tools provided by configured MCP servers are exposed to the agent as mcp__<server>__<tool>. They appear alongside built-in tools and behave identically from the agent's perspective. MCP tools obey the same --tools/--include-tools/--exclude-tools filtering as built-in tools, so a restrictive --tools base that doesn't name them will strip them; filter per server with enabled_tools instead.

Default tool set​

By default Ante enables Read, Bash, Grep, Glob, TodoWrite, WebFetch, Edit, Write, and Agent. WebSearch is added automatically when the session's provider supports native web search.

ViewImage is opt-in.

Tool filtering​

Control which tools are available in a session:

# Replace the default tool set with exactly these tools
ante --tools Read,Glob,Grep -p "analyze the code"

# Add opt-in tools on top of the default set
ante --include-tools ViewImage -p "describe the screenshots in assets/"

# Remove these tools
ante --exclude-tools Bash,Write -p "read-only analysis"

Each flag takes one comma-separated value per occurrence and may be repeated. Space-separated lists are rejected, and the former --allowed-tools name is no longer accepted (--disallowed-tools remains a deprecated alias for --exclude-tools).

Matcher syntax such as Bash(cargo test *) is accepted in these lists but selects by tool name only — it keeps the whole Bash tool available. To scope what a tool may run, use permission rules alongside filtering.