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. Image detection also checks file contents, so a PNG saved without an extension or with a .bin suffix is still read as an image.

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.

Completed edit results use a 32-row inline budget that preserves complete diff hunks in file order, with remaining changes summarized and accessible in full via Ctrl+O.

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.

In content mode, each long line is clipped to 500 characters including truncation markers. Matching lines keep the start of the first match in view; context lines keep their prefix. Use Read for the full line.

Shell​

Bash​

Execute shell commands. Each call runs in a fresh non-interactive process — shell state does not persist between calls. Commands receive the calling session ID in ANTE_SESSION instead of inheriting stale parent process values. 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. When a background job exits, its completion notification automatically re-enters the session at the model's next step boundary or turn start (delivering a notification block with exit code, duration, output tails, and file paths), removing the need for manual polling loops or long wait windows. 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.

Clients receive a TaskEnd event when tracked background work finishes, keyed to the original tool call. The TUI updates that call’s job status in place.

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, and can optionally specify a per-call model parameter to override the subtask's model (falling back to the agent definition or current session model). Use the max_concurrent_subagents setting to cap parallel calls; further calls wait for a slot.

AskUser​

Ask structured multiple-choice questions (one to four questions) mid-turn to clarify ambiguity or confirm decisions. The TUI renders questions in place of the composer with option previews, free-text notes, and multi-select support; Enter selects the recommended option, Esc skips so the model proceeds on its own judgment, and "Chat about this" returns to conversation. In channel gateways (Slack/Discord), questions render as numbered choices. Subagents do not receive AskUser, and unattended sessions never pause for questions.

Each question accepts one to four options. A single-option question is valid, though plain conversation is usually clearer when there is no meaningful choice. Invalid AskUser calls show their error in chat.

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 temporary cache file in the OS cache directory that 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.

Prefer URLs supplied by the user or discovered in files, tool output, or search results. If the URL is uncertain, search for it before fetching.

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, and Antix). 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.

Transient search failures are retried up to three times beyond the provider client’s own retries, honoring Retry-After when the wait fits within the same 90-second budget. If throttling cannot recover in time, the error advises continuing with known information or fetching a known URL instead of immediately searching again.

Opt-in tools​

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

TodoWrite​

Track progress on multi-step work with a task list. Default TUI sessions omit the pinned task list; enable it with --include-tools TodoWrite.

ViewImage​

Read a local image for the current model using file_path and optional detail. The default high detail caps the longest edge at 2000 pixels; low caps it at 768 pixels, and original preserves the resolution. Images still pass format, file-size, and decode-limit validation.

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, AskUser, WebFetch, Edit, Write, and Agent. WebSearch is added automatically when the session's provider supports native web search.

TodoWrite and ViewImage are 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 TodoWrite,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.