The Tools System: Teaching Claude How to Touch the World

If the query engine is Claude Code's brain, tools are its hands. An LLM on its own is just a text generator confined to a vacuum. To interact with your file system, run scripts, or connect to the internet, it needs tools. Let's dive into exactly how Anthropic engineered an incredibly robust, deeply typed, and dynamically loaded tool ecosystem for Claude.

The Root: Tool.ts Interface

If you have ever built a simple GPT wrapper, you might have just defined tools as a massive JSON array of schemas. Anthropic took a much more sophisticated, object-oriented approach. In claude-code-src/Tool.ts, every single tool implements a generic interface: Tool<Input, Output, Progress>.

Why this complexity? Because in a terminal application, a tool is not just a schema. It needs to know how to validate inputs, check user permissions before doing something dangerous, render progress spinners using React (Ink), and serialize its output cleanly back to the API. Tying all these concerns perfectly into one single object eliminates an enormous amount of boilerplate and hard-to-track UI bugs.

// Tool.ts  - The architecture of a tool (from the actual source)
export type Tool<
  Input extends AnyObject = AnyObject,
  Output = unknown,
  P extends ToolProgressData = ToolProgressData,
> = {
  readonly name: string
  readonly inputSchema: Input

  // The actual action takes place here:
  call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>

  // Crucial Security Flags:
  isConcurrencySafe(input): boolean   // Can multiple instances run at once?
  isReadOnly(input): boolean          // Does it change anything on disk?
  isDestructive?(input): boolean      // Could it cause irreversible damage?
  
  // Terminal React UI (Ink):
  renderToolUseMessage(input, options): React.ReactNode
  renderToolResultMessage?(output, progressMessages, options): React.ReactNode

  // Memory bounds:
  maxResultSizeChars: number          // When to spill output to a tmp file
  readonly shouldDefer?: boolean      // Hide from initial prompt to save tokens
}

The Safety Net: buildTool() Factory

When you have dozens of tools, forgetting to implement a security check in just one of them can be disastrous. Imagine shipping a tool that accidentally defaults to "no permission needed" and lets Claude run destructive commands silently. To prevent this, Anthropic routes every single tool through the buildTool() factory function.

If a developer creates a new tool but forgets to specify whether it writes to disk, buildTool steps in and applies fail-closed defaults. It assumes the tool is NOT concurrency safe and NOT read-only, which means the permission system will automatically flag it and force user approval. You have to explicitly opt out of safety checks, not opt into them. That is a brilliant design decision.

// These are the actual defaults from Tool.ts (line 757)
const TOOL_DEFAULTS = {
  isEnabled:          () => true,
  isConcurrencySafe:  (_input?) => false,   // Assume NOT safe (fail-closed)
  isReadOnly:         (_input?) => false,   // Assume it writes (fail-closed)
  isDestructive:      (_input?) => false,
  checkPermissions:   (input, _ctx?) =>
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: (_input?) => '',   // Skip classifier for most tools
  userFacingName:     (_input?) => '',
}

// Every tool in the codebase uses this pattern:
export const GrepTool = buildTool({
  name: 'Grep',
  inputSchema: z.object({ pattern: z.string(), path: z.string() }),
  maxResultSizeChars: 50_000,
  isReadOnly: () => true,           // Override: grep is safe
  isConcurrencySafe: () => true,    // Override: multiple greps are fine
  async call(args) { /* ... */ },
  renderToolUseMessage(input) { /* ... */ },
})

The Roster: How tools.ts Assembles Everything

All 40+ tool implementations live in their own directories under tools/. The file tools.ts is the central registry that pulls them all together into a single ordered list. But it is far from a simple import-and-export. This file contains some of the most interesting engineering decisions in the entire codebase.

Dead-Code Elimination with Feature Flags

Not every tool ships in every build. Anthropic uses Bun's compile-time feature() macro to strip entire tools from the final binary. If a feature flag is off, the tool's code literally does not exist in the compiled output. Zero bytes. Zero overhead.

