要為 AI 代理使用錯誤工具的問題除錯，應重建模型當時看到的確切工具清單和情境，再於不執行任何操作的情況下測試選擇。許多失敗源於名稱、描述、參數結構重疊或缺少情境，但追蹤也可能顯示工具選擇正確，只是結果有問題。
在能明確指出哪個階段失敗前，不要修改提示。
目前的 MCP 工具規格會向用戶端顯示名稱、描述、輸入結構描述和選用的輸出結構描述。這些都是可觀察的合約，因此在把問題歸因於隱藏的模型推理前，應先檢查它們。
準確分類失敗
- 選擇錯誤： 另一項可見工具更符合任務。
- 參數錯誤： 選擇了正確工具，但 ID、enum、範圍或必填欄位錯誤。
- 過早呼叫： 代理在取得必要情境或批准前，便使用了正確工具。
- 結果誤導： 工具正確呼叫後端，但傳回含糊、過時或格式不正確的回應。
- 執行不安全： 選擇有效，但工具背後的授權、冪等性或批准失敗。
這些情況需要不同的修改。當供應商在非同步工作完成前便傳回 ok，重新命名工具並不能解決問題。
取得確切的追蹤和工具集
記錄模型和版本、系統提示、檢索到的情境、對話前綴、完整的可見工具清單、工具定義、選定名稱、參數、結果、政策決定和下游結果。
完整清單十分重要。只閱讀兩個可疑檔案，可能會遺漏由插件或工作階段公開的第三項工具。在失敗執行中根本無法使用的工具，不可能解釋這次選擇。
代理可觀察性指南說明如何使用追蹤把工具選擇連接至後端副作用。
並列相似工具
[
{
"name": "list_files",
"description": "List entries directly inside one directory.",
"inputSchema": { "directory": "string" }
},
{
"name": "search_files",
"description": "Find files whose path or content matches a query across a directory tree.",
"inputSchema": { "directory": "string", "query": "string" }
}
]
這兩項描述說明了不同的輸出和觸發條件，其結構描述也會強化差異。「處理檔案」和「尋找檔案」這類籠統描述，會讓模型自行猜測邊界。
檢查共用動詞、名詞、描述、例子、必填欄位和結果形狀。如果兩項工具透過不同供應商實現相同的用戶意圖，應盡可能公開一項語意工具，再在後端選擇供應商。
讓參數配合任務語言
使用 order_id、customer_id 和 deployment_id，而不是三個毫無關聯的 id 欄位。加入 enum、格式、範圍和描述。從已驗證的情境取得租戶和用戶範圍，而不是要求模型提供。
如果工具需要代理不一定擁有的資訊，應說明先決條件，並傳回穩定的缺少情境錯誤。可以考慮使用另一項讀取工具取得識別碼，而不是接受猜測的自由文字值。
MCP 工具設計指南涵蓋有限的輸入和結構化錯誤。
歸咎於選擇前先檢查結果
結果應告訴代理發生了甚麼，以及接下來可以做甚麼。傳回穩定的狀態、資源或操作 ID，以及任何輪詢或批准要求。不要傳回完整的供應商負載或籠統的成功字串。
對於非同步工作，應區分 accepted、running、completed 和 failed。建立工作仍在等待時便傳回「已建立」，可能令代理過早呼叫下一項工具。
建立只測試選擇的評估
凍結模型、提示、工具清單和相關情境，只要求選擇工具和參數，不允許執行。測試應包括：
- 每項工具的明確正向案例；
- 最接近兩項工具的易混淆案例；
- 缺少必要情境的請求；
- 不應使用任何工具的請求；
- 檢索內容中的惡意指示；
- 原有的失敗請求和已移除識別數據的版本。
重複非確定性案例並報告試驗次數。每次只修改一項合約元素，再重新執行相同集合。這樣才能判斷名稱、描述、結構描述或情境變更是否改善選擇。
修改引致失敗的最小合約
重新命名含糊的工具、縮窄其描述、加入先決條件、限制參數、拆分混合讀寫操作，或合併無法區分的工具。當不相關工具造成衝突時，縮減該任務可見的工具集。
真正跨越多項工具的工作流程政策可以使用系統提示指引。如果歧義存在於合約內，就不要為過往每次錯誤不斷累積一次性規則。
只有選擇通過後才重新啟用執行
然後在隔離環境中測試有效、無效、未獲授權、重複、中斷和受政策閘道控制的呼叫。模型選擇正確的工具，並不代表工具本身安全。
下方提示會在建議變更前重建並分類失敗。它會關閉執行，因此可用於為具破壞性的工具除錯，而不會造成第二宗事故。