---
title: 工具使用疑難排解
url: https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/troubleshooting-tool-use
description: 透過「症狀對應修正」診斷表，修正最常見的工具使用錯誤。
---

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

## 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 ... block` | 後續請求使等待中的伺服器工具無法執行 | 請參閱[伺服器工具呼叫沒有結果區塊](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/troubleshooting-tool-use#a-server-tool-call-has-no-result-block)。 |
| `Unsupported regex feature in pattern field: ...` | 嚴格工具的 `pattern` 使用了嚴格模式無法編譯的正規表示式功能，例如反向參照、單字邊界，或過大的 `{n,m}` 範圍 | 簡化該 regex 模式。請參閱 [JSON Schema 限制](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#json-schema-limitations)。 |
| `Invalid regex in pattern field: ...` | 嚴格工具的 `pattern` 含有前瞻（lookahead）、後顧（lookbehind）或語法錯誤 | 移除任何前瞻或後顧，並修正任何語法錯誤。請參閱 [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`。 |

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

當[伺服器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/server-tools)的 `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` 訊息結尾。

完整步驟請參閱[當伺服器工具仍在等待時](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons#when-a-server-tool-is-still-waiting)以及 [`pause_turn` 停止原因](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons#pause-turn)。

## 錯誤：思考區塊無法被修改

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

完整的錯誤說明與修正步驟，請參閱[思考區塊不可修改](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()` 進行解析。切勿對序列化後的輸入進行原始字串比對。 |

## 後續步驟

<CardGroup cols={3}>
  <Card title="定義工具" href="https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/define-tools">
    撰寫能引導 Claude 選用正確工具的 schema 與描述。
  </Card>

  <Card title="處理工具呼叫" href="https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/handle-tool-calls">
    執行工具並以所需的訊息格式回傳結果。
  </Card>

  <Card title="工具參考" href="https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/tool-reference">
    Anthropic 所提供工具及其版本字串的完整目錄。
  </Card>
</CardGroup>
