工具使用能力：训练与注入的双重来源

工具菜单是注入的：从 tools 字段到 special system prompt

候选 A「每个产品专门训练一个模型」——证伪：换一套完全不同的工具，同一个模型照样会用。候选 B「工具清单背在参数里」——证伪：请求删掉 tools 字段，能力即刻消失，参数没变行为变了。候选 C 成立：训练学「填表」，注入给「菜单」。官方两条证据①：

• tools 是顶层参数，模型不内置任何工具（官方原话①：All tools must be explicitly provided by you, in each API request）；工具定义三件套 = name（函数名）+ description（说明书）+ input_schema（表单）
• 工具定义计入 input tokens：计费口径明确「包括 tools 参数」①——工具菜单和你说的话，在模型眼里是同一种东西：上下文里的 token
• 服务端构造 special system prompt：使用 tools 时 API 自动附加一段启用工具使用的特殊 system prompt，模板顺序为——工具使用指令 → 格式指令 → 工具定义（JSON Schema） → 用户 system prompt → 工具配置①；关键细节：工具定义注入在用户 system prompt 之前；这段固定开销约 286–406 tokens①
• tool_choice 的 prefill 行为：设为 any / tool 时，API 会预填 assistant 消息，模型不再先输出自然语言解释①
• description 是决定性因素（官方原话①：This is by far the most important factor in tool performance）→ 工具描述是可干预的实验变量：改一段描述就能改行为

• 用 Anthropic SDK 定义 1 个工具并打印实际请求结构，指认工具定义在上下文里的位置
• 把 tool_choice 从 auto 改为 tool，观察输出是否还包含自然语言前言

什么能训、什么不能训：一张归因表

• 两阶段分工（本讲核心结论）：训练 / 后训练学「读说明书 → 输出合法 tool_use」的通用能力与「何时该调、何时该答」；推理（每次请求）决定具体有哪些工具、叫什么、参数怎么填——没有任何 client-side 工具是被「永久学会」的，schema 一删，本次请求中该能力即消失
• 约束解码的真相：默认 strict: false 靠微调学会生成符合 schema 的 JSON 但不保证严格一致（可能出现字符串 "2" 代替整数 2、漏必填字段）；开启 strict: true（OpenAI Structured Outputs）才把 JSON Schema 编译为语法约束 token 生成——Anthropic 未对 tool_use 做此承诺，宿主必须校验参数，不能赌模型永不出错
• 格式纪律可以被 RL 强化：Qwen3-Coder-Next 在 RL 里对非法 tool call 施加 turn 级 token 惩罚①（上一讲第 5 卡的三层奖励）——「工具调用的格式纪律是练出来的」
• 工具选择能力要专门训：ToolTrain 两阶段（拒绝采样 SFT → 基于规则的 RL，奖励用定位函数排名类指标）证明工具使用是独立可训练维度②
• ToolRM 的发现：在自然语言输出上训练的奖励模型判断工具调用很差，需要专门面向工具的奖励模型②——印证「工具调用是独立评估维度」
• server-side 工具是例外：联网搜索、代码执行等由厂商托管、模型训练过——注入生态里混着少量「真·内置」能力，表述时必须加限定

• 定义两个语义相近的工具（如 send-user / send-channel），观察描述模糊时的误选率
• 改一次 description 措辞，重跑同一任务，记录行为差异——体会「描述即软提示」

• 默认模式不保证 schema 严格一致，运行时校验的责任落在谁身上？这对 harness 设计意味着什么？
• 「工具描述是实验变量」对 benchmark 的可复现性提出什么要求？（伏笔：第 4 卡的 schema 版本锚定）

defer_loading 与 Tool Search：控制的是「进不进上下文」

• 工具膨胀的代价：多 server 场景（GitHub / Slack / Sentry / Grafana / Splunk）工具定义可吃 ~55K tokens①；Anthropic 工程博客举过 58 个 MCP 工具 ≈ 55K、内部见过 134K 的案例③——模型还没干活先交「菜单费」
• 选择准确率在 30–50 个工具之后开始下降① → 「更多工具」不等于「更强」，反而更笨
• Tool Search 机制：被标 defer_loading: true 的工具不进入上下文；初始只加载 ToolSearch 工具本身（约 500 tokens③）+ 非延迟工具；模型需要时先搜索，命中项以 tool_reference 返回并展开为完整定义（默认最多 5 个）①
• 反直觉点（必须讲清）：defer_loading 控制的是「是否进入 context」，不是「是否发送」——每个请求仍发送全部工具的完整定义，服务端需要它们来执行搜索与展开①；省的是模型上下文，不是网络流量
• 效果数据（口径各异，注意级别）：官方文档口径「token 降低 85%+、选择准确率在数千工具规模保持稳定」①；工程博客案例「上下文约 77K → 约 8.7K（-95%），Opus 4 选择准确率 49% → 74%」③
• Claude Code 侧：内置 ToolSearch 工具按需装载 MCP 工具（③逆向分析佐证）；配置旋钮 ENABLE_TOOL_SEARCH（unset / true / auto / auto:N / false）与 alwaysLoad 豁免③

• 「模型没用某个工具」有哪些可能的解释？在轨迹数据上如何区分「不需要」与「看不见」？（直接引出第 4 卡）

trajectory_schema 现状与三处缺口

• 现有能力（experiment_modules/recording/trajectory_schema.py）：12 类事件枚举、TOOL_USE / TOOL_RESULT 分离、parent_event_id 因果链、causality_id、tool_name / tool_input / tool_output / token_usage——「提议 / 执行分离」这条已经做对了
• 缺口一：工具可见性快照——不记录本轮请求实际装载了哪些工具、哪些被 defer，「为什么没用某工具」永远无法区分「不需要」与「看不见」
• 缺口二：提议 vs 执行的 outcome 判定——事件间有因果链接但没有状态标志，「模型以为成功」与「环境实际报错」在数据上不可区分
• 缺口三：工具 schema 版本锚定——工具描述是动态生成的软提示（第 1 卡），不锚定版本则跨期实验不可比：上个月的行为差异是模型的问题还是描述改了？

• 打开本仓一条真实轨迹（experiments/ 下任一 .traj），尝试回答「这一轮模型能看到哪些工具」——亲手体会数据缺口