工具使用故障排查

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

针对最常见的 "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 schema 工具及其版本字符串的完整目录。

Was this page helpful?

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 块不能被修改

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

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

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

JSON 转义差异（Opus 4.6+）

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

后续步骤

定义工具

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

处理工具调用

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

工具参考

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

Was this page helpful?

Claude 调用了错误的工具

Claude 编造工具参数

并行工具调用不起作用

缓存不断失效

请求时的错误

错误：thinking 块不能被修改

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

JSON 转义差异（Opus 4.6+）

后续步骤

Claude 调用了错误的工具

Claude 编造工具参数

并行工具调用不起作用

缓存不断失效

请求时的错误

错误：thinking 块不能被修改

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

JSON 转义差异（Opus 4.6+）

后续步骤

Claude 调用了错误的工具

Claude 编造工具参数

并行工具调用不起作用

缓存不断失效

请求时的错误

错误：thinking 块不能被修改

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

JSON 转义差异（Opus 4.6+）

后续步骤

Claude 调用了错误的工具

Claude 编造工具参数

并行工具调用不起作用

缓存不断失效

请求时的错误

错误：thinking 块不能被修改

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

JSON 转义差异（Opus 4.6+）

后续步骤