Tool Design & Rules
Tool design rules
The four mandatory rules for adding or editing tools (build-time contract from reasoning_guide(topic=tool_generate), exposed to external agents as tool_generate_guide; ongoing quality checked by the code-reviewer skill):
- Name is the only semantic carrier — stub-tool first calls only see the name; description and params arrive on the second round
- Description is exactly 3 lines, 60-200 chars — What (core action) / When (trigger vs alternatives, e.g.
use for X; Y for Z) / Precondition (key constraint, omit if none). No filler, no bold, no output-schema dump. - English only — Chinese only appears in user-facing handler return messages
- Optional fields must declare a
default— handlers still defend against nil/missing
Trigger conditions and comparisons with similar tools are required in the When line, not forbidden — a description with only the core action and no trigger signal is treated as incomplete. Parameter descriptions must cover How/When/Example, and a non-trivial type (object/array/enum) under 20 chars is incomplete.
Tool concurrency markers
toolRegister.Def carries five behavioral flags:
| Flag | Effect |
|---|---|
AlwaysAllow |
Exempt from the confirm gate (read-only tools) |
AlwaysLoad |
Schema is present on the first round instead of needing search_tools activation |
Concurrent |
Opts into Pass 2 fan-out (one goroutine per call) |
FireAndForget |
Result is not awaited by the loop (e.g. remember_error) |
Timeout |
Per-tool override of the 1-minute default |
Adding Concurrent: true requires both "no side effects" and "upstream allows parallelism". The current concurrent set is listed on the Execution Engine page.
Tool timeout matrix
Each adapter has its own timeout, layered with the executor-side ceiling:
| Adapter | Default | Configurable | Where |
|---|---|---|---|
Built-in (toolRegister.Dispatch) |
1 min | Def.Timeout per tool |
tool registration |
Script (script_*) |
5 min (300s) | tool.json "timeout": <seconds> |
extensions/scripts/<name>/tool.json |
API (api_*) |
60s | doc.Endpoint.Timeout; hard cap 300s |
extensions/apis/<name>.json |
| MCP HTTP | 60s http.Client.Timeout + 1 min outer dispatch |
n/a | MCP server config |
| MCP stdio | 1 min outer dispatch only | n/a | MCP server config |
Long-running tools (script + API) emit running name=... elapsed=Ys/Zs to the daemon log every 30s for visibility.
Long-running built-ins declare their own caps at registration: invoke_subagent = MaxSubagentTimeoutMin (30 min), download_file = 10 min, transcribe_media = 5 min, fetch_page / search_web = 90 s, list_rag / search_rag = 15 s, open_file = 15 s.
Credential auto-heal
store_secret is AlwaysLoad: true so the agent sees it on the first round. When a downstream tool returns a missing-key or invalid-credential error (401 / 403 / invalid api key / expired token), the system prompt's §10 Credential auto-heal SOP directs the agent to call store_secret (which captures the new value through masked input — the value never reaches the LLM) and retry the original tool. Capped at two store_secret rounds per failing tool per turn.