Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
針對最常見的「tool use」（工具使用）錯誤所整理的症狀對應修正表。每項修正都會交叉參照負責該功能的頁面。
| 症狀 | 可能原因 | 修正方式 |
|---|---|---|
| 您想要工具 B，但 Claude 呼叫了工具 A | 描述含糊不清 | 讓描述更精確。以「何時」使用來區分工具，而不僅是它們「做什麼」。請參閱定義工具。 |
| Claude 從不呼叫您的工具 | 工具名稱衝突或結構描述過於籠統 | 檢查工具清單中是否有重複的名稱。加入 input_examples 讓預期用途更具體。 |
| Claude 呼叫時使用了錯誤的參數型別 | 模型在含糊的結構描述下進行猜測 | 加入 strict: true（若您的結構描述屬於支援的子集），或加入 input_examples。 |
| 症狀 | 可能原因 | 修正方式 |
|---|---|---|
| 出現您的結構描述中不存在的參數 | 未啟用嚴格模式時模型過度生成 | 若您的結構描述屬於支援的子集，請加入 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 <name>_tool_result block | 前一個助理輪次含有一個沒有結果區塊的 server_tool_use 區塊（最常見的情況是 Claude 將它與某個用戶端工具一同呼叫），而且您的下一則使用者訊息結束了該輪次（例如在 tool_result 區塊之後加上文字），或是恢復請求中不再定義該伺服器工具（此時訊息結尾會是 but no <name> tool was provided） | 傳送一則僅包含用戶端 tool_use id 對應之 tool_result 區塊的使用者訊息，並保持相同的 tools 陣列。請參閱停止原因與後備處理。 |
Unsupported regex feature in pattern field: ... | 嚴格工具的 input_schema 中某個 pattern 使用了嚴格模式無法編譯的正規表示式功能，例如反向參照、環視（lookaround）、單字邊界，或過大的 {n,m} 範圍 | 簡化該 pattern。支援帶錨點且使用基本量詞、字元類別與群組的 pattern；請參閱 JSON Schema 限制。 |
All tools have defer_loading: true | 模型看不到任何工具 | 至少必須有一個工具立即載入。工具搜尋工具本身絕不可設為 defer_loading: true。 |
若在工具呼叫後繼續對話時，請求以 400 invalid_request_error 失敗，且其訊息包含 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified，表示您的應用程式在將助理的 thinking 區塊送回之前對其進行了更動。請將整則助理訊息原封不動地送回，然後再附加您的 tool_result。
完整的錯誤說明與修正步驟，請參閱 Thinking 區塊無法修改。
| 症狀 | 可能原因 | 修正方式 |
|---|---|---|
| Claude 拒絕依據工具結果採取行動，或要求使用者確認來自該結果的指令 | 您自己的指令被放在 tool_result 內容中傳遞 | Claude 經過訓練，會將工具結果中的指令視為可能不受信任的第三方內容。請將您的指令移出工具結果：在 tool_result 區塊之後的 user 輪次中傳送，或在支援的模型上使用對話中途系統訊息傳送。讓工具結果只包含資料。請參閱緩解越獄與提示注入。 |
| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 對工具輸入進行字串比對在較新模型上失敗 | Unicode 與正斜線的跳脫方式在不同模型版本之間有所差異 | 使用 json.loads() 或 JSON.parse() 進行解析。切勿對序列化後的輸入進行原始字串比對。 |
Was this page helpful?