# 工具使用故障排除

通过症状到修复的诊断表修复最常见的工具使用错误。

---

最常见的工具使用错误的症状到修复表。每个修复都交叉引用了拥有该功能的页面。

## Claude 调用了错误的工具

| 症状 | 可能原因 | 修复 |
|---|---|---|
| Claude 调用了工具 A，而你想要工具 B | 描述歧义 | 优化描述。通过何时使用而非仅做什么来区分工具。参见[定义工具](/docs/en/agents-and-tools/tool-use/define-tools)。 |
| Claude 从不调用你的工具 | 工具名称冲突或过于通用的 schema | 检查工具列表中是否有重复名称。添加 `input_examples` 使预期用途具体化。 |
| Claude 使用错误的参数类型调用 | 模型在模糊 schema 下猜测 | 添加 `strict: true`（如果你的 schema 在支持的子集中）或添加 `input_examples`。 |

## Claude 捏造工具参数

| 症状 | 可能原因 | 修复 |
|---|---|---|
| 参数在你的 schema 中不存在 | 模型在非 strict 模式下过度生成 | 如果你的 schema 在[支持的子集](/docs/en/agents-and-tools/tool-use/strict-tool-use)中，添加 `strict: true`。 |
| 参数值超出你的 enum 范围 | 缺少 strict 模式或 enum 过大 | 缩小 enum 或添加 `input_examples` 展示有效选择。 |

## 并行工具调用不工作

| 症状 | 可能原因 | 修复 |
|---|---|---|
| Claude 在并行更优时仍串行调用工具 | 消息历史格式化 | 在一条用户消息中发送多个 `tool_result` 块，而非每轮一个。参见[并行工具使用](/docs/en/agents-and-tools/tool-use/parallel-tool-use)。 |
| `disable_parallel_tool_use` 似乎被忽略 | 在对话中设置太晚 | 必须在返回 `tool_use` 的请求上设置。在后续请求上设置对之前的工具调用无效。 |

## 缓存持续失效

| 症状 | 可能原因 | 修复 |
|---|---|---|
| 每次请求都是缓存未命中 | `tool_choice` 在请求间变化 | 保持 `tool_choice` 稳定，或将 `cache_control` 断点放在变化点之前。参见[工具使用与 prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-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` 块放在任何文本之前。参见[处理工具调用](/docs/en/agents-and-tools/tool-use/handle-tool-calls)和[并行工具使用](/docs/en/agents-and-tools/tool-use/parallel-tool-use)。 |
| `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()` 解析。永远不要对序列化输入进行原始字符串匹配。 |

## 下一步

<CardGroup cols={3}>
  <Card title="定义工具" href="/docs/en/agents-and-tools/tool-use/define-tools">
    编写引导 Claude 选择正确工具的 schema 和描述。
  </Card>
  <Card title="处理工具调用" href="/docs/en/agents-and-tools/tool-use/handle-tool-calls">
    执行工具并以所需消息格式返回结果。
  </Card>
  <Card title="工具参考" href="/docs/en/agents-and-tools/tool-use/tool-reference">
    Anthropic schema 工具及其版本字符串的完整目录。
  </Card>
</CardGroup>