> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools
> The tools the model can call while it works.
Tools are how the model acts: it reads and edits files, searches, runs commands, fetches web pages and starts other agents by calling them. This page lists every built-in tool by the name the model uses, what it does, its main parameters and its limits. You see these names in the transcript and in approval prompts, and you use them in [permission rules](/safety/permissions#permission-rules).
## Approval
Each tool has a default approval level. It decides what happens in the default `ask` [permission mode](/safety/permissions):
| Level | In `ask` mode |
| - | - |
| **Never asks** | Runs without a prompt. |
| **Asks once** | Asks the first time. After you approve, o4 doesn't ask again this session for the same target: the same file for `write`, `edit` and `notebook_edit`, the same host for `fetch`, and the same set of attached files for `brief`. For the other tools, one approval covers the tool for the rest of the session. |
| **Asks every time** | Asks before every call. |
Other modes change this:
* `accept-edits` also runs `write`, `edit` and `notebook_edit` without asking.
* `review` has the session model review each call that would ask, and asks you only if the review doesn't approve it.
* `auto` runs everything except package installs that run install-time scripts.
* `bypass` runs everything.
* `plan` blocks everything that isn't "Never asks".
[Permission rules](/safety/permissions#permission-rules) and [hooks](/extend/hooks) can allow, deny or require a prompt for a specific tool. Shell commands also run inside the [sandbox](/safety/sandbox), whatever the approval.
Every tool's text output is capped at 100,000 characters. Longer output keeps the first and last 10,000 characters with a note in between.
## Files
The file tools work inside the project directory and your home directory. They refuse credential locations in your home directory, such as `~/.ssh`, `~/.aws`, `~/.config/gh`, `~/.netrc` and o4's own `~/.o4/settings.json`. When you pass `-C`, `--add-dir`, `--sandbox read-only` or `--sandbox workspace-write`, they work only inside the working directory and the added directories, and `--sandbox read-only` also refuses every write. See [Sandbox](/safety/sandbox).
| Tool | What it does | Approval |
| - | - | - |
| `read` | Read a file with line numbers. Also reads images (PNG, JPEG, GIF, WebP, BMP) and Jupyter notebooks. | Never asks |
| `write` | Create or overwrite a file, creating parent folders as needed. | Asks once per file |
| `edit` | Replace an exact string in a file. | Asks once per file |
| `notebook_edit` | Edit a Jupyter notebook cell, or insert a new cell. | Asks once per file |
| `undo` | Undo the last `write` or `edit`, putting the file back as it was. o4 keeps the last 50 changes. `notebook_edit` changes aren't recorded, so they can't be undone this way. Not available in print mode. | Asks once |
* `file_path` (required): absolute path to the file.
* `offset`: 1-based line to start from.
* `limit`: number of lines to read. Default 2000.
Lines longer than 2000 characters are cut. Text files up to 25 MB can be read. SVG files are read as text.
* `file_path` (required): absolute path to the file.
* `content` (required): the full new content.
Writes up to 50 MB. Each write can be reversed with `undo` or `/undo`.
* `file_path` (required): absolute path to the file.
* `old_string` (required): the text to replace. It must match exactly one place in the file unless `replace_all` is set.
* `new_string` (required): the replacement.
* `replace_all`: replace every occurrence.
Works on files up to 25 MB. The approval prompt shows a preview of the change.
* `notebook_path` (required): path to the `.ipynb` file.
* `new_source` (required): the new cell content.
* `cell_id`: the cell to edit. Leave it out to insert a new cell.
* `cell_type`: `code` or `markdown`.
* `insert_after`: insert the new cell after this cell ID.
## Search
| Tool | What it does | Approval |
| - | - | - |
| `glob` | Find files by glob pattern, such as `**/*.rs`. | Never asks |
| `grep` | Search file contents with a regular expression. | Never asks |
| `ls` | List a directory's entries with their type. | Never asks |
| `git_info` | Run read-only git commands: `status`, `diff` or `log`. | Never asks |
* `pattern` (required): the glob pattern.
Returns at most 10,000 paths.
* `pattern` (required): the regular expression.
* `path`: file or folder to search. Defaults to the current directory.
* `glob`: only search files matching this pattern, such as `*.rs`.
* `case_insensitive`: ignore case.
* `context`: lines of context around each match, up to 100.
* `output_mode`: `content` (the default), `files_with_matches` or `count`.
Output stops at 200 lines. It skips `.git`, `node_modules`, binary files and files over 1 MB, respects `.gitignore`, and gives up after 30 seconds. It uses `rg` (ripgrep) when it's installed in a standard location such as `/opt/homebrew/bin` or `/usr/bin`.
* `path` (required): the folder to list.
Lists at most 10,000 entries.
* `subcommand` (required): `status`, `diff` or `log`.
* `ref`: a ref or range, such as `HEAD~3` or `main..feature`, for `diff` and `log`.
* `path`: limit `diff` to a file or folder.
* `count`: number of commits for `log`. Default 10.
It never changes the repository.
## Shell and code execution
| Tool | What it does | Approval |
| - | - | - |
| `bash` | Run a shell command and return its output. | Asks every time |
| `repl` | Run code in a persistent Python or Node.js session. | Asks every time |
| `test_run` | Run the project's tests and return structured results. | Asks once |
| `format` | Format a file with a configured formatter. | Asks once |
* `command` (required): the command to run.
* `timeout`: milliseconds. Default 600,000 (10 minutes), maximum 1,800,000 (30 minutes). `0` turns the timeout off.
* `working_directory`: folder to run the command in.
* `run_in_background`: start the command as a background task and return a task ID right away. For dev servers, watchers and other long-running commands.
* `justification`: one sentence shown on the approval prompt explaining why the command is needed.
The working directory carries over between calls; shell variables and other shell state don't. Output is limited to 100,000 characters. Commands run inside the [sandbox](/safety/sandbox). A command that runs past its time limit can be moved to the background instead of failing; see [Todos and background tasks](/guides/tasks-and-todos).
* `language` (required): `python` (runs `python3`) or `node`.
* `code` (required): the code to run.
Variables persist between calls in the same session. Each call times out after 30 seconds.
* `pattern`: only run tests whose names match.
* `file`: run the tests for one file.
* `timeout`: seconds. Default 300, maximum 1,800; `0` turns it off.
* `impacted_only`: run only the tests affected by the current changes, falling back to the full suite when unsure.
* `impact_set`: a precomputed set of impacted tests to use with `impacted_only`.
It detects the project type from `Cargo.toml`, `package.json`, `pyproject.toml`, `setup.py` or `go.mod`, and returns each test's name, status, duration, location and failure message.
* `file_path` (required): the file to format.
* `timeout`: milliseconds. Default 120,000.
Available only when you've configured at least one formatter. See [Language servers and formatters](/extend/lsp-and-formatters).
## Web
| Tool | What it does | Approval |
| - | - | - |
| `fetch` | Download a URL with HTTP GET and return the body. HTML is converted to text. | Asks once per host |
| `web_fetch` | Fetch a public page and return its text together with a question to answer about it. | Asks once |
| `web_search` | Search the web and return titles, URLs and snippets. | Asks once |
* `url` (required): the URL.
Times out after 30 seconds and reads at most 10 MB. Only public addresses are allowed; private and internal addresses are refused.
* `url` (required): a public URL.
* `prompt` (required): the question to answer about the page.
The page content is cut to about 20,000 characters.
* `query` (required): the search terms.
* `count`: number of results. Default 5, maximum 10.
Uses the Brave Search API if you've saved a `brave` key in `/config` > Providers or set `BRAVE_API_KEY`, otherwise Tavily with a `tavily` key or `TAVILY_API_KEY`, otherwise DuckDuckGo on a best-effort basis. See [Environment variables](/reference/environment-variables).
`fetch` and `web_search` follow the sandbox's host rules, so in the `guarded` tier a request to a host that isn't allowed prompts you first. See [Sandbox](/safety/sandbox#network-access).
## Planning and goals
| Tool | What it does | Approval |
| - | - | - |
| `enter_plan_mode` | Switch to plan mode, a read-only research mode. | Never asks |
| `exit_plan_mode` | Leave plan mode and restore the full tool set. | Never asks |
| `plan_create` | Save a multi-step plan as a draft for you to review. Takes a `title` and a list of `steps`. | Asks once |
| `plan_status` | Show a plan's steps and progress. | Never asks |
| `plan_modify` | Rewrite a step that is still pending. Steps that have started, finished, failed or been skipped can't be changed. | Asks once |
| `checkpoint_create` | Tag the current git `HEAD` as a checkpoint before a risky change. | Asks once |
| `checkpoint_restore` | Restore tracked files from a checkpoint tag. Refuses to overwrite uncommitted changes unless `force` is set. | Asks every time |
| `create_goal` | Start or replace the session goal. Takes an `objective` and an optional `token_budget`. | Never asks |
| `get_goal` | Read the current goal. | Never asks |
| `update_goal` | Mark the goal `complete` (with evidence) or `blocked`. | Never asks |
See [Plan mode](/guides/plan-mode) and [Goals](/guides/goals).
## Todos and background tasks
| Tool | What it does | Approval |
| - | - | - |
| `todo_write` | Replace the session todo list. Each item has `content`, `status` (`pending`, `in_progress` or `completed`) and an optional `activeForm` label. | Never asks |
| `task_list` | List background tasks with their ID, type, status and running time. | Never asks |
| `task_get` | Show one background task. | Never asks |
| `task_output` | Read the end of a task's output, 50 lines by default. | Never asks |
| `task_wait` | Wait for a task to finish, then return its status and output. Waits up to 300 seconds by default and 1800 at most. | Never asks |
| `task_create` | Register a new background task entry. | Asks every time |
| `task_update` | Change a task's state: `start`, `pause`, `resume`, `complete`, `fail`, `kill` or `notify`. | Asks every time |
| `task_stop` | Stop a running background task. | Asks every time |
See [Todos and background tasks](/guides/tasks-and-todos).
## Agents and teams
| Tool | What it does | Approval |
| - | - | - |
| `agent` | Start a subagent with its own context to handle a task. | Asks once |
| `campaign` | Start a multi-agent campaign with several workers. | Asks every time |
| `send_message` | Send a message to another agent or team. | Asks once |
| `team_create` | Create a named team with 1 to 10 members under `.o4/teams//`. It sets up the roster and mailboxes but doesn't start workers. | Asks every time |
| `team_delete` | Disband a team and remove its working directory. | Asks every time |
| `brief` | Send a summary, and optionally files, from a subagent back to the session that started it. | Asks once |
| `ask_user_question` | Ask you a question with 2 to 5 options to choose from. Only available in the interactive interface. | Never asks |
* `prompt` (required): the task for the subagent.
* `agent`: the agent definition to use, such as `Explore`, `Plan`, `General` or one of your own. Leave it out to fork the current conversation.
* `description`: a short label for the display.
* `model`: a `provider:model` reference to use instead of the current model.
* `background`: run it in the background and return a task ID right away.
* `name`: a name other agents can use to reach it with `send_message`.
* `isolation`: `worktree` runs it in its own git worktree.
* `structured_output_schema`: a JSON Schema. The subagent then gets a `StructuredOutput` tool and must call it once with a result that matches.
* `contract`: a task contract with `task`, `context`, `done_when` (a shell command and the result that proves the work is done), `touch_only` (the files it may change) and `on_failure`. When `touch_only` names more than one file, o4 checks `done_when` itself by default.
* `verify`: a shell command that replaces that check, or `false` to turn it off. A failing check goes back to the subagent, up to 2 retries.
See [Subagents](/guides/subagents).
* `description` (required): the overall goal.
* `workers` (required): the workers, each with a `role` (the agent to use) and a `task`, and optionally a `model`.
* `strategy`: `parallel` (the default), `sequential`, `map_reduce` or `collaborative`.
* `timeout_secs`: a time limit per worker. No limit if left out.
* `auto_approve`: accepted, but o4 0.2.74 doesn't use it.
See [Campaigns](/guides/campaigns).
* `summary` (required): the report, up to 100,000 characters.
* `files`: paths to attach, up to 1 MB each and 5 MB in total.
Outside a subagent, it returns the report directly.
## Code intelligence
| Tool | What it does | Approval |
| - | - | - |
| `codebase_query` | Query the project's code index for callers, callees, symbols, imports, types and files that change together. | Never asks |
| `show_architecture` | Draw the codebase as a Mermaid diagram: `modules`, `files`, or the `calls` from one function. | Never asks |
| `lsp` | Ask a language server for definitions, references, hover information, symbols, implementations or call hierarchy. | Asks once |
`codebase_query` takes an `operation` (such as `callers_of`, `find_symbol` or `changed_together`) and a `target`. The index lives in `.o4/index/codebase.db` and is built in the background when a session starts. `lsp` takes an `operation`, a `filePath`, and a 1-based `line` and `character`. It needs a language server for that file type installed; by default o4 looks for `rust-analyzer`, `typescript-language-server`, `pyright-langserver` and `gopls`. In 0.2.74 o4 doesn't send the server the `initialize` request, so standard servers such as `rust-analyzer` answer with an `LSP error -32002`. See [Code intelligence](/guides/code-intelligence) and [Language servers and formatters](/extend/lsp-and-formatters).
## Memory
| Tool | What it does | Approval |
| - | - | - |
| `memory_save` | Save a memory with `content`, a `type` (`fact`, `decision`, `pattern` or `preference`) and optional `tags`. | Asks every time |
| `memory_search` | Search memories. Returns 10 results by default, 50 at most. | Asks every time |
| `memory_list` | List memories, optionally filtered by type, including `session_summary`. Returns 20 by default, 50 at most. | Asks every time |
| `memory_forget` | Delete a memory by its `id`. | Asks every time |
Each memory tool takes a `scope`: `project` (the default, stored in `.o4/memory/memory.db`) or `global` (stored in `~/.o4/memory/global.db`). The global store is available only in a [trusted workspace](/safety/workspace-trust). See [Memory](/guides/memory).
## Skills
| Tool | What it does | Approval |
| - | - | - |
| `skill` | List skills (no parameters), search them with `query`, or load one's instructions with `name`. Includes skills from installed plugins. | Never asks |
See [Skills](/extend/skills).
## MCP
| Tool | What it does | Approval |
| - | - | - |
| `list_mcp_resources` | List the resources an MCP server offers. Takes a `server` name. | Never asks |
| `read_mcp_resource` | Read one resource by `server` and `uri`. | Asks every time |
| MCP server tools | Each tool from a connected MCP server, named `__`, for example `github__create_issue`. | Asks once per server |
| `tool_search` | Search the MCP tools that were held back, and load them. Takes a `query` and optional `max_results` (default 5). | Never asks |
If your built-in and MCP tools add up to more than 64, o4 doesn't send the MCP tools to the model up front. It adds `tool_search` instead, and the model loads MCP tools as it needs them. See [MCP servers](/extend/mcp).
## Worktrees
| Tool | What it does | Approval |
| - | - | - |
| `enter_worktree` | Create a git worktree for the session and move into it. Takes an optional `name`. | Asks once |
| `exit_worktree` | Leave the worktree and go back to the original folder. `merge` merges the changes first; `force` discards uncommitted changes. | Asks once |
## Other tools
| Tool | What it does | Approval |
| - | - | - |
| `sleep` | Wait for `seconds`, from 0.1 to 300. | Never asks |
| `harness_audit` | Check `.o4/harness.toml` for problems, without changing files. See [Harness guides and sensors](/extend/harness). | Never asks |
| `synthetic_output` | Return JSON `data` after checking it against a JSON `schema`. | Asks once |
| `remote_trigger` | Send a `prompt` to a remote agent endpoint (`target`, a URL) with HTTP POST, optionally with a `model`. Private and internal addresses are refused. | Asks every time |
## CodeMode
| Tool | What it does | Approval |
| - | - | - |
| `exec` | Run a JavaScript program that calls o4's other tools as functions. Offered only when CodeMode is on. | Never asks; each tool call inside asks as usual |
| `wait` | Collect the result of an `exec` program that's still running. Offered only when CodeMode's `background` option is on. | Never asks |
See [CodeMode](/extend/codemode).
## Where each tool is available
Not every tool is offered in every kind of session:
* **Plan mode.** The model can only use `read`, `glob`, `grep`, `ls`, `fetch`, `task_create`, `task_update`, `task_list`, `enter_plan_mode` and `exit_plan_mode`. Other tools are hidden from it, and a call to one is blocked. See [Plan mode](/guides/plan-mode).
* **Print mode** (`o4 -p`). There's no one to ask, so `ask_user_question` isn't offered, and neither are `undo`, `todo_write`, the `task_*` tools, the `plan_*`, `checkpoint_*` and goal tools, `lsp`, `format`, `list_mcp_resources`, `read_mcp_resource` and `tool_search`. MCP server tools are still offered. See [Print mode and scripting](/guides/print-mode).
* **Subagents.** A subagent gets `read`, `glob`, `grep`, `ls`, `write`, `edit`, `bash`, `fetch`, `web_search`, `git_info` and your MCP server tools, narrowed by its agent definition, plus `agent` when its definition allows it, and `StructuredOutput` when it was started with a `structured_output_schema`. Inside a subagent, MCP server tools ask every time. A subagent started without an `agent` type, a fork, gets the same tools as the session that started it. See [Subagents](/guides/subagents).
* **Daemon runs.** When a client of the [o4 daemon](/extend/daemon) starts a run with an output schema, the model also gets a `structured_output` tool whose input is that schema. A call that doesn't match the schema returns an error to the model, and a run that ends without a valid call fails with `model did not produce valid structured output`.
* **Configuration.** `format` needs at least one formatter, and `tool_search` appears only when MCP tools were held back.
## Plugin tools and turning tools off
Installed [plugins](/extend/plugins) can add their own tools. Plugin tools ask for approval every time, and a plugin tool with the same name as a built-in tool isn't added. To leave tools out of the model's tool set in a project, built-in or MCP, list their names under `disabled_tools` in the `[scout]` section of `.o4/config.toml`; `/scout` can write this for you. This applies to the interactive interface. See the [configuration reference](/reference/configuration).