如何設計 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、結果類別與時間。

錯誤工具偵錯指南說明選擇測試失敗時，該如何利用這些追蹤資料。

從完整工具清單開始

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

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