Claude Code Tools工具机制研究系列前置篇全方位深度解析

本系列后续将逐一拆解具体的 Claude Code Tool。但在深入之前，必须先打好基础：全面理解 tool 的本质是什么，以及 Claude 如何调用这些工具。后续所有分析都建立在这个认知框架之上。

为什么需要 tool 机制

LLM 本质上只能生成文本。听起来功能强大，但仔细分析会发现两个致命短板：

1. 无法操作外部世界 —— 模型可以声称“文件已删除”，但实际文件纹丝不动
2. 输出不可靠 —— 模型可能返回格式错误、字段缺失、包含幻觉内容的文本，下游程序无法稳定消费

Tool 恰好弥补了这两大缺陷：

• 动作能力 —— 声明一个可执行函数，模型调用后由 harness 真正执行（读文件、发请求、切换模式）
• 结构约束 —— 使用 JSON schema 声明入参，模型必须按 schema 输出，不合规直接拦截

因此，tool 的核心价值并非让 LLM 变得更强，而是为 LLM 与外部世界之间搭建一条可信、可控的通信通道。

一个 tool 定义的具体结构

Anthropic API 中的 tool 定义是一个 JSON 对象。以 AskUserQuestion 简化版为例：

{"name": "AskUserQuestion","description": "Use this tool only when you are blocked on a decision that is genuinely the user's to make: one you cannot resolve from the request, the code, or sensible defaults. ...","input_schema": {"type": "object","properties": {"questions": {"type": "array","description": "Questions to ask the user (1-4 questions)","minItems": 1,"maxItems": 4,"items": {"type": "object","properties": {"question": {"type": "string","description": "The complete question to ask the user. Should be clear, specific, and end with a question mark. Example: "Which library should we use for date formatting?""},"header": {"type": "string","maxLength": 12,"description": "Very short label displayed as a chip/tag (max 12 chars). Examples: "Auth method", "Library", "Approach"."},"multiSelect": {"type": "boolean","default": false,"description": "Set to true to allow the user to select multiple options ..."},"options": {"type": "array","minItems": 2,"maxItems": 4,"items": { "...": "..." }}},"required": ["question", "header", "options"]}}},"required": ["questions"]}}

三个顶级字段，务必牢记：

• name —— 工具的唯一标识，也是向模型传递命名语义的信号
• description —— 一段自然语言描述，说明工具的用途、适用场景与禁用场景
• input_schema —— JSON schema，声明入参结构、每个字段的描述以及校验规则

简而言之，一个 tool 定义就是这三个字段的组合，没有隐藏配置，也没有额外元数据。所有设计意图都必须浓缩在这三块内容中。

三大字段各自承担的角色

后续每篇文章会按 4 层结构拆解 tool，而这 4 层正是三大字段的展开：

注意这个规律：信号密度递减，覆盖面递增。

• 命名 —— 一个词即可感知（每次读到字段名都在强化认知）
• 工具描述 —— 每次考虑调用该工具时都会读取（宏观边界）
• 字段描述 —— 只在填写字段时读取（精确提示）
• schema 校验 —— 仅在写错时才会被触发（硬拦截）

一个 tool 定义对模型而言的完整 prompt 表面，其实就是这四层叠加的效果。

Claude 是如何“读取”这些定义的

所有 tool 定义都会拼入 system prompt，每次请求都发送给模型。关键点在于：并非调用时才临时加载，而是常驻在对话上下文中。

具体流程：

1. Harness 启动时收集所有可用的 tool 定义
2. 每次向 Claude 发送请求时，将 tool 列表附加在请求的 tools 参数中
3. Claude 收到的 prompt 结构大致为：system prompt + tools 定义（JSON 形式全文注入）+ messages 对话历史

这个机制带来的直接后果有两个：

• 描述中的每个字都要消耗 token —— 一个 20 KB 的 tool 定义每次请求都会重复发送，token 成本乘以对话轮次
• 描述可以引用其他 tool —— 因为所有 tool 都在同一份 system prompt 中，编写 AskUserQuestion 时可以直接说明“不要用来问‘方案 OK 吗’，那是 ExitPlanMode 的职责”

