<!-- Markdown mirror. Canonical: https://empryo.com/docs/reference/tools -->

# Tools

> Every tool on the agent's belt: what it does, which surface it needs, which mode belts carry it, and how to switch one off.

<!-- GENERATED by scripts/build-tools-doc.ts — edit packages/tools/src/constants.ts, then run `bun run docs:tools`. -->

The belt is bigger than what ships in a single request. Core tools are resident on
every call; the rest load on demand through `request_tools`, so an unused tool costs
nothing per turn (~300 tokens of schema each when resident).

See [compound tools](/docs/concepts/compound-tools) for why single-call tools beat
step-by-step instructions, and [Permissions & reach](/docs/reference/configuration#agent-features)
for turning one off.

## The catalog

This is what `/tools` lists — 45 tools, each disable-able unless marked always on.

| Tool | What it does | Notes |
|------|--------------|-------|
| `request_tools` | Let the agent list/load/unload tools on demand (saves ~300 tokens/tool/call) |  |
| `skills` | Let the agent search, install, and load skills from skills.sh |  |
| `read` | Read file contents with optional line range or symbol target | always on |
| `edit_file` | Edit, create, or write files with line-anchored matching | always on |
| `multi_edit` | Apply multiple edits to one or more files atomically | always on |
| `undo_edit` | Undo recent edits to a file |  |
| `grep` | The Genome's repo-wide search (symbol context, count mode, dep search) | always on |
| `find` | The Genome's file/symbol finder: fuzzy ranked, globs, concept overview | always on |
| `shell` | Execute shell commands (background:true for servers/watchers/long builds) | always on |
| `shell_jobs` | Background shell jobs: list, status, log tail/poll, wait, stop |  |
| `advisor` | Second opinion over this conversation from a tool-less model |  |
| `link` | Live link to other agents: list, send, ask (blocking), reply, broadcast, inbox, history |  |
| `orchestrate` | Multi-agent graphs with loops: validate, save, run, watch, resume, stop |  |
| `routine` | Scheduled routines (cron): list, add, remove, enable, run now |  |
| `project` | Auto-detected lint, format, test, build, typecheck across 23 ecosystems | always on |
| `explore` | Delegate a read-only question to a solo explore agent (fg or background) |  |
| `dispatch` | Spawn parallel subagents for multi-file tasks |  |
| `background_dispatch` | Spawn a detached agent that runs while you keep working |  |
| `background_status` | Check background agents (non-blocking) |  |
| `background_stop` | Abort a running background agent |  |
| `background_await` | Block until background agents finish and collect results |  |
| `agent_send` | Send a follow-up instruction to a running subagent (dispatch id or bg-N) |  |
| `agent_create` | Create or update a custom agent definition, dispatchable immediately |  |
| `plan` | Create an implementation plan for large changes (7+ files) |  |
| `update_plan_step` | Update a plan step's status during execution |  |
| `ask_user` | Ask the user a question and wait for their response |  |
| `navigate` | LSP symbol lookup: definitions, references, callers, type hierarchies | always on |
| `genome_query` | Chain search → filter → deps → outline → read in one Genome call | always on |
| `genome_analyze` | Codebase analysis: file profiles, dead code, packages, symbol queries | always on |
| `genome_impact` | Dependency graph: dependents, dependencies, cochanges, blast radius | always on |
| `genome_vision` | Display images and videos inline in chat (PNG, JPG, GIF, video files/URLs) | TUI only |
| `analyze` | LSP diagnostics, type info, outline, code actions on a file | always on |
| `web_search` | Search the web for documentation, APIs, error messages |  |
| `find_model` | Fuzzy-search the model catalog: providers, models, key state |  |
| `find_agent` | Fuzzy-search custom agent definitions: name, purpose, mode, model |  |
| `fetch_page` | Fetch readable pages or make structured HTTP probes |  |
| `git` | Git operations: status, diff, log, commit, push, pull, stash, branch |  |
| `list_dir` | List directory contents (supports multiple paths + recursive depth in one call) |  |
| `refactor` | Code transforms: extract, format, organize imports, rename/move symbols and files |  |
| `memory` | Read/write persistent memories across sessions | always on |
| `editor` | Open file in embedded Neovim editor | TUI only, needs the `neovim` addon |
| `task_list` | Create and track tasks for the current session |  |
| `settings` | Read/change Empryo's own settings — the running surface applies and repaints |  |
| `ast_edit` | Surgical AST editing for TS/JS — prefer over edit_file/multi_edit | always on |
| `structural_edit` | Polyglot AST find/rewrite via ast-grep — non-TS/JS (Go, Rust, Python, …) |  |

## Host and protocol tools

Injected by the surface or the mode rather than the catalog, so they do not appear in `/tools`.

| Tool | What it does |
|------|--------------|
| `final_response` | Marks where the final answer starts, so it streams instead of hiding in the tool rail |
| `respond_to_steering` | Reply to one steering message in place, beside the message it answers |
| `explore_script` | Run one read-only script against the workspace API and return only its summary |
| `code_script` | One script that gathers, edits by symbol span in any language, verifies and reports |
| `council` | Convene 2–4 seats with their own briefs to debate one topic in a shared room |
| `cells` | Read, write and drive Cells — the agent's half of Cells & Morphs |
| `browser` | Drive the embedded Chromium: snapshot, click, type, screenshot, inspect, audit |
| `rename_tab` | Rename this tab when the work changes fundamentally |
| `model` | Look up and switch the model a lane runs on |
| `spark` | Delegate a read-only slice to a Spark agent |
| `agent` | Delegate work to a custom agent definition |
| `reviewer` | Judge the current state of the repo and return PASS, FAIL or PARTIAL |

## Mode belts

A mode is a belt, not a personality. This is which tools each one carries.

| Belt | Why | Tools |
|------|-----|-------|
| **Core** | Resident on every call — schemas ship with every request. | `read`, `edit_file`, `multi_edit`, `grep`, `find`, `shell`, `project`, `memory` |
| **Always available** | Protocol markers. Present in every mode, never disable-able. | `final_response`, `respond_to_steering`, `web_search`, `fetch_page`, `link`, `advisor`, `find_model`, `rename_tab` |
| **Undisable-able** | `/tools` hides these and hosts drop them from any incoming disable list. | `read`, `edit_file`, `multi_edit`, `grep`, `find`, `shell`, `project`, `memory`, `genome_query`, `genome_analyze`, `genome_impact`, `navigate`, `analyze`, `ast_edit`, `final_response`, `respond_to_steering` |
| **Restricted modes** | architect, socratic, challenge — read and analyse, no edit/shell/git. | `read`, `grep`, `find`, `genome_analyze`, `genome_impact`, `list_dir`, `web_search`, `explore`, `explore_script`, `editor`, `navigate`, `analyze`, `memory`, `skills`, `fetch_page`, `ask_user`, `plan`, `update_plan_step` |
| **Plan execution** | The belt a plan runs with. | `read`, `edit_file`, `code_script`, `undo_edit`, `multi_edit`, `task_list`, `list_dir`, `shell`, `shell_jobs`, `project`, `grep`, `find`, `navigate`, `analyze`, `git`, `editor`, `refactor`, `update_plan_step`, `memory`, `skills`, `genome_analyze`, `genome_impact` |
| **Morph mode** | The Cellwright belt — see [Cells & Morphs](/docs/tools/morphs). | `read`, `grep`, `find`, `list_dir`, `explore_script`, `navigate`, `genome_query`, `genome_analyze`, `genome_impact`, `analyze`, `edit_file`, `multi_edit`, `undo_edit`, `web_search`, `fetch_page`, `git`, `ask_user`, `task_list`, `memory`, `model`, `spark`, `agent`, `reviewer`, `find_model`, `find_agent`, `cells`, `rename_tab` |
| **Duck mode** | Repo-blind: the web and the agent link only. | `web_search`, `fetch_page`, `link`, `advisor`, `find_model`, `rename_tab` |
| **Orchestrate mode** | The graph engineer — designs and drives runs, never edits directly. | `read`, `grep`, `find`, `list_dir`, `explore_script`, `navigate`, `genome_query`, `genome_analyze`, `genome_impact`, `web_search`, `fetch_page`, `ask_user`, `task_list`, `memory`, `find_agent`, `find_model`, `orchestrate`, `routine`, `background_status`, `background_stop`, `background_await`, `agent_send`, `shell_jobs`, `link`, `council`, `rename_tab` |

## Switching tools off

```json
{ "disabledTools": ["shell", "git"] }
```

`/tools` on the TUI and **My tools → Permissions & reach** on the desktop write the
same key. Tools marked *always on* are stripped from any disable list, including a
hand-edited config: disabling `read` or `grep` does not make an agent safer, it makes
it fail three turns later in ways that look like a model problem.

## Next

#### Configuration

Every config field, including `disabledTools` and the agent feature flags.

#### Commands

Every slash command on every surface.