Tools
A “tool” is a function the agent can call inside the loop. Each tool has a JSONSchema definition, a category tag, and a Go handler. This page is the conceptual overview — for hands-on usage see the per-category guides.
How tools fit into the loop
Tools are resolved at the start of each turn, sent to the LLM as function definitions, and executed by the runner when the model emits a tool call. See Agent Loop for the full cycle.
The catalogue is assembled at startup: each builtin tool is registered in order and stamped with its semantic category. Memory tools are wired in separately, per surface.
Categories at a glance
| Category | Examples | What they do |
|---|---|---|
| System | execute_command, shell_tasks, shell_kill, write_file, open_file, download_file | Run commands and write to the local filesystem |
| FileRead | read_file, grep, glob, list_dir | Read and search the local filesystem |
| Logs | read_logs | Tail the daemon log with filtering |
| Remote | connect, connect_session, ask_machine, ask_machine_stream, ask_machines | Reach other machines |
| Board | issue_list, issue_get, issue_create, issue_update, issue_close | CRUD over the issue board |
| Meta | todo_write, skill_list, skill_run, delegate_task, task_status | Self-management and delegation |
| Help | help | Read-only help registry |
| Permissions | permissions_helper | Introspect the permission policy |
| Research | web_search, web_fetch | Routed through the model gateway; only present if SDKROUTER_API_KEY is set |
| Gen | generate_parser | Generate CSS/XPath/regex selectors |
The full list with parameters and usage notes lives in the per-category guides.
System tools
The most-used tools the agent reaches for first.
| Tool | Params | Notes |
|---|---|---|
execute_command | {command: string} | Stream-based PTY. Floor-checked for unsafe patterns. |
shell_tasks | {id?, action: start | stop | status, command?} | Long-running background tasks tracked across turns. |
shell_kill | {id: string} | Clean SIGTERM + SIGKILL fallback. |
write_file | {path: string, content: string} | Floor-checked path; atomic write via temp + rename. |
open_file | {path: string} | Renders in Desktop. No-op in CLI / SDK. |
download_file | {url: string, path: string} | Chunked; floor-checks the target path. |
FileRead tools
| Tool | Params | Notes |
|---|---|---|
read_file | {path, offset?, limit?} | Line-numbered output, 64 KiB cap, binary detection. |
grep | {path, pattern, mode: files | content | count, -i?, -n?, -A/-B/-C?} | Ripgrep-backed, 10 s timeout, respects .gitignore. |
glob | {path, glob} | Ripgrep-backed pattern match, ~1000-file limit. |
list_dir | {path, recursive?} | Shallow or recursive listing, 10k-file cap. |
Remote tools
The cross-machine surface — see Agent Communication for the full story.
| Tool | Purpose |
|---|---|
connect | Dispatcher: list, exec, whoami, share, … on a target machine. |
connect_session | Persistent multi-command session on a target. See Remote Sessions. |
ask_machine | Single remote agent call, unary. |
ask_machine_stream | Single remote agent call, streamed. |
ask_machines | Fan-out to many agents in parallel. |
Meta tools
| Tool | Purpose |
|---|---|
todo_write | Replace the visible task list. Mirrors to the Board if CMDOP_TODO_PERSIST=on and a parent issue is set. |
skill_list | Enumerate installed skills. |
skill_run | Run a skill in a sub-session with full tool access. |
delegate_task | Spawn a subagent with the parent’s model provider (or the model gateway as fallback). |
task_status | Query a subagent’s state and output snippet. |
Permissions and the floor
Every tool call from a remote agent passes through the gate. The gate consults the non-bypassable floor first, then rules, then mode default. See Permissions.
Local chat (cmdop chat, TUI, SDK on the same OAuth identity) does not go through the
gate by design — the floor still applies (it is a code-level safety net), but rule and
mode gating is skipped.
Tool definitions and JSONSchema
Each tool ships a name, a description, and a JSONSchema describing its parameters. The runner presents these to the LLM as function definitions on every turn.
{
"name": "read_file",
"description": "Read a file with pagination.",
"schema": { "...": "JSONSchema for the parameters" }
}To add a tool you ship a new daemon binary that registers it in the builtin catalogue following the same pattern the existing tools use.
Conditional tools
web_search and web_fetch are only registered when SDKROUTER_API_KEY is set.
generate_parser is wired through the parser package and may also be conditional. If the
agent says “I don’t have a web tool”, check the env var first.
Cache discipline
Tool definitions are part of the static system prefix that providers cache. Adding or removing tools mid-session invalidates the cache for that session — try not to flip optional tools on and off during a single conversation.
Tools are not user-extensible at runtime. To add a tool you ship a new daemon binary. For one-off integrations use Skills instead.
Cmdop