消息工具

工具使用故障排除

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

针对最常见工具使用错误的症状到解决方案对照表。每个解决方案都交叉引用了负责该功能的相关页面。

Claude 调用了错误的工具

症状	可能原因	解决方案
您希望 Claude 调用工具 B，但它调用了工具 A	描述存在歧义	优化描述。通过"何时"（WHEN）使用来区分工具，而不仅仅是"做什么"（WHAT）。请参阅定义工具。
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` 不一致	保持 `tool_choice` 稳定，或将 `cache_control` 断点放置在变化点之前。请参阅工具使用与提示缓存。
在对话中途添加工具会破坏缓存	工具被前置到 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` 数组。请参阅停止原因和回退。
`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`	模型看不到任何工具	至少有一个工具必须立即加载。工具搜索工具本身绝不能设置 `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` 轮次中发送它们，或者（在 Claude Opus 4.8 及更高版本上）通过对话中途系统消息发送。工具结果中只保留数据。请参阅缓解越狱和提示注入。

JSON 转义差异（Opus 4.6+）

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

后续步骤

定义工具

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

处理工具调用

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

工具参考

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

Was this page helpful?

消息工具

工具使用故障排除

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

针对最常见工具使用错误的症状到解决方案对照表。每个解决方案都交叉引用了负责该功能的相关页面。

Claude 调用了错误的工具

症状	可能原因	解决方案
您希望 Claude 调用工具 B，但它调用了工具 A	描述存在歧义	优化描述。通过"何时"（WHEN）使用来区分工具，而不仅仅是"做什么"（WHAT）。请参阅定义工具。
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` 不一致	保持 `tool_choice` 稳定，或将 `cache_control` 断点放置在变化点之前。请参阅工具使用与提示缓存。
在对话中途添加工具会破坏缓存	工具被前置到 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` 数组。请参阅停止原因和回退。
`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`	模型看不到任何工具	至少有一个工具必须立即加载。工具搜索工具本身绝不能设置 `defer_loading: true`。

错误：thinking 块不能被修改

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

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

症状	可能原因	解决方案
Claude 拒绝根据工具结果采取行动，或要求用户确认来自工具结果的指令	您自己的指令被放在了 `tool_result` 内容中传递	Claude 经过训练，会将工具结果中的指令视为潜在不可信的第三方内容。请将您的指令移出工具结果：在 `tool_result` 块之后的 `user` 轮次中发送它们，或者（在 Claude Opus 4.8 及更高版本上）通过对话中途系统消息发送。工具结果中只保留数据。请参阅缓解越狱和提示注入。

JSON 转义差异（Opus 4.6+）

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

后续步骤

定义工具

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

处理工具调用

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

工具参考

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+）

后续步骤