Home › Concepts › Tool System Architecture

Tool System Architecture

Claude Code's tool system is the interface between the LLM's intentions and the real world. 40+ tools covering file operations, search, execution, web access, task management, and inter-agent communication. The architecture prioritizes cache preservation, parallel execution, and lazy loading.

The buildTool Factory

Every tool is created through buildTool(), a factory function that standardizes: - Tool name, description, and parameter schema (for the model's tool-use interface) - isConcurrencySafe flag (can this tool run in parallel with others?) - Permission requirements (which permission mode allows this tool?) - Tool-specific validation and execution logic

Tool Categories

File operations: FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool Execution: BashTool, PowerShellTool, REPLTool Web: WebFetchTool, WebSearchTool MCP: MCPTool, ListMcpResourcesTool, ReadMcpResourceTool, McpAuthTool Agent coordination: AgentTool, TeamCreateTool, TeamDeleteTool, SendMessageTool Task management: TaskCreate, TaskGet, TaskList, TaskUpdate, TaskOutput, TaskStop Session: EnterPlanModeTool, ExitPlanModeTool, EnterWorktreeTool, ExitWorktreeTool Utilities: ToolSearchTool, NotebookEditTool, SleepTool, ConfigTool, BriefTool Special: SyntheticOutputTool (internal), RemoteTriggerTool, ScheduleCronTool

The Streaming Tool Executor

Tools execute as the API streams them in — the moment a complete tool-use block arrives, execution begins, even if the model is still generating additional tool calls. Tools marked isConcurrencySafe run in parallel. Results are buffered and emitted in request order, keeping the conversation coherent.

The agent loop itself is an async generator: streaming tokens flow through yield, tool calls are naturally recursive (another iteration of the same loop), interruption is clean (single AbortController cancels the whole generator), and budget control is trivial (check maxTurns or maxBudget at each iteration boundary).

Cache-Aware Tool Registration

Tool registration order matters for prompt cache economics: 1. Built-in tools — registered first, form the cached prefix 2. MCP tools — sorted alphabetically, appended after built-ins, never interleaved

This partitioning preserves the expensive built-in prefix cache when MCP servers change. Adding/removing an MCP server invalidates MCP tool cache but preserves the built-in prefix.

Lazy Loading (ToolSearch)

With 40+ built-in tools and potentially dozens of MCP tools, loading all tool schemas into every request is expensive. ToolSearchTool provides lazy loading: deferred tools appear by name only (no parameter schema). The model calls ToolSearch to fetch full schemas on demand, paying the context cost only for tools it actually needs.

Tool Result Storage

Large tool outputs are persisted to temporary disk files rather than kept in memory. The conversation holds a reference (file path), not the content. This prevents memory bloat during long sessions with hundreds of file reads.

Design Tensions

  1. Parallelism vs. ordering — concurrent execution is faster but results must be emitted in order to maintain conversation coherence
  2. Lazy loading vs. availability — ToolSearch reduces token cost but adds a round-trip before first use of any deferred tool
  3. Cache preservation vs. flexibility — tool registration order is locked to preserve cache, limiting dynamic tool management