Claude Platform Docs
Messages工具

工具使用故障排查

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

针对最常见的 "tool use"（工具使用）错误的症状到修复对照表。每项修复都交叉引用了负责该功能的页面。

Claude 调用了错误的工具

症状可能原因修复方法
您想要工具 B，但 Claude 调用了工具 A描述含糊不清使描述更加精确。通过"何时"使用工具来区分它们，而不仅仅是它们"做什么"。请参阅定义工具。
Claude 从不调用您的工具工具名称冲突或 schema 过于通用检查工具列表中是否存在重复名称。添加 input_examples 使预期用途更加具体。
Claude 调用时使用了错误的参数类型模型在含糊的 schema 上进行猜测添加 strict: true（如果您的 schema 属于受支持的子集），或添加 input_examples。

Claude 编造工具参数

症状可能原因修复方法
出现了您的 schema 中不存在的参数未启用严格模式时模型过度生成如果您的 schema 属于受支持的子集，请添加 strict: true。
参数值超出您的枚举范围缺少严格模式或枚举过大缩小枚举范围，或添加展示有效选项的 input_examples。

并行工具调用不起作用

症状可能原因修复方法
在并行更合适的情况下，Claude 却按顺序调用工具消息历史格式问题在一条用户消息中发送多个 tool_result 块，而不是每轮发送一个。请参阅并行工具使用。
disable_parallel_tool_use 似乎被忽略在对话中设置得太晚必须在返回 tool_use 的那个请求上设置。在之后的请求上设置对先前的工具调用没有影响。

缓存不断失效

症状可能原因修复方法
每个请求都是缓存未命中tool_choice、思考配置或 output_config.effort 在请求之间发生变化保持 tool_choice 稳定，或将 cache_control 断点放在变化点之前；在缓存对话的整个生命周期内保持思考配置和 effort 级别不变。请参阅工具使用与提示缓存和思考与提示缓存。
在对话中途添加工具会破坏缓存工具被添加到 tools 数组的开头将 defer_loading: true 与工具搜索配合使用，以内联方式追加工具，而不是修改数组头部。

请求时的错误

错误原因修复方法
tool_use ids were found without tool_result blocks immediately after某些 tool_use id 缺少对应的 tool_result，或者 tool_result 不是用户消息中的第一个内容块为助手响应中的每个 tool_use 块返回一个 tool_result。将 tool_result 块放在任何文本之前。请参阅处理工具调用和并行工具使用。
was found without a corresponding <name>_tool_result block上一个助手轮次包含一个没有结果块的 server_tool_use 块（最常见的情况是 Claude 将其与客户端工具一起调用），并且您的下一条用户消息结束了该轮次（例如，在 tool_result 块之后包含文本），或者恢复请求不再定义该服务器工具（此时消息以 but no <name> tool was provided 结尾）发送一条仅包含客户端 tool_use id 对应的 tool_result 块的用户消息，并保持相同的 tools 数组。请参阅停止原因与回退。
Unsupported regex feature in pattern field: ...严格工具的 input_schema 中的某个 pattern 使用了严格模式无法编译的正则表达式特性，例如反向引用、环视断言、单词边界或较大的 {n,m} 范围简化该模式。支持带有基本量词、字符类和分组的锚定模式；请参阅 JSON Schema 限制。
All tools have defer_loading: true没有对模型可见的工具至少必须有一个工具被立即加载。工具搜索工具本身绝不能设置 defer_loading: true。

错误：thinking 块不能被修改

如果在工具调用后继续对话时，请求失败并返回 400 invalid_request_error，且其消息包含 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified，则说明您的应用程序在将助手的 thinking 块发回之前对其进行了修改。请将整条助手消息原样发回，然后追加您的 tool_result。

请参阅 Thinking 块不能被修改了解完整的错误信息和修复步骤。

Claude 将工具结果标记为提示注入

症状可能原因修复方法
Claude 拒绝根据工具结果采取行动，或要求用户确认来自工具结果的指令您自己的指令被放在 tool_result 内容中传递Claude 经过训练，会将工具结果中的指令视为可能不受信任的第三方内容。请将您的指令移出工具结果：在 tool_result 块之后的 user 轮次中发送它们，或者在受支持的模型上，通过对话中途的系统消息发送。让工具结果仅包含数据。请参阅缓解越狱和提示注入。

JSON 转义差异（Opus 4.6+）

症状原因修复方法
在较新的模型上，对工具输入进行字符串比较失败不同模型版本之间的 Unicode 和正斜杠转义方式不同使用 json.loads() 或 JSON.parse() 进行解析。切勿对序列化后的输入进行原始字符串匹配。

后续步骤

定义工具

编写能够引导 Claude 选择正确工具的 schema 和描述。

处理工具调用

执行工具并以所需的消息格式返回结果。

工具参考

Anthropic 提供的工具及其版本字符串的完整目录。

Was this page helpful?