// tools.ts - conditional tool loading (from the actual source)
import { feature } from 'bun:bundle'

// These tools only exist when their feature flag is enabled at BUILD time:
const SleepTool = feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null

const cronTools = feature('AGENT_TRIGGERS')
  ? [
      require('./tools/ScheduleCronTool/CronCreateTool.js').CronCreateTool,
      require('./tools/ScheduleCronTool/CronDeleteTool.js').CronDeleteTool,
      require('./tools/ScheduleCronTool/CronListTool.js').CronListTool,
    ]
  : []

// Internal-only tools gated by environment variable:
const REPLTool = process.env.USER_TYPE === 'ant'
    ? require('./tools/REPLTool/REPLTool.js').REPLTool
    : null

Why Tool Order Matters

The order of tools in the getAllBaseTools() array is not random. It directly affects the system prompt sent to the Claude API. Tools listed first appear more prominently in the prompt, which means Claude is statistically more likely to reach for them. That is why AgentTool, BashTool, FileReadTool, and FileEditTool are always at the top of the list.

// tools.ts - the master tool list (simplified from source)
export function getAllBaseTools(): Tools {
  return [
    AgentTool,          // First: orchestrate subtasks
    TaskOutputTool,     // Monitor background work
    BashTool,           // Execute shell commands
    GlobTool, GrepTool, // Search and discover
    FileReadTool,       // Read files
    FileEditTool,       // Surgical edits
    FileWriteTool,      // Create new files
    // ... 30+ more tools, ordered by importance
    BriefTool,          // Last: session handoff (rarely needed)
  ]
}

Token Budgeting: Deferred Tools

Claude Code ships with over 46 built-in tools. Sending all 46 API schemas in the system prompt for every single conversation turn would consume thousands of tokens and drastically increase API costs and latency. To solve this, Anthropic implemented Deferred Tools.

By defining readonly shouldDefer: true, a tool is temporarily hidden from Claude's initial prompt. The model only knows about the core alwaysLoad tools directly (like Bash, File Edit, File Read). If Claude encounters a task needing a niche tool (like creating a Scheduled Cron job), it first calls the ToolSearchTool with a keyword query. The system returns the hidden schema, and then Claude can use it.

Each deferred tool includes a searchHint property (a short phrase like "create recurring cron scheduled agent task") that the ToolSearch algorithm matches against. Think of it as the tool advertising its capabilities to an internal search engine.

Managing Memory: maxResultSizeChars

What happens if Claude asks to run ls -laR / and the bash tool outputs 50 megabytes of text? Feeding that back into the LLM context window would instantly blow up the token limit and crash the session.

Anthropic enforces a strict maximum cap via the maxResultSizeChars property on every tool. If a tool's output string exceeds this limit, the system gracefully traps the output, saves it to a temporary file on the user's disk, and instead returns a compressed summary to Claude: "Output was too large. I saved the full result to /tmp/claude-xyz.txt. You can read specific sections with FileReadTool."

The one exception is FileReadTool itself, which sets maxResultSizeChars: Infinity. Think about why: if a file read produces output that gets persisted to another file, Claude would need to use FileReadTool to read that file, which could again be too large, creating an infinite loop. So FileReadTool manages its own output size internally with line-range parameters.

The Full Tool Catalog

Here is a breakdown of every tool category in the codebase, with explanations of why each tool exists and how it fits into the larger architecture.

Filesystem Tools

The bread and butter for any coding agent. These let Claude navigate and manipulate your repository.

Execution Tools

When the model writes code, it needs to test it. This is what sets Claude Code apart from basic web-based chatbots.

Agent & Task Tools

This is where Claude Code gets truly powerful: the ability to spawn copies of itself for parallel work.

Web & Network Tools

MCP & Integration Tools

Anthropic knew they could not build every tool imaginable. Instead of a messy plugin system, they implemented the Model Context Protocol (MCP) as the universal extension mechanism.

