Claude Platform Docs
Messages工具

工具使用疑難排解

透過「症狀對應修正」診斷表,修正最常見的工具使用錯誤。

找出您遇到的症狀或錯誤,然後套用其對應列出的修正方式。

Claude 呼叫了錯誤的工具

症狀可能原因修正方式
您想要工具 B,但 Claude 呼叫了工具 A描述含糊不清讓描述更精確。以「何時」使用來區分工具,而不僅是它們「做什麼」。請參閱定義工具。
Claude 從未呼叫您的工具工具名稱衝突或 schema 過於籠統檢查您的工具清單中是否有重複名稱。加入 input_examples,讓預期用途更具體。
Claude 呼叫時使用了錯誤的參數型別schema 模稜兩可加入 strict: true(若您的 schema 屬於支援的子集)或加入 input_examples。

Claude 捏造工具參數

症狀可能原因修正方式
出現您的 schema 中不存在的參數未啟用嚴格模式時模型過度生成若您的 schema 屬於支援的子集,請加入 strict: true。
參數值超出您的 enum 範圍缺少嚴格模式或 enum 過大縮小 enum,或加入 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 ... block後續請求使等待中的伺服器工具無法執行請參閱伺服器工具呼叫沒有結果區塊。
Unsupported regex feature in pattern field: ...嚴格工具的 pattern 使用了嚴格模式無法編譯的正規表示式功能,例如反向參照、單字邊界,或過大的 {n,m} 範圍簡化該 regex 模式。請參閱 JSON Schema 限制。
Invalid regex in pattern field: ...嚴格工具的 pattern 含有前瞻(lookahead)、後顧(lookbehind)或語法錯誤移除任何前瞻或後顧,並修正任何語法錯誤。請參閱 JSON Schema 限制。
All tools have defer_loading: true模型看不到任何工具至少必須有一個工具是立即載入的。工具搜尋工具本身絕不可設定 defer_loading: true。

伺服器工具呼叫沒有結果區塊

當伺服器工具的 server_tool_use 或 mcp_tool_use 區塊沒有結果區塊時,該工具仍在等待執行。錯誤 was found without a corresponding ... block 表示後續請求使等待中的工具無法執行。錯誤訊息與上一次的 stop_reason 會顯示原因。請採用第一個符合的情況:

  • 訊息以 but no `<name>` tool was provided 或 is not available after the last message 結尾: 此處的 <name> 是工具的名稱,例如 web_search。請求不再定義該工具。請傳送與先前相同的 tools 陣列;若是 MCP 工具,也請傳送相同的 mcp_servers。
  • 上一次的 stop_reason 為 tool_use: 您的使用者訊息在 tool_result 區塊之後還有其他內容。請只傳送 tool_result 區塊,每個用戶端 tool_use 區塊對應一個。
  • 上一次的 stop_reason 為 pause_turn: 您新增了一則使用者訊息。請將其移除,讓請求以暫停的回應作為 assistant 訊息結尾。

完整步驟請參閱當伺服器工具仍在等待時以及 pause_turn 停止原因。

錯誤:思考區塊無法被修改

若在工具呼叫後繼續對話時,請求以 400 invalid_request_error 失敗,且其訊息包含 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified,表示您的應用程式在將助理的思考區塊送回之前對其進行了更動。請將整則助理訊息原封不動地送回,然後再附加您的 tool_result。

完整的錯誤說明與修正步驟,請參閱思考區塊不可修改。

Claude 將工具結果標記為提示注入

症狀可能原因修正方式
Claude 拒絕依據工具結果採取行動,或要求使用者確認來自該結果的指令您自己的指令被放在 tool_result 內容中傳遞Claude 經過訓練,會將工具結果中的指令視為可能不受信任的第三方內容。請將您的指令移出工具結果:在 tool_result 區塊之後以 user 輪次傳送,或在支援的模型上使用對話中途系統訊息。讓工具結果只包含資料。請參閱緩解越獄與提示注入。

不同模型版本之間的 JSON 跳脫差異

症狀原因修正方式
對工具輸入進行字串比對在較新模型上失敗不同模型版本之間的 Unicode 與正斜線跳脫方式不同使用 json.loads() 或 JSON.parse() 進行解析。切勿對序列化後的輸入進行原始字串比對。

後續步驟

撰寫能引導 Claude 選用正確工具的 schema 與描述。

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

Anthropic 所提供工具及其版本字串的完整目錄。

這個頁面有幫助嗎?