因此，优秀的 tool 描述一定是既简短又精准。简短是为了节省 token，精准是为了每一句话都在承担限制职责、划清边界、明确协作契约的任务。

Claude 如何调用一个 tool

一次调用就是一次消息往返：

Step 1 · 模型输出 tool_use block

当 Claude 决定使用某个 tool 时，并不会直接执行，而是在回复中输出一个特殊 block：

{"type": "tool_use","id": "toolu_01A09q90qw90lq917835lq9","name": "AskUserQuestion","input": {"questions": [{"question": "选哪种认证方式？","header": "认证方式","options": [{ "label": "JWT（推荐）", "description": "无状态、易横向扩展" },{ "label": "会话 cookie", "description": "server-side session store" },{ "label": "OAuth", "description": "接第三方身份提供商" }]}]}}

Step 2 · Harness 拦截并执行

模型的输出被 harness 截获，harness 检查 name 找到对应工具，将 input 传递给实现（可以是本地函数、外部服务或 UI 交互）。执行完毕后返回结果。

Step 3 · Harness 通过 tool_result 将结果送回模型

{"type": "tool_result","tool_use_id": "toolu_01A09q90qw90lq917835lq9","content": "用户选择：JWT（推荐）"}

这个 block 作为新一条 user 消息发回给 Claude。Claude 继续对话 —— 可以基于返回值再调用下一个 tool，也可以直接向用户输出文本回复。

在整个过程中，模型担任决策者：何时调用、调用哪个工具、传递什么参数、拿到结果后如何使用，全凭模型自主判断。Harness 只负责执行和传递结果。

返回值的两种模式

成功时，tool_result 携带内容：

{"type": "tool_result","tool_use_id": "...","content": "..."}

content 可以是纯文本，也可以是结构化的 block（多段文本 + 图片等）。

失败时，增加 is_error: true：

{"type": "tool_result","tool_use_id": "...","content": "Error: file not found","is_error": true}

这就是所谓的 loud fail：错误不会静默消失，模型能够感知到失败，并据此决定下一步 —— 重试、换方案，或询问用户。这也是为什么优秀的 tool 会采用严格的 schema 校验 —— 在 harness 层就把错误拦截，返回一个明确的失败，而不是让模型拿到一个语义模糊的空结果继续执行。

返回内容会占用主循环的上下文。模型每次收到 tool_result 都会将其读入上下文。这意味着：

• 返回体积必须严格控制 —— 一个 grep 返回 10 万行会瞬间填满上下文
• 优秀的工具会提前进行摘要、截断或分页（例如 Read 默认只读 2000 行，Grep 设有 head_limit）
• 这也解释了为什么 Claude Code 中有大量看似“读取”类的工具却总是返回精简结果 —— 这不是能力不足，而是有意识的上下文预算管理

Tool 是结构化的 prompt engineering

对比以下两种方式：

自由 prompt 版本：

Tool 版本：

• name = "AskUserQuestion"
• description = 一段几百字的行为约束
• input_schema = 精确到字段的类型 + 校验 + few-shot

差异不在于“能否实现”，而在于“能否稳定”：

Tool 本质上就是结构化的 prompt engineering：将“让模型稳定执行某件事”这一软性需求，编码为可校验、可组合、可维护的规格说明。

系列后续预告

在理解 tool 机制后，后续每篇文章将沿用同一骨架拆解一个具体 tool：

1. 作用
2. 一个具体例子（含反例对照）
3. 触发条件
4. 技术实现 —— 按 4 层展开
   • 1 · 命名
   • 2 · 工具级描述
   • 3 · 字段级描述
   • 4 · schema 校验规则
5. 与相邻工具的分工
6. 小结

前篇讲机制，将 tool 是什么、Claude 如何使用说清楚。后续讲设计，看具体 tool 如何将这四层用满，把一个能力从“能做”升级为“稳定、可预测、可协作”。