构建工具

工具使用故障排除

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

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

Claude 调用了错误的工具

症状	可能原因	修复
Claude 调用工具 A，而你想要工具 B	描述歧义	锐化描述。通过何时使用来区分工具，而不仅仅是它们做什么。参见定义工具。
Claude 从不调用你的工具	工具名称冲突或过于通用的模式	检查工具列表中是否有重复名称。添加 `input_examples` 以使预期用途具体化。
Claude 使用错误的参数类型调用	模型在模糊模式下猜测	添加 `strict: true`（如果你的模式在支持的子集中）或添加 `input_examples`。

症状	可能原因	修复
模式中不存在的参数	模型在非严格模式下过度生成	如果你的模式在支持的子集中，添加 `strict: true`。
参数值超出你的枚举	缺少严格模式或枚举过大	缩小枚举或添加 `input_examples` 显示有效选择。

症状	可能原因	修复
Claude 按顺序调用工具，而并行会更好	消息历史格式化	在一个用户消息中发送多个 `tool_result` 块，而不是每轮一个。参见并行工具使用。
`disable_parallel_tool_use` 似乎被忽略	在对话中设置太晚	必须在返回 `tool_use` 的请求上设置。在稍后的请求上设置它对早期的工具调用没有影响。

症状	可能原因	修复
每个请求都是缓存未命中	`tool_choice` 在请求之间变化	保持 `tool_choice` 稳定或将 `cache_control` 断点放在变化点之前。参见工具使用与提示缓存。
在对话中途添加工具会破坏缓存	工具前置到工具数组	使用 `defer_loading: true` 与工具搜索一起，以内联方式追加工具而不是修改数组头。

错误	原因	修复
`tool_use ids were found without tool_result blocks immediately after`	缺少某些 `tool_use` ids 的 `tool_result`，或 `tool_result` 不是用户消息中的第一个内容块	为助手响应中的每个 `tool_use` 块返回一个 `tool_result`。将 `tool_result` 块放在任何文本之前。参见处理工具调用和并行工具使用。
`Input schema is not compatible with strict mode: string patterns are not supported`	使用 `pattern` 与 `strict: true`	删除模式或放弃 `strict: true`。`pattern` 关键字还不在支持的 JSON Schema 子集中。
`All tools have defer_loading: true`	模型看不到任何工具	至少一个工具必须立即加载。工具搜索工具本身绝不能有 `defer_loading: true`。

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

编写模式和描述，引导 Claude 选择正确的工具。

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

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

Was this page helpful?

Claude 调用了错误的工具

症状	可能原因	修复
Claude 调用工具 A，而你想要工具 B	描述歧义	锐化描述。通过何时使用来区分工具，而不仅仅是它们做什么。参见定义工具。
Claude 从不调用你的工具	工具名称冲突或过于通用的模式	检查工具列表中是否有重复名称。添加 `input_examples` 以使预期用途具体化。
Claude 使用错误的参数类型调用	模型在模糊模式下猜测	添加 `strict: true`（如果你的模式在支持的子集中）或添加 `input_examples`。

症状

可能原因

修复

模式中不存在的参数

模型在非严格模式下过度生成

如果你的模式在支持的子集中，添加 strict: true。

参数值超出你的枚举

缺少严格模式或枚举过大

缩小枚举或添加 input_examples 显示有效选择。

并行工具调用不起作用

症状	可能原因	修复
Claude 按顺序调用工具，而并行会更好	消息历史格式化	在一个用户消息中发送多个 `tool_result` 块，而不是每轮一个。参见并行工具使用。
`disable_parallel_tool_use` 似乎被忽略	在对话中设置太晚	必须在返回 `tool_use` 的请求上设置。在稍后的请求上设置它对早期的工具调用没有影响。

缓存持续失效

症状	可能原因	修复
每个请求都是缓存未命中	`tool_choice` 在请求之间变化	保持 `tool_choice` 稳定或将 `cache_control` 断点放在变化点之前。参见工具使用与提示缓存。
在对话中途添加工具会破坏缓存	工具前置到工具数组	使用 `defer_loading: true` 与工具搜索一起，以内联方式追加工具而不是修改数组头。

请求时的错误

错误	原因	修复
`tool_use ids were found without tool_result blocks immediately after`	缺少某些 `tool_use` ids 的 `tool_result`，或 `tool_result` 不是用户消息中的第一个内容块	为助手响应中的每个 `tool_use` 块返回一个 `tool_result`。将 `tool_result` 块放在任何文本之前。参见处理工具调用和并行工具使用。
`Input schema is not compatible with strict mode: string patterns are not supported`	使用 `pattern` 与 `strict: true`	删除模式或放弃 `strict: true`。`pattern` 关键字还不在支持的 JSON Schema 子集中。
`All tools have defer_loading: true`	模型看不到任何工具	至少一个工具必须立即加载。工具搜索工具本身绝不能有 `defer_loading: true`。

症状

原因

修复

对工具输入的字符串比较在较新的模型中失败

Unicode 和正斜杠转义在模型版本之间不同

使用 json.loads() 或 JSON.parse() 解析。永远不要对序列化输入进行原始字符串匹配。