<>

A coding agent is only as capable as the tools it can use. Claude Code ships with roughly 40 tools — each a self-contained module that lets the LLM interact with the outside world. Read files, run commands, search code, spawn sub-agents, fetch web pages, talk to MCP servers. The breadth matters because the model can only do what you give it.

This post covers every tool category and, more importantly, the factory pattern that makes them all work.

The buildTool Pattern

Every tool is defined with the same factory function. The pattern is consistent across all 40 modules:

export const MyTool = buildTool({
  name: 'MyTool',
  aliases: ['my_tool'],
  description: 'What this tool does',
  inputSchema: z.object({
    param: z.string(),
  }),
  async call(args, context, canUseTool, parentMessage, onProgress) {
    // Execute and return { data: result, newMessages?: [...] }
  },
  async checkPermissions(input, context) { /* Permission checks */ },
  isConcurrencySafe(input) { /* Can run in parallel? */ },
  isReadOnly(input) { /* Non-destructive? */ },
  prompt(options) { /* System prompt contribution */ },
  renderToolUseMessage(input, options) { /* Terminal UI for invocation */ },
  renderToolResultMessage(content, progressMessages, options) { /* Terminal UI for result */ },
})

The design is contract-based: you implement a handful of methods, and the factory fills in sensible defaults for everything else. Most tools only need name, inputSchema, call, and prompt — the rest is optional.

Directory Structure

Each tool lives in its own directory with a standard layout:

src/tools/MyTool/
├── MyTool.ts        # Core implementation (the buildTool call)
├── UI.tsx           # Ink terminal rendering components
├── prompt.ts        # System prompt description for the LLM
└── utils.ts         # Tool-specific helpers

This self-contained structure means adding a new tool is a matter of creating one directory and registering it in src/tools.ts. The system prompt gets the prompt() output injected automatically. The UI components get rendered when the tool runs.

File System Tools

These are the most frequently used tools. They handle all file interactions:

The FileReadTool is notable for what it supports: plain text, images (multimodal), PDFs, and Jupyter notebooks. The line range parameters (offset/limit) let the model read only what it needs rather than pulling in entire files.

FileEditTool uses precise string replacement — find an exact string in the file, replace it with something else. This is safer than rewriting entire files when you only need to change a few lines.

Shell and Execution Tools

BashTool is the workhorse. It runs commands, captures stdout/stderr, and returns exit codes. The permission system pays special attention to Bash — dangerous command patterns like rm -rf / are blocked by default, and users can configure fine-grained rules like Bash(git *) to allow git commands without prompting.

Agent and Orchestration Tools

These tools let the agent spawn other agents, creating a tree of independent workers:

The AgentTool is the most interesting here. It lets the LLM say “I need to research this in parallel” and spawn a completely independent agent instance. The sub-agent gets its own tool set, its own conversation context, and streams results back when done. This is how Claude Code handles tasks like “search for bugs across the entire codebase” without blocking the main conversation.

The TeamCreateTool takes this further — it creates a coordinated group of agents that can work on different parts of a problem simultaneously. The main agent acts as a coordinator, collecting results and synthesizing a final response.

Task Management Tools

These tools implement a persistent task system within the agent:

This is a lightweight task system built into the agent. Tasks are used for background work — spawning a long-running analysis, tracking progress on multi-step operations, or deferring work that doesn’t need immediate results. The read-only / read-write split follows the same pattern as the file tools.

Web Tools

These two tools give the agent internet access. WebSearchTool performs a search query and returns results. WebFetchTool fetches a specific URL and extracts its content. Both are read-only, which means they bypass many permission checks — the model can freely search and read web content without prompting.

MCP (Model Context Protocol) Tools

MCP tools allow Claude Code to connect to external services:

MCPTool is a dynamic wrapper — it doesn’t have a fixed implementation. Instead, when you connect an MCP server, this tool adapts to expose whatever tools that server provides. The mcp__${serverName}__${toolName} naming convention prevents collisions between tools from different servers.

Integration Tools

The LSPTool is particularly powerful for code understanding. Instead of guessing what a function does, the agent can ask the LSP server directly: find the definition, find all references, get hover documentation. This gives the model the same capabilities that your IDE has.

Scheduling and Trigger Tools

These enable proactive and event-driven behavior. The agent can set up recurring tasks or respond to external triggers — useful for monitoring, periodic checks, or CI/CD integration.

Utility Tools

AskUserQuestionTool is the safety valve. When the agent encounters ambiguity — which file to edit, which approach to take, whether to proceed with a risky operation — it can ask the user directly. This bridges the gap between autonomous execution and user control.

Permission Model

Every tool invocation goes through a multi-layer permission check:

Permission rules use wildcard patterns that are surprisingly expressive:

Bash(git *)           # Allow all git commands without prompting
FileEdit(/src/*)      # Allow edits to anything in src/
FileRead(*)           # Allow reading any file

These rules can be configured at multiple levels: enterprise policy (MDM), user settings (~/.claude/settings.json), project settings (.claude/settings.json), or per-session. The most specific rule wins.

Each tool also implements its own checkPermissions() method for tool-specific logic. BashTool, for example, checks whether the command matches known dangerous patterns before even asking the user.

Tool Presets

Tools aren’t always registered as a flat list. They’re grouped into presets for different contexts:

• Read-only preset: FileReadTool, GlobTool, GrepTool, WebSearchTool, etc. — used for code review or exploration mode
• Full toolset: All tools — used during active development
• Plan mode: Only AskUserQuestionTool and read-only tools — used during planning

This contextual tool selection is important because it shapes the model’s behavior. Give it only read tools and it’ll analyze. Give it the full set and it’ll build.

What I Find Interesting

The tool system reveals a lot about how Claude Code thinks about capability boundaries. The read-only vs. destructive split is a first-class concept — it maps directly to the permission system’s default behavior. The concurrency safety flag is another dimension that the tool designer explicitly considers.

What strikes me most is the consistency. Forty tools, all built with the same factory, all following the same conventions. A new contributor can understand any tool by reading one. That’s the sign of a well-designed abstraction.

The real lesson for anyone building their own agent: invest in your tool abstraction early. The model’s behavior is shaped by the tools you give it, and a clean, consistent tool API makes the difference between an agent that’s predictable and one that’s chaotic.