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.
Copy & share
Loading sections…
Connect MCP or install the Empryo skillSection exports contain only that heading’s content. Markdown and text links fetch the selected content directly, without the rest of the page.
<!-- 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 for why single-call tools beat step-by-step instructions, and Permissions & reach 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. | 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
{ "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.