Messages工具

工具使用疑難排解

透過症狀對應修正方法的診斷表格，修正最常見的工具使用錯誤。

針對最常見的工具使用錯誤提供症狀對應修正方法的表格。每個修正方法都會交叉參照擁有該功能的頁面。

Claude 呼叫了錯誤的工具

症狀	可能原因	修正方法
您希望 Claude 呼叫工具 B，但它卻呼叫了工具 A	描述不明確	強化描述。透過「何時」使用工具來區分它們，而不僅是「做什麼」。請參閱定義工具。
Claude 從未呼叫您的工具	工具名稱衝突或結構描述過於通用	檢查您的工具清單中是否有重複的名稱。新增 `input_examples` 以使預期用途更具體。
Claude 使用錯誤的參數類型進行呼叫	模型對不明確的結構描述進行猜測	新增 `strict: true`（如果您的結構描述在支援的子集內）或新增 `input_examples`。

Claude 虛構工具參數

症狀	可能原因	修正方法
出現您的結構描述中不存在的參數	模型在沒有嚴格模式的情況下過度生成	如果您的結構描述在支援的子集內，請新增 `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`	將 `pattern` 與 `strict: true` 一起使用	移除 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()` 進行解析。切勿對序列化的輸入進行原始字串比對。

後續步驟

定義工具

撰寫結構描述和說明，引導 Claude 選擇正確的工具。

處理工具呼叫

執行工具並以所需的訊息格式傳回結果。

工具參考

Anthropic 結構描述工具及其版本字串的完整目錄。

Was this page helpful?

Messages工具

工具使用疑難排解

透過症狀對應修正方法的診斷表格，修正最常見的工具使用錯誤。

針對最常見的工具使用錯誤提供症狀對應修正方法的表格。每個修正方法都會交叉參照擁有該功能的頁面。

Claude 呼叫了錯誤的工具

症狀	可能原因	修正方法
您希望 Claude 呼叫工具 B，但它卻呼叫了工具 A	描述不明確	強化描述。透過「何時」使用工具來區分它們，而不僅是「做什麼」。請參閱定義工具。
Claude 從未呼叫您的工具	工具名稱衝突或結構描述過於通用	檢查您的工具清單中是否有重複的名稱。新增 `input_examples` 以使預期用途更具體。
Claude 使用錯誤的參數類型進行呼叫	模型對不明確的結構描述進行猜測	新增 `strict: true`（如果您的結構描述在支援的子集內）或新增 `input_examples`。

Claude 虛構工具參數

症狀	可能原因	修正方法
出現您的結構描述中不存在的參數	模型在沒有嚴格模式的情況下過度生成	如果您的結構描述在支援的子集內，請新增 `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`	將 `pattern` 與 `strict: true` 一起使用	移除 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()` 進行解析。切勿對序列化的輸入進行原始字串比對。

後續步驟

定義工具

撰寫結構描述和說明，引導 Claude 選擇正確的工具。

處理工具呼叫

執行工具並以所需的訊息格式傳回結果。

工具參考

Anthropic 結構描述工具及其版本字串的完整目錄。

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

後續步驟