工具使用故障排除
通过症状到修复的诊断表修复最常见的工具使用错误。
最常见的工具使用错误的症状到修复表。每个修复都交叉引用了拥有该功能的页面。
Claude 调用了错误的工具
| 症状 | 可能原因 | 修复 |
|---|---|---|
| Claude 调用了工具 A，而你想要工具 B | 描述歧义 | 优化描述。通过何时使用而非仅做什么来区分工具。参见定义工具。 |
| Claude 从不调用你的工具 | 工具名称冲突或过于通用的 schema | 检查工具列表中是否有重复名称。添加 input_examples 使预期用途具体化。 |
| Claude 使用错误的参数类型调用 | 模型在模糊 schema 下猜测 | 添加 strict: true（如果你的 schema 在支持的子集中）或添加 input_examples。 |
Claude 捏造工具参数
| 症状 | 可能原因 | 修复 |
|---|---|---|
| 参数在你的 schema 中不存在 | 模型在非 strict 模式下过度生成 | 如果你的 schema 在支持的子集中，添加 strict: true。 |
| 参数值超出你的 enum 范围 | 缺少 strict 模式或 enum 过大 | 缩小 enum 或添加 input_examples 展示有效选择。 |
并行工具调用不工作
| 症状 | 可能原因 | 修复 |
|---|---|---|
| Claude 在并行更优时仍串行调用工具 | 消息历史格式化 | 在一条用户消息中发送多个 tool_result 块，而非每轮一个。参见并行工具使用。 |
disable_parallel_tool_use 似乎被忽略 | 在对话中设置太晚 | 必须在返回 tool_use 的请求上设置。在后续请求上设置对之前的工具调用无效。 |
缓存持续失效
| 症状 | 可能原因 | 修复 |
|---|---|---|
| 每次请求都是缓存未命中 | tool_choice 在请求间变化 | 保持 tool_choice 稳定，或将 cache_control 断点放在变化点之前。参见工具使用与 prompt caching。 |
| 在对话中途添加工具导致缓存失效 | 工具被添加到 tools 数组头部 | 使用 defer_loading: true 配合 tool search 将工具内联追加，而非修改数组头部。 |
请求时错误
| 错误 | 原因 | 修复 |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | 某些 tool_use id 缺少 tool_result，或 tool_result 不是用户消息中的第一个内容块 | 为助手响应中的每个 tool_use 块返回一个 tool_result。将 tool_result 块放在任何文本之前。参见处理工具调用和并行工具使用。 |
Input schema is not compatible with strict mode: string patterns are not supported | 在 strict: true 中使用了 pattern | 移除 pattern 或去掉 strict: true。pattern 关键字目前不在支持的 JSON Schema 子集中。 |
All tools have defer_loading: true | 模型没有可见的工具 | 至少一个工具必须立即加载。tool search 工具本身绝不能设置 defer_loading: true。 |
JSON 转义差异（Opus 4.6+）
| 症状 | 原因 | 修复 |
|---|---|---|
| 对工具输入的字符串比较在较新模型上失败 | Unicode 和正斜杠转义在不同模型版本间有差异 | 使用 json.loads() 或 JSON.parse() 解析。永远不要对序列化输入进行原始字符串匹配。 |