tool_choice 有三种模式。选错了是流水线故障的常见根源。
| 模式 | 保证 | 适用场景 |
|---|---|---|
Forced ({type: tool, name: X}) | 每次都调用指定工具 | 单 schema 流水线 |
Any ({type: any}) | 一定调用某个工具，Claude 选哪个 | 多 schema，保证结构化输出 |
Auto ({type: auto}) | 工具调用可选——可能返回文本 | 有些输入不需要结构化 |
数据：500 份混合文档，3 个提取工具
| 模式 | 工具调用率 | 错误 schema |
|---|---|---|
| Forced（单工具） | 100% | 34% |
| Any | 100% | 3% |
| Auto | 87% | 2% |
Any 是多工具流水线的最优选择。它同时实现了 100% 工具调用和高 schema 准确率——Claude 选对工具的同时保证了结构化输出。
Auto 模式：保证输出的反模式
Auto 模式允许 Claude 返回文本而不调用工具。13% 的请求中发生了这种情况——完全绕过 schema，打断下游解析。
再怎么改进工具描述也无法保证 auto 总是调用工具。any 模式在设计上就提供了这个保证。只在某些输入确实不应该产出结构化输出时才用 auto。
Forced 模式：多 Schema 的反模式
对所有文档类型强制使用一个工具，会把错误的 schema 套到不匹配的文档上。即使 90% 的文档是发票，对收据强制使用 extract_invoice 也会产出 34% 的错误 schema 输出。
对于多 schema 流水线，any 模式让 Claude 选择合适的工具，同时保证工具一定被调用。
Auto 什么时候是对的
一个流水线同时接收代码文件（需要结构化分析）和 README 文件（需要文本摘要）。Auto 让 Claude 对代码使用分析工具，对 README 返回文本。这种有条件的行为才是 auto 的合理用例。
顺序提取模式
两阶段提取（先元数据，再补充信息）：
- 阶段 1：Forced tool_choice — 保证元数据提取
- 阶段 2：Auto — 允许有条件地补充（不需要时跳过）
两个阶段都强制的话产出了 15% 的空补充字段。阶段 2 用 Auto 让 Claude 在文档不需要时跳过补充。
一句话总结： 单 schema 流水线用 forced，多 schema 保证输出用 any，只在某些输入确实不需要结构化输出时用 auto——选错模式导致 13-34% 的流水线故障。