Skip to slide
045 / 221

CH 03 · Tool Design · 18/18

Read as one page

Read the source yourself

Four stops, in order. Each one shows an idea from this chapter in code the slides above did not quote.

  1. Scoping tools to the surface. Gemini CLI, packages/core/src/tools/tool-registry.ts, method isActiveTool. 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 read getFunctionDeclarations, 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.
  2. Errors the model should see, and errors it should not. Codex, codex-rs/core/src/tools/registry.rs, function dispatch_any_with_state. A call to a tool name Codex does not know becomes FunctionCallError::RespondToModel with the message unsupported call: <name>. A known tool called with the wrong kind of payload becomes FunctionCallError::Fatal. Now search parallel.rs for FunctionCallError::Fatal: a fatal error turns into CodexErr::Fatal and 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.
  3. Workflow encoded in a description. Gemini CLI, model-family-sets/gemini-3.ts, entry google_web_search. The description ends by telling the model to follow up with web_fetch when a result needs deeper analysis: tool B follows tool A, in the same repo, on the Gemini 3 tool set.
  4. How tool guidelines reach the prompt. pi, packages/coding-agent/src/core/system-prompt.ts, function buildRules. 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.