Utility & Meta Tools

Source Deep Dive: files.ts — Binary File Detection

Before any filesystem tool reads a file, Claude Code needs to know whether it's text or binary. Feeding raw binary data to an LLM as if it were source code wastes tokens and produces garbled output. The logic lives in src/utils/files.ts, which exports a two-stage detection system: a fast extension blocklist and a content-heuristic fallback.

Stage 1: The Extension Blocklist

BINARY_EXTENSIONS is a JavaScript Set containing roughly 80 file extensions across every category of binary content. It's organized by type, giving a clear picture of what Claude Code considers "untouchable as text":

The lookup function is a one-liner:

export function hasBinaryExtension(filePath: string): boolean {
  const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase()
  return BINARY_EXTENSIONS.has(ext)
}

This runs in O(1) time because it's a Set lookup, making the extension check essentially free on every file open. Notice that .pdf is included in the binary list, which would seem to prevent Claude from reading PDFs. The source comment explains the exception: "PDF is here; FileReadTool excludes it at the call site." FileReadTool has special-cased PDF to invoke a PDF extraction pipeline rather than raw file reading, so the extension check is bypassed for PDFs specifically.

Stage 2: The Content Heuristic

Extension matching isn't enough — files can be misnamed, and new binary formats appear regularly. The second check, isBinaryContent(), inspects the actual file bytes:

const BINARY_CHECK_SIZE = 8192  // Only check first 8KB

export function isBinaryContent(buffer: Buffer): boolean {
  const checkSize = Math.min(buffer.length, BINARY_CHECK_SIZE)

  let nonPrintable = 0
  for (let i = 0; i < checkSize; i++) {
    const byte = buffer[i]!

    // Null byte is a strong indicator of binary
    if (byte === 0) {
      return true  // Early exit: single null byte = binary
    }

    // Count non-printable, non-whitespace bytes
    // Printable ASCII is 32-126, plus tab(9), newline(10), CR(13)
    if (byte < 32 && byte !== 9 && byte !== 10 && byte !== 13) {
      nonPrintable++
    }
  }

  // If more than 10% non-printable, likely binary
  return nonPrintable / checkSize > 0.1
}

The heuristic has two tiers. The first is an immediate early exit: a single null byte (\0) anywhere in the first 8 KB is treated as a definitive binary indicator. Nearly all binary formats (ELF executables, PE headers, compiled JARs, ZIP archives) have null bytes in their headers, while valid UTF-8 text essentially never does. The second tier counts all bytes below ASCII 32 that aren't standard whitespace (tab, newline, carriage return) — if more than 10% of the sampled bytes are non-printable, the file is classified as binary.

Where Binary Detection Runs

These two functions are called in sequence in FileReadTool before any file content is returned to the model. If hasBinaryExtension() returns true (and the file isn't PDF), the tool returns an informative error message like "This file has a binary extension and cannot be read as text." If the extension passes but isBinaryContent() returns true on the first 8 KB, the same error is returned. The model never sees the raw bytes, preventing both garbage output and context window contamination from binary data.

The Safety Protocol

Of course, arming an AI with BashTool without safeguards would be reckless. Every single tool.call() invocation passes through a multi-layered permissions interceptor before anything actually executes.

First, validateInput() checks that the arguments are structurally valid. Then checkPermissions() runs tool-specific security logic. The result is one of three outcomes:

• { behavior: 'allow' } - Proceed immediately. Used for read-only tools like GrepTool.
• { behavior: 'ask' } - Freeze execution and show a permission dialog in the terminal. The model waits until you explicitly approve.
• { behavior: 'deny' } - Reject the tool call entirely and tell Claude why it was denied.

Tools that declare isDestructive: () => true trigger an even more prominent confirmation dialog. This is how Claude Code ensures you always stay in control, even when the agent is running autonomously.

For a complete deep dive into the permission modes (Interactive, Auto, Bypass) and the security classifier, see the Security & Permissions page.