ruvector/docs/research/claude-code-rvsource/02-tool-system.md

Claude Code CLI: Tool System Architecture

Built-in Tools

Claude Code registers tools with the Anthropic Messages API using the standard tool_use / tool_result content block protocol.

Tool Registry

The internal tool name map (display names for UI):

{
  Read: "Reading",
  Write: "Writing",
  Edit: "Editing",
  MultiEdit: "Editing",
  Bash: "Running",
  Glob: "Searching",
  Grep: "Searching",
  WebFetch: "Fetching",
  WebSearch: "Searching",
  Task: "Running task",
  FileReadTool: "Reading",
  FileWriteTool: "Writing",
  FileEditTool: "Editing",
  GlobTool: "Searching",
  GrepTool: "Searching",
  BashTool: "Running",
  NotebookEditTool: "Editing notebook",
  LSP: "LSP"
}

Tool Name Variables (Internal References)

Variable	Tool Name
Yq	Bash
Bq	Read
c7	Write
wK	Edit
Gf	Glob
f9	Grep
sw	WebFetch
nE	WebSearch
IL	NotebookEdit
WX	ToolSearch
lI	TodoWrite
nj	Skill
tXH	SendUserMessage

Tool Categories

File Operations:

• Read / FileReadTool -- Read files, images, PDFs, notebooks
• Write / FileWriteTool -- Create or overwrite files
• Edit / FileEditTool -- String replacement edits in existing files
• MultiEdit -- Multiple edits in a single tool call
• NotebookEdit / NotebookEditTool -- Jupyter notebook cell operations

Search:

• Glob / GlobTool -- File pattern matching (fast, sorted by mtime)
• Grep / GrepTool -- Content search via ripgrep with regex support

Execution:

• Bash / BashTool -- Shell command execution with sandbox support
• Task -- Spawn subagent for parallel work

Web:

• WebFetch -- HTTP fetch with content extraction
• WebSearch -- Web search integration

Agent/System:

• ToolSearch -- Discover deferred tools (MCP tools loaded on demand)
• Skill -- Execute registered skills/slash commands
• SendUserMessage -- Agent-to-user communication (brief mode)
• TodoRead / TodoWrite -- Task list management
• EnterWorktree / ExitWorktree -- Git worktree management
• LSP -- Language Server Protocol integration

Tool Schema Pattern

Each tool is defined with:

{
  name: "ToolName",
  description: `Template literal with ${otherToolNames} interpolated`,
  input_schema: {
    type: "object",
    properties: { ... },
    required: [ ... ]
  }
}

Tool descriptions dynamically reference other tool names so the model knows the full toolkit available. For example, Bash's description says "Avoid using this tool to run grep, find, cat... instead use the appropriate dedicated tool."

Tool Validation

Tools have category-based validation:

• filePatternTools: ["Read", "Write", "Edit", "Glob", "NotebookRead", "NotebookEdit"]
  • Validate file paths
• bashPrefixTools: ["Bash"]
  • Validate command prefixes against allowed/denied patterns
• customValidation: Per-tool validators (e.g., WebSearch rejects wildcards)

Tool Permission Flow

User prompt -> Model generates tool_use -> Permission check -> Execute -> tool_result

Each tool call goes through the permission system before execution. See 04-permission-system.md for details.

MCP Tool Integration

MCP (Model Context Protocol) tools extend the built-in set:

• MCP tools are prefixed with mcp__<server-name>__<tool-name>
• ReadMcpResourceTool -- Read MCP server resources
• MCP tools can be deferred (loaded on-demand via ToolSearch)
• Tool output size controlled by MAX_MCP_OUTPUT_TOKENS env var
• Large outputs can be saved to files (ENABLE_MCP_LARGE_OUTPUT_FILES)

Tool Concurrency

CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY controls parallel tool execution. Multiple tool calls in a single response can execute concurrently.

Content Block Types

The API supports these content block types in messages:

Type	Direction	Purpose
text	Both	Text content
thinking	Response	Extended thinking
redacted_thinking	Response	Safety-redacted thinking
tool_use	Response	Tool call request
tool_result	Request	Tool execution result
image	Request	Image content
file	Request	File content
server_tool_use	Response	Server-side tool calls
web_search_tool_result	Response	Web search results
code_execution_tool_result	Response	Code execution results
mcp_tool_use	Response	MCP tool calls
mcp_tool_result	Response	MCP tool results