建構工具

工具使用故障排除

使用症狀對應修復診斷表修復最常見的工具使用錯誤。

針對最常見工具使用錯誤的症狀對應修復表。每個修復都交叉參考擁有該功能的頁面。

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() 進行解析。永遠不要對序列化輸入進行原始字串匹配。