Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
針對最常見的工具使用錯誤，提供症狀對應修復方法的表格。每個修復方法都會交叉引用擁有該功能的頁面。
| 症狀 | 可能原因 | 修復方法 |
|---|---|---|
| 當您想要工具 B 時，Claude 卻呼叫了工具 A | 描述含糊不清 | 讓描述更精確。以「何時」使用工具來區分工具，而不僅僅是它們「做什麼」。請參閱定義工具。 |
| Claude 從不呼叫您的工具 | 工具名稱衝突或 schema 過於籠統 | 檢查您的工具清單中是否有重複的名稱。新增 input_examples 讓預期用途更具體。 |
| Claude 呼叫時使用了錯誤的參數類型 | 模型對含糊的 schema 進行猜測 | 新增 strict: true（如果您的 schema 在支援的子集內）或新增 input_examples。 |
| 症狀 | 可能原因 | 修復方法 |
|---|---|---|
| 您的 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 <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。 |
如果在工具呼叫後繼續對話時，請求失敗並出現 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?