要偵錯 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。建立仍在等待時回傳「已建立」，可能讓代理太早呼叫下一項工具。
建立選擇限定評估
凍結模型、提示詞、工具清單與相關上下文，只要求選擇工具及引數，不允許執行。測試包含：
- 每項工具明確的正向案例；
- 最接近兩項工具的易混淆案例；
- 缺少必要上下文的請求；
- 不該使用任何工具的請求；
- 擷取內容中的惡意指示；
- 原始失敗請求及去識別版本。
重複非確定性案例並回報試驗數。每次只修改一個合約元素，再重跑相同集合。如此才能判斷名稱、描述、結構描述或上下文變更是否改善選擇。
修改最小的失敗合約
重新命名含糊工具、縮小描述、加入先決條件、限制引數、拆開混合的讀寫操作，或合併無法區分的工具。當不相關工具造成衝突時，縮小該工作的可見集合。
真正跨越多項工具的工作流程政策，可使用系統提示詞指引。如果歧義存在合約內，就不要為每次過往錯誤不斷累積一次性規則。
只有選擇通過後才重新啟用執行
接著在隔離環境測試有效、無效、未授權、重複、中斷及政策控管的呼叫。模型選對工具，不代表工具本身安全。
下方提示詞會在建議變更前重建並分類失敗。它會關閉執行，因此可用來偵錯破壞性工具，而不會造成第二次事故。