Every agent in Fabro has access to a set of built-in tools for interacting with the codebase and environment. Tools execute inside the agent’s sandbox — whether that’s the local machine, a Docker container, or a Daytona VM — so the same tool calls work identically regardless of provider.
The tools described on this page apply to the API backend (the default). When using the CLI backend, the external CLI tool (claude, codex, or gemini) provides its own tools — Fabro’s built-in tools are not used. | Tool | Category | Description |
|---|
shell | shell | Run shell commands via /bin/bash -c |
read_file | read | Read file contents with optional offset and limit |
write_file | write | Create or overwrite a file |
grep | read | Search file contents with regex patterns |
glob | read | Find files by name pattern |
web_search | shell | Search the web via Brave Search |
web_fetch | shell | Fetch and optionally summarize a URL |
| Tool | Providers | Description |
|---|
edit_file | Anthropic, Gemini | Replace a string in a file (find-and-replace) |
apply_patch | OpenAI | Apply a v4a-format patch to modify files |
read_many_files | Gemini | Read multiple files in a single call |
list_dir | Gemini | List directory contents with depth control |
shell
Executes a shell command via /bin/bash -c in the sandbox’s working directory.
| Parameter | Type | Required | Description |
|---|
command | string | yes | The shell command to execute |
timeout_ms | integer | no | Timeout in milliseconds |
description | string | no | Description of what the command does |
read_file
Reads a file and returns its contents with line numbers.
| Parameter | Type | Required | Description |
|---|
file_path | string | yes | Absolute path to the file |
offset | integer | no | 1-based line number to start reading from |
limit | integer | no | Number of lines to read (default: 2000) |
1 | fn main() {), making it easy for agents to reference specific lines when editing.
write_file
Creates or overwrites a file.
| Parameter | Type | Required | Description |
|---|
file_path | string | yes | Absolute path to the file |
content | string | yes | Content to write |
The read-before-write guardrail prevents writing to existing files that haven’t been read first. Writing to new files is always allowed. edit_file
Replaces a string in an existing file. Available for Anthropic and Gemini providers.
| Parameter | Type | Required | Description |
|---|
file_path | string | yes | Absolute path to the file |
old_string | string | yes | The string to find |
new_string | string | yes | The replacement string |
replace_all | boolean | no | Replace all occurrences (default: false) |
old_string is not found, the tool returns an error. If multiple occurrences exist and replace_all is false, the tool returns an error asking for more context or to set replace_all.
The tool reads the file internally before writing, so it satisfies the read-before-write guardrail automatically.
grep
Searches file contents with a regex pattern, powered by ripgrep in the sandbox.
| Parameter | Type | Required | Description |
|---|
pattern | string | yes | Regex pattern to search for |
path | string | no | Path to search in (default: .) |
glob_filter | string | no | Glob pattern to filter which files are searched |
case_insensitive | boolean | no | Case-insensitive search (default: false) |
max_results | integer | no | Maximum number of results |
file:line:content lines. Files that appear in grep results are marked as “read” for the read-before-write guardrail.
glob
Finds files matching a glob pattern.
| Parameter | Type | Required | Description |
|---|
pattern | string | yes | Glob pattern to match files (e.g. **/*.rs) |
path | string | no | Directory to search in (default: working directory) |
Unlike grep, glob does not mark files as read for the read-before-write guardrail. To modify a file found via glob, the agent must read it first.
web_search
Searches the web using the Brave Search API.
| Parameter | Type | Required | Description |
|---|
query | string | yes | Search query |
max_results | integer | no | Maximum results (default: 5, max: 20) |
BRAVE_SEARCH_API_KEY environment variable. Returns numbered results with title, URL, and description.
web_fetch
Fetches content from a URL and optionally summarizes it with an LLM.
| Parameter | Type | Required | Description |
|---|
url | string | yes | URL to fetch (must be http:// or https://) |
prompt | string | no | A question about the page content; returns a concise answer instead of the full page |
timeout_ms | integer | no | Timeout in milliseconds (default: 30000, max: 60000) |
prompt is provided and a summarizer model is configured, the fetched content is passed to a lightweight LLM call that returns a concise answer.
apply_patch
Applies a v4a-format patch to create, update, or delete files. Available for OpenAI providers.
| Parameter | Type | Required | Description |
|---|
patch | string | yes | Patch content in v4a format |
*** Begin Patch / *** End Patch delimiters with *** Add File:, *** Delete File:, and *** Update File: operations.
read_many_files
Reads multiple files in a single tool call. Available for Gemini.
| Parameter | Type | Required | Description |
|---|
paths | string[] | yes | Array of absolute file paths |
=== path ===.
list_dir
Lists directory contents with optional depth control. Available for Gemini.
| Parameter | Type | Required | Description |
|---|
path | string | yes | Directory path to list |
depth | integer | no | Depth of listing (default: 1) |
/ in the output.
Read-before-write guardrail
Fabro wraps every sandbox in a ReadBeforeWriteSandbox decorator that tracks which files the agent has seen. The rules are:
- Writing to a new file (one that doesn’t exist yet) is always allowed
- Writing to an existing file requires that the agent has previously read it via
read_file or seen it in grep results
- Deleting an existing file follows the same rule as writing
If an agent attempts to write to an existing file it hasn’t read, the tool returns an error:
Cannot write to 'src/main.rs': file exists but has not been read.
Use read_file to read the file before writing to it.
src/main.rs (relative) and /workspace/src/main.rs (absolute) both satisfy the check.
Parallel execution
When an LLM returns multiple tool calls in a single response, Fabro can execute them in parallel. Independent tool calls run concurrently, while the results are collected in order. If the agent session is cancelled, pending tool calls return a “Cancelled” error.
Argument validation
Before executing a tool, Fabro validates the arguments against the tool’s JSON Schema. Invalid arguments are rejected with a descriptive error before the tool executor runs.
Output truncation
Tool output is truncated before being stored in conversation history to prevent context window bloat. Each tool has default limits:
| Tool | Character limit | Truncation mode |
|---|
grep | 30,000 | Tail (keep end) |
glob | 20,000 | Tail |
edit_file | 10,000 | Tail |
apply_patch | 10,000 | Tail |
write_file | 1,000 | Tail |
| Other tools | No default limit | Head + tail |
SessionConfig.tool_output_limits.
Error handling
When a tool call fails, the error is returned to the agent as a tool result with an error flag — the agent loop continues. Tool errors do not fail the stage. The LLM sees the error message and decides how to respond: retry the call, try an alternative approach, or move on.
Common error cases:
| Error | Cause |
|---|
| Unknown tool | The agent called a tool that doesn’t exist |
| Argument validation failure | Arguments don’t match the tool’s JSON Schema |
| File not found | The target file doesn’t exist |
| Command timeout | A shell command exceeded its timeout |
| Read-before-write | The agent tried to write to a file it hasn’t read (see guardrail) |
Timeouts
Shell commands have two timeout settings:
| Setting | Default | Description |
|---|
default_command_timeout_ms | 10,000 (120,000 for Anthropic) | Timeout when the agent doesn’t specify one |
max_command_timeout_ms | 600,000 (10 minutes) | Hard cap regardless of what the agent requests |
timeout_ms parameter, but it’s always capped at the maximum.
Extending with MCP
Additional tools can be added via MCP servers. MCP tools appear alongside built-in tools in the agent’s tool set and follow the same permission and execution model.
Further reading
