--- title: 工具使用疑難排解 url: https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/troubleshooting-tool-use description: 透過「症狀對應修正」診斷表，修正最常見的工具使用錯誤。 --- 針對最常見的「tool use」（工具使用）錯誤所整理的症狀對應修正表。每項修正都會交叉參照負責該功能的頁面。 ## Claude 呼叫了錯誤的工具 | 症狀 | 可能原因 | 修正方式 | | ------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------- | | 您想要工具 B，但 Claude 呼叫了工具 A | 描述含糊不清 | 讓描述更精確。以「何時」使用來區分工具，而不僅是它們「做什麼」。請參閱[定義工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/define-tools)。 | | Claude 從不呼叫您的工具 | 工具名稱衝突或 schema 過於籠統 | 檢查工具清單中是否有重複的名稱。加入 `input_examples` 讓預期用途更具體。 | | Claude 呼叫時使用了錯誤的參數型別 | 模型對含糊的 schema 進行猜測 | 加入 `strict: true`（若您的 schema 屬於支援的子集），或加入 `input_examples`。 | ## Claude 捏造工具參數 | 症狀 | 可能原因 | 修正方式 | | ------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- | | 出現您的 schema 中不存在的參數 | 未啟用嚴格模式時模型過度生成 | 若您的 schema 屬於[支援的子集](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/strict-tool-use)，請加入 `strict: true`。 | | 參數值超出您的 enum 範圍 | 缺少嚴格模式或 enum 過大 | 縮小 enum，或加入 `input_examples` 以展示有效的選項。 | ## 平行工具呼叫無法運作 | 症狀 | 可能原因 | 修正方式 | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 在平行呼叫較佳的情況下，Claude 卻依序呼叫工具 | 訊息歷史格式問題 | 在「同一則」使用者訊息中傳送多個 `tool_result` 區塊，而非每輪傳送一個。請參閱[平行工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/parallel-tool-use)。 | | `disable_parallel_tool_use` 似乎被忽略 | 在對話中設定得太晚 | 必須在回傳 `tool_use` 的那個請求上設定。在之後的請求上設定，對先前的工具呼叫沒有任何效果。 | ## 快取不斷失效 | 症狀 | 可能原因 | 修正方式 | | -------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 每個請求都是快取未命中 | `tool_choice`、思考設定或 `output_config.effort` 在各請求之間有所變動 | 保持 `tool_choice` 穩定，或將 `cache_control` 斷點放在變動點之前；在快取對話的整個生命週期內，保持思考設定與 effort 等級不變。請參閱[搭配提示快取的工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-use-with-prompt-caching)以及[思考與提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-prompt-caching)。 | | 在對話中途新增工具會破壞快取 | 工具被加到 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` 區塊放在任何文字之前。請參閱[處理工具呼叫](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/handle-tool-calls)以及[平行工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/parallel-tool-use)。 | | `was found without a corresponding _tool_result block` | 前一個助理輪次含有一個沒有結果區塊的 `server_tool_use` 區塊（最常見的情況是 Claude 將它與某個用戶端工具一起呼叫），而且您的下一則使用者訊息結束了該輪次（例如在 `tool_result` 區塊之後加上文字），或是恢復請求中不再定義該伺服器工具（此時訊息結尾會是 `but no tool was provided`） | 傳送一則僅包含用戶端 `tool_use` id 對應之 `tool_result` 區塊的使用者訊息，並保持相同的 `tools` 陣列。請參閱[停止原因與後備處理](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons#tool-use)。 | | `Unsupported regex feature in pattern field: ...` | 嚴格工具的 `input_schema` 中某個 `pattern` 使用了嚴格模式無法編譯的正規表示式功能，例如反向參照、環視（lookaround）、單字邊界，或過大的 `{n,m}` 範圍 | 簡化該 pattern。支援帶錨點且使用基本量詞、字元類別與群組的 pattern；請參閱 [JSON Schema 限制](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#json-schema-limitations)。 | | `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 區塊無法被修改](https://platform.claude.com/docs/zh-TW/api/errors#thinking-blocks-cannot-be-modified)。 ## Claude 將工具結果標記為提示注入 | 症狀 | 可能原因 | 修正方式 | | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Claude 拒絕依據工具結果採取行動，或要求使用者確認來自該結果的指令 | 您自己的指令被放在 `tool_result` 內容中傳遞 | Claude 經過訓練，會將工具結果中的指令視為可能不受信任的第三方內容。請將您的指令移出工具結果：在 `tool_result` 區塊之後以 `user` 輪次傳送，或在支援的模型上使用[對話中途系統訊息](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages)。讓工具結果只包含資料。請參閱[緩解越獄與提示注入](https://platform.claude.com/docs/zh-TW/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection)。 | ## 不同模型版本之間的 JSON 跳脫差異 | 症狀 | 原因 | 修正方式 | | ------------------- | ---------------------------- | ----------------------------------------------------------- | | 對工具輸入進行字串比對在較新模型上失敗 | 不同模型版本之間的 Unicode 與正斜線跳脫方式不同 | 使用 `json.loads()` 或 `JSON.parse()` 進行解析。切勿對序列化後的輸入進行原始字串比對。 | ## 後續步驟 撰寫能引導 Claude 選用正確工具的 schema 與描述。 執行工具並以規定的訊息格式回傳結果。 Anthropic 所提供工具及其版本字串的完整目錄。