> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/sanbuphy/claude-code-source-code/llms.txt > Use this file to discover all available pages before exploring further. # Tool System > How Claude Code's tool interface works — lifecycle, capabilities, rendering, and the complete built-in tool inventory. Every capability Claude Code can exercise — reading a file, running a shell command, fetching a URL, spawning a sub-agent — is a tool. Tools are the atomic unit of action in the agent loop. When the Claude API returns a `tool_use` block, the loop looks up the matching tool by name, validates the input, checks permissions, and calls it. ## The Tool interface Every tool is a TypeScript object that satisfies the `Tool` type defined in `src/Tool.ts`. The interface is divided into four groups of methods. ### Lifecycle methods These methods run in sequence for every tool invocation. | Method | Signature | Description | | -------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `validateInput()` | `(input, context) => Promise` | Reject malformed or out-of-bounds inputs before any permission check. Returns `{ result: true }` or `{ result: false, message, errorCode }`. Optional — omit to skip. | | `checkPermissions()` | `(input, context) => Promise` | Tool-specific authorization (e.g., path sandboxing for file tools). Called after the general permission system approves the call. | | `call()` | `(args, context, canUseTool, parentMessage, onProgress?) => Promise>` | Execute the tool and return the result. The `onProgress` callback streams incremental updates to the UI. | ### Capability flags These methods let the executor and permission system know how to handle a tool safely. | Method | Default | Description | | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isEnabled()` | `true` | Feature gate — return `false` to hide the tool entirely from the model. | | `isConcurrencySafe(input)` | `false` | When `true`, this tool can run in parallel with other concurrency-safe tools. Defaults to `false` (assume writes). | | `isReadOnly(input)` | `false` | When `true`, the tool has no side effects. Informs the permission dialog. | | `isDestructive(input)` | `false` | When `true`, the operation is irreversible (delete, overwrite, send). Shown prominently in the permission UI. | | `interruptBehavior()` | `'block'` | What happens when the user submits a new message while this tool runs. `'cancel'` stops it immediately; `'block'` lets it finish while the new message waits. | ### Rendering methods Tools render their own UI in the terminal (React/Ink). The loop never dictates how a tool looks. | Method | When it runs | | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `renderToolUseMessage(input, options)` | Immediately when the tool\_use block starts streaming — input may be partial. | | `renderToolUseProgressMessage(progressMessages, options)` | While the tool is executing, to show spinners and live output. | | `renderToolResultMessage(content, progressMessages, options)` | After the tool completes, to display the final result. | | `renderGroupedToolUse(toolUses, options)` | When multiple instances of the same tool ran in parallel — renders them as a group instead of individually. | | `renderToolUseRejectedMessage(input, options)` | When the user denied the tool. Optional — falls back to ``. | | `renderToolUseErrorMessage(result, options)` | When the tool threw an error. Optional — falls back to ``. | ### AI-facing methods These methods shape how the model sees the tool. | Method | Description | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt(options)` | Returns the tool's description string included in the system prompt. Can be dynamic based on current context. | | `description(input, options)` | One-line summary shown in permission dialogs and compact views. | | `mapToolResultToToolResultBlockParam(content, toolUseID)` | Serialize the tool output into the `ToolResultBlockParam` format the API expects. | | `toAutoClassifierInput(input)` | Returns a compact text representation for the auto-mode security classifier. Security-relevant tools must override this; return `''` to skip. | | `userFacingName(input)` | Short display name shown in the terminal UI. Defaults to `name`. | ## buildTool() factory All tools are created through the `buildTool()` factory function in `src/Tool.ts`. It merges safe defaults for the commonly-stubbed methods so that callers never need `?.() ?? default`. ```ts theme={null} // src/Tool.ts export function buildTool(def: D): BuiltTool { return { ...TOOL_DEFAULTS, userFacingName: () => def.name, ...def, } as BuiltTool } ``` The defaults applied by `buildTool()` are all **fail-closed** where it matters: ```ts theme={null} const TOOL_DEFAULTS = { isEnabled: () => true, isConcurrencySafe: (_input?) => false, // assume not safe isReadOnly: (_input?) => false, // assume writes isDestructive: (_input?) => false, checkPermissions: (input, _ctx?) => Promise.resolve({ behavior: 'allow', updatedInput: input }), toAutoClassifierInput: (_input?) => '', // skip classifier by default userFacingName: (_input?) => '', } ``` Every tool in the codebase goes through `buildTool()`. The factory also ensures that `userFacingName` always returns the tool's `name` even when the tool definition omits it. ## Complete tool inventory Tools that read, write, and edit files on the local filesystem. | Tool | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `FileReadTool` | Read file contents. Supports PDF, image, and text. Result size is unbounded (never persisted to disk — the tool self-bounds). | | `FileEditTool` | String-replace editing. Applies a targeted diff rather than rewriting the full file. | | `FileWriteTool` | Full file creation or overwrite. | | `NotebookEditTool` | Edit Jupyter notebook cells (`.ipynb`). | Tools for finding files and content across the codebase. | Tool | Description | | ---------------- | ------------------------------------------------------------------------------------- | | `GlobTool` | File pattern matching (`**/*.ts`). Returns matches sorted by modification time. | | `GrepTool` | Content search using ripgrep. Supports full regex. | | `ToolSearchTool` | Keyword search across the tool registry itself. Used when deferred tools are enabled. | Tools that run code or system commands. | Tool | Description | | ---------------- | ------------------------------------------------------ | | `BashTool` | Shell command execution. Most-used tool in the system. | | `PowerShellTool` | PowerShell command execution (Windows). | Tools that access the internet. | Tool | Description | | --------------- | ----------------------------------------------------- | | `WebFetchTool` | HTTP fetch, converts response to Markdown by default. | | `WebSearchTool` | Web search, returns structured results. | Tools for spawning and coordinating agents and tasks. | Tool | Description | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `AgentTool` | Spawn a sub-agent with a fresh `messages[]`. Supports `default`, `fork`, `worktree`, and `remote` modes. | | `SendMessageTool` | Send a message to a named teammate agent. | | `TeamCreateTool` / `TeamDeleteTool` | Create and delete persistent teammate agents. | | `TaskCreateTool` / `TaskUpdateTool` / `TaskGetTool` / `TaskListTool` / `TaskStopTool` / `TaskOutputTool` | File-based task graph with status tracking. | Tools for structured planning and worktree management. | Tool | Description | | ---------------------------------------- | ------------------------------------------------------ | | `EnterPlanModeTool` / `ExitPlanModeTool` | Switch to/from read-only planning mode. | | `EnterWorktreeTool` / `ExitWorktreeTool` | Bind sub-agent to an isolated git worktree. | | `TodoWriteTool` | Manage a persistent todo list for the current session. | Tools for interacting with Model Context Protocol servers. | Tool | Description | | ---------------------- | ----------------------------------------------------------------------------------------- | | `MCPTool` | Wrapper around any tool exposed by a connected MCP server. Named `mcp____`. | | `ListMcpResourcesTool` | List resources available from a connected MCP server. | | `ReadMcpResourceTool` | Read a specific resource from a connected MCP server. | Tools for user interaction, configuration, and system management. | Tool | Description | | --------------------- | ----------------------------------------------------------------- | | `AskUserQuestionTool` | Request input from the user mid-task. | | `BriefTool` | Display a brief message to the user without requesting input. | | `ConfigTool` | Read and write Claude Code settings. | | `SkillTool` | Load and invoke a skill from the `memdir/` system. | | `LSPTool` | Language server protocol queries (go-to-definition, diagnostics). | | `ScheduleCronTool` | Register a cron-style scheduled task. | ## Tool result size limits Every tool sets a `maxResultSizeChars` property. When a result exceeds this limit, the output is saved to a temporary file and Claude receives a preview with the file path instead of the full content. This prevents single large tool results from consuming the entire context window. `FileReadTool` sets `maxResultSizeChars` to `Infinity` — it self-bounds through its own read limits and persisting would create a circular `Read → file → Read` loop. ## Deferred tools When the `shouldDefer` flag is `true` on a tool, it is sent to the model with `defer_loading: true` and its full schema is omitted from the initial system prompt. The model must call `ToolSearchTool` first to locate and load the tool's schema. This reduces prompt size when many tools are registered. Set `alwaysLoad: true` on a tool to force its schema into the initial prompt regardless of deferral settings. For MCP tools, this is controlled via `_meta['anthropic/alwaysLoad']`.