Claude Code Tools 研究系列-前置篇（tool 机制）

这个系列后续每篇会拆一个具体 tool。在此之前，先把 "tool 是什么、Claude 怎么用" 讲清楚 —— 后面所有拆解都建立在这个底子上。

为什么要有 tool

LLM 本身只会生成文本。这带来两个硬伤：

1. 不能操作外部世界 —— 光生成 "我把文件删了" 这句话没用，文件还在
2. 输出不可靠 —— 模型可能返回结构不对、字段缺失、幻觉内容的文本，下游程序没法稳定消费

Tool 补上的正是这两块：

1. 动作 —— 声明一个可执行函数，模型调用后由 harness 真的执行（读文件、发请求、切模式）
2. 结构 —— 用 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 usefordate 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"]}}

三个顶级字段：

1. name —— 工具唯一标识，同时也是给模型看的命名信号
2. description —— 一段自然语言，讲这个工具是什么、什么时候用、什么时候不用
3. input_schema —— JSON schema，声明入参结构 + 每个字段的 description + 校验规则

这就是 tool 定义的全部 —— 没有隐藏配置，没有其他元数据。所有设计意图都必须编码进这三个字段。

三大字段各自在做什么

后续每篇文章会按 4 层拆解 tool，这 4 层其实就是三大字段的展开：

信号密度递减，覆盖面递增：

1. 命名 —— 一个词就能感知（每次读到字段名都在训练）
2. 工具描述 —— 每次考虑用这个工具时都会读到（宏观边界）
3. 字段描述 —— 填字段时才读到（精确 hint）
4. schema 校验 —— 只在写错时才被感知（硬拦截）

一个 tool 定义的完整 prompt 表面 = 这 4 层叠加。

Claude 是怎么"读到"这些的

所有 tool 定义会拼进 system prompt，随每次请求发给模型。这是关键 —— 不是 "调用的时候才加载"，而是常驻在对话上下文里。

具体流程：

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

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

1. 描述里每个字都花 token —— 一个 20 KB 的 tool 定义每次请求都要发一遍，token 成本乘以对话轮次
2. 描述可以引用其他 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 层就返回明确失败，而不是让模型拿到一个语义模糊的空结果继续走。

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

1. 返回体积必须节制 —— 一个 grep 返回 10 万行会把上下文瞬间打满
2. 好的工具会提前摘要 / 截断 / 分页（比如 Read 默认只读 2000 行、Grep 有 head_limit）
3. 这也解释了为什么 Claude Code 有大量看似 "读取" 类工具却总是返回精简结果 —— 不是能力弱，是有意的 context 预算管理

Tool 是结构化 prompt engineering

对比一下：

自由 prompt 版本：

Tool 版本：

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

差别不在 "能不能实现"，而在能不能稳定：

Tool 本质上是 结构化的 prompt engineering：把 "让模型稳定做某件事" 这个软性需求，编码成可校验、可组合、可维护的规格。

系列后续预告

搞清楚 tool 机制后，后续每篇会用同一个骨架拆一个具体 tool：

1. 作用

2. 一个具体例子（含反例对照）

3. 触发条件

4. 技术实现 —— 按 4 层展开

   1. 1 · 命名
   2. 2 · 工具级描述
   3. 3 · 字段级描述
   4. 4 · schema 校验规则

5. 与邻居工具的分工

6. 小结

前置篇讲机制 —— tool 是什么、Claude 怎么用。后续讲设计 —— 具体 tool 是怎么把这 4 层用满，让一个能力从"能做"变成"稳定、可预测、可协作"。