CH 03 · Tool Design · 18/18
Read as one pageRead the source yourself
Four stops, in order. Each one shows an idea from this chapter in code the slides above did not quote.
- Scoping tools to the surface. Gemini CLI,
packages/core/src/tools/tool-registry.ts, methodisActiveTool. Find each check that hides a registered tool from the model. Two to look for: the MCP resource tools disappear when no connected server offers resources (MCP, the Model Context Protocol, is a standard way to plug outside tool servers into an agent), and of the enter and exit plan-mode pair, only the one that makes sense right now is offered. Then readgetFunctionDeclarations, the next method in that file, and see how Plan Mode rewrites the description of the write and edit tools ("ONLY FOR PLANS") instead of hiding them. - Errors the model should see, and errors it should not. Codex,
codex-rs/core/src/tools/registry.rs, functiondispatch_any_with_state. A call to a tool name Codex does not know becomesFunctionCallError::RespondToModelwith the messageunsupported call: <name>. A known tool called with the wrong kind of payload becomesFunctionCallError::Fatal. Now searchparallel.rsforFunctionCallError::Fatal: a fatal error turns intoCodexErr::Fataland propagates up, while every other error is turned into a tool result for the model. Ask yourself which failures a model could fix by trying again, and which it could not. - Workflow encoded in a description. Gemini CLI,
model-family-sets/gemini-3.ts, entrygoogle_web_search. The description ends by telling the model to follow up withweb_fetchwhen a result needs deeper analysis: tool B follows tool A, in the same repo, on the Gemini 3 tool set. - How tool guidelines reach the prompt. pi,
packages/coding-agent/src/core/system-prompt.ts, functionbuildRules. Each selected tool's guidelines become bullet rules with duplicates removed, and there is a fallback for when bash or PowerShell is present and grep, find, and ls are not: use the shell for listing and searching.
Exercise: rewrite Codex's update_plan as a pi-style TypeBox schema. pi's read.ts already uses Type.Union and Type.Literal, which is enough to express the three statuses. Decide where "at most one step in progress" should live and how you would reject extra keys. Then compare your version with the Rust types in codex-rs/protocol/src/plan_tool.rs, and note every rule that your schema enforces and theirs does not, or the other way round.
Finished this idea?
Your learning progress stays in this browser.