4 · The Tool Model

This chapter covers how “a tool” is modeled inside the program, and how the 40 built-in tools are organized and served to the model.

4.1 The Tool interface: seven orthogonal capability groups

Tool.ts is 793 lines in total, of which the type definition Tool<Input, Output, Progress> takes up 330. It slices “every question a tool needs to answer” into seven non-overlapping capability groups:

4.2 Why the “safety predicates” deserve their own group

Because this group is not for humans; it is for the scheduler. The scheduler knows nothing about any concrete tool — it has no idea what Bash is or what Read is. It only asks these few yes/no questions and arranges execution accordingly:

An easily overlooked detail: the predicates take arguments

isConcurrencySafe(input) is a method that takes the input, not a static flag.

Same Bash tool: running ls (list files) is concurrency-safe; running rm -rf (delete) is not. Safety depends on what this particular call is going to do, not on the tool type. Modeled as a static flag, the Bash tool could only ever declare “I am unsafe,” giving up every opportunity for parallelism.

4.3 Fail-safe defaults

Every tool is created through a factory function:

const TOOL_DEFAULTS = {
  isEnabled:          () => true,
  isConcurrencySafe:  () => false,   // ← default: "cannot run in parallel"
  isReadOnly:         () => false,   // ← default: "writes"
  isDestructive:      () => false,
  checkPermissions:   (input) => ({ behavior:'allow', updatedInput: input }),
  toAutoClassifierInput: () => '',   // ← default: "skip the safety classifier"
  userFacingName:     () => '',
}

export function buildTool<D>(def: D): BuiltTool<D> {
  return { ...TOOL_DEFAULTS,               // lay down the defaults first
           userFacingName: () => def.name,
           ...def }                        // then override with the tool's own definition
}

claude-code/src/Tool.ts

A source comment sums up the design principle: “Defaults (fail-closed where it matters)”.

The one default that looks like it breaks the rule

toAutoClassifierInput defaults to returning an empty string, meaning “this tool stays out of the safety classifier’s view.” The comment explains why:

4.4 The 40 built-in tools, by category

The tool list is assembled conditionally

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    // The internal native build embeds fast search programs in the executable, and
    // find/grep in the shell are aliased to them, so standalone Glob/Grep tools aren't needed
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool,
    FileReadTool, FileEditTool, FileWriteTool, NotebookEditTool,
    WebFetchTool, TodoWriteTool, WebSearchTool, TaskStopTool,
    AskUserQuestionTool, SkillTool, EnterPlanModeTool,
    ...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),      // internal users only
    ...(isTodoV2Enabled() ? [TaskCreateTool, TaskGetTool, ...] : []),
    ...(isEnvTruthy(process.env.ENABLE_LSP_TOOL) ? [LSPTool] : []),
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
    ...(isAgentSwarmsEnabled() ? [getTeamCreateTool(), getTeamDeleteTool()] : []),
    ...cronTools,
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
  ]
}

Three dimensions of condition: compile-time feature flags (feature('XXX')), runtime environment variables, and user type (internal / external). Chapter 13 explains how compile-time flags achieve “this code does not even exist in the external build.”

4.5 Progressive tool loading

The problem

Every tool’s full description goes into the system prompt, and the system prompt is resent every turn. When a user has connected a dozen or so MCP external servers, the total tool count can exceed a hundred, and the descriptions add up to tens of thousands of tokens — paid for again every turn.

The fix: defer_loading

The two related fields:

• shouldDefer: true — this tool is lazily loaded
• alwaysLoad: true — never deferred. For tools the model must see on the very first turn. MCP external tools can declare this on the server side via _meta['anthropic/alwaysLoad']

How to write the keywords

Remediation when deferred loading goes wrong

Deferred loading has a side effect: the model may call a tool from memory before its full description has been loaded, and get the parameters wrong. So when parameter validation fails, there is a special hint:

const schemaHint = buildSchemaNotSentHint(tool, toolUseContext.messages,
                                          toolUseContext.options.tools)
if (schemaHint) {
  logEvent('tengu_deferred_tool_schema_not_sent', {
    toolName: sanitizeToolNameForAnalytics(tool.name), isMcp: tool.isMcp ?? false })
  errorContent += schemaHint    // append the hint: "you haven't loaded this tool's description yet; search for it first"
}

And this situation has its own telemetry event (tengu_deferred_tool_schema_not_sent) — which tells you they are monitoring “the rate of call failures caused by deferred loading” to judge the net benefit of this optimization.

4.6 Tool list assembly: a hidden constraint about caching

This code is only 8 lines long, but what it reveals is extremely valuable:

export function assembleToolPool(permissionContext, mcpTools): Tools {
  const builtInTools    = getTools(permissionContext)               // built-in tools
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  const byName = (a, b) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName)             // ★ built-in tools sorted on their own
      .concat(allowedMcpTools.sort(byName)),   // ★ external tools sorted on their own, then appended
    'name',                                    // dedup by name; built-ins win
  )
}

claude-code/src/tools.ts

Note: the two groups are sorted separately and then concatenated, not merged into one big array and sorted together. To someone unfamiliar with the caching mechanism, this looks like needless complication. The source comment gives the answer:

How serious this is

The same file has another comment:

/**
 * NOTE: This MUST stay in sync with
 * https://console.statsig.com/.../claude_code_global_system_caching,
 * in order to cache the system prompt across users.
 */
export function getAllBaseTools(): Tools { ... }

In other words: note: this function must stay in sync with a particular live configuration so that the system prompt’s cache can be shared across all users.

4.7 backfillObservableInput: an extreme example of cache protection

Sometimes a tool needs to add derived fields for logs, hooks, or the SDK (for example, expanding a relative path into an absolute one). But the original parameter object that gets sent back to the API must never be changed — change one byte and the cache is gone.

/**
 * Called on copies of tool_use input before observers see it (SDK stream,
 * transcript, canUseTool, PreToolUse/PostToolUse hooks). Mutate in place
 * to add legacy/derived fields. Must be idempotent. The original API-bound
 * input is never mutated (preserves prompt cache).
 */
backfillObservableInput?(input: Record<string, unknown>): void

The implementation at the call site is even more careful:

const originalInput = block.input as Record<string, unknown>
const inputCopy = { ...originalInput }        // clone
tool.backfillObservableInput(inputCopy)       // mutate only the clone

// ★ Produce a cloned message only when the backfill "added fields";
//   if it merely overwrote existing fields, don't even clone
const addedFields = Object.keys(inputCopy).some(k => !(k in originalInput))
if (addedFields) {
  clonedContent ??= [...message.message.content]
  clonedContent[i] = { ...block, input: inputCopy }
}

Why no clone when it “only overwrites existing fields”? The comment explains:

This level of restraint shows that “protect the cache” is a first-class constraint in this system — even a field overwrite that might affect test fixtures is avoided.