如何設計 AI 代理能可靠使用的 MCP 工具

可靠的 MCP 工具有明確的工作名稱、有界限的輸入、結構化輸出、穩定錯誤、下游授權和安全寫入行為。工具必須以完整集合進行測試，因為選擇失敗往往來自兩份單獨看來都有效的定義互相重疊。

先從只測試選擇的評估開始，這能夠在錯誤調用尚未接觸後端時發現歧義。

每項工具只負責一件事

使用符合用戶工作的動詞和受詞。get_order_status 比 query_order_service 清楚。避免 execute、manage、process 或 run_query 等通用名稱，除非廣泛能力是刻意設計，而且限制非常嚴格。

描述應回答：

1. 工具會產生甚麼結果？
2. 模型應在何時使用？
3. 模型應在何時改用另一項工具或完全不用工具？
4. 工具會產生哪些外部副作用？

工作層級 API 指南並列比較較弱和較強的合約。

維持精簡而受限的輸入

使用 JSON Schema 表達必填欄位、列舉、格式、長度和數值範圍。如果用戶或前一項工具已經識別資源，應使用穩定的資源 ID，而不是自由文字描述。

不要要求模型提供伺服器能夠從已驗證上下文推導的值。租戶 ID、用戶 ID 和供應商憑證通常屬於工作階段或伺服器，不應出現在工具參數中。

對變更操作，如果後端合約要求，應接受操作或冪等鍵。不要在自動重試中產生新的鍵，否則重試會變成另一項新操作。

傳回可供下一個決策使用的結果

目前的 MCP 工具規格支援選用的輸出結構描述和 structuredContent，也建議同時傳回文字表示，以相容其他客戶端。

傳回範圍明確的數據結構，其中只包含代理下一步需要的權威欄位：

{
  "deploymentId": "dep_1842",
  "state": "pending",
  "statusUrl": "/deployments/dep_1842",
  "retryAfterSeconds": 10
}

預設不要傳回完整的供應商回應，其中通常有不穩定欄位、內部識別碼、過量文字或密鑰。

分開協定錯誤與領域錯誤

MCP 請求本身無效或伺服器無法處理時，使用協定錯誤。工具已執行但業務操作失敗時，則傳回帶有穩定領域錯誤的 isError: true。

有用的領域錯誤會告訴調用者下一步：

絕對不要在模型可見的錯誤中加入 stack trace、數據庫訊息或憑證。

在工具背後執行授權

伺服器應驗證客戶端與其代表的用戶身份。下游 API 應針對租戶、資源和操作授權該身份。工具清單並不是存取控制清單。

MCP 身份驗證指南解釋綁定 audience 的存取權杖和獨立的上游憑證。

讓寫入能安全地重複執行

對每一項會建立、更新、傳送、支出或刪除的工具：

• 定義一個邏輯操作識別碼；
• 儲存或對應其結果；
• 拒絕配搭衝突參數重用；
• 記載逾時後結果未知的情況；
• 在影響重大的執行前加入批准；
• 如果後端支援，優先使用可復原的刪除。

客戶端重試和伺服器重試可能相乘。應決定由哪一層負責重試，並把每次嘗試記在同一個操作之下。

將註解視為顯示提示

MCP 工具註解可以描述唯讀、破壞性、冪等或開放世界行為，但客戶端不能信任來自不受信任伺服器的註解。可以用它們改善呈現方式，同時在程式碼中執行相同的限制。

分開評估選擇與執行

選擇測試固定模型能看到的工具集，再要求模型決定要調用哪一項。測試應包含：

• 每項工具明確的正向工作；
• 最接近兩項工具的易混淆工作；
• 缺少必要上下文的請求；
• 不應調用任何工具的請求；
• 擷取數據中的對抗性內容。

執行測試會使用有效、無效、未獲授權、重複和中斷的請求調用選定工具。記錄工具名稱、遮蔽後的參數、政策決策、操作 ID、結果類別和時間。

錯誤工具除錯指南解釋選擇測試失敗時，應如何利用這些追蹤數據。

從完整工具清單開始

匯出模型實際看見的完整清單。逐一閱讀工具檔案會掩蓋衝突。按照共用名詞、動詞、描述和參數結構為工具配對排序，再為最接近的一對編寫易混淆工作。

下方提示會建立這份評估集合，而且不會調用任何工具。