工作層級的代理 API 會說明一項操作能完成甚麼、何時使用、何時不應使用，以及可能產生哪些副作用。端點結構只能解釋如何傳送請求；需要選擇工具的模型同時需要兩種資訊。
「語意」聽起來可能比這項工作複雜，實際改變很簡單：按照用戶工作設計工具，而不是按照數據庫數據表和內部服務邊界設計。
有效的端點仍可能含糊
看看以下 REST 操作：
POST /users/{id}/status
{"value":"inactive"}
方法、路徑、請求內容和回應都可以有完整文件，但合約仍沒有說明 inactive 是暫停登入、停止計費、移除指派、排程刪除，還是只改變 CRM 標籤。
開發者會閱讀周邊文件並釐清一次；模型則可能每次執行都要重新在多項工具之間選擇。
將意圖放進可調用合約
較弱的工具：
set_user_status
Set a user's status.
工作層級工具：
suspend_workspace_member
Temporarily block one member from signing in to this workspace.
Use when an administrator asks to suspend access without deleting the account.
Do not use for billing cancellation, workspace deletion, or permanent data removal.
第二份描述會告訴模型工作、權限、副作用和排除事項。其結構描述仍應在必要時識別工作區、成員、原因，以及批准或操作 ID。
MCP 工具規格為每項工具提供名稱、描述、輸入結構描述、選用的輸出結構描述和註解，但不會替你編寫這些邊界。
將一項工作對應到最精簡的實用結果
代理在選擇下一步時，很少需要後端的完整回應。只需傳回能夠決定下一步的欄位。
例如，查詢訂單時可能需要：
{
"orderId": "1842",
"status": "shipped",
"estimatedDelivery": "2026-09-02",
"canCancel": false
}
不要傳回內部數據庫欄位、供應商權杖或 200 KB 的承載數據，再要求模型自行找出答案。REST 轉 MCP 指南示範如何由轉換層把多個內部調用合併成一份工作結果。
說明副作用與失敗行為
每一項工具都應記載：
- 它會讀取、寫入、支出、傳送或刪除哪些內容；
- 適用哪一種調用者和資源授權；
- 是否需要批准；
- 操作是否能安全重試；
- 哪些穩定失敗會改變下一步；
- 哪些結果欄位具有權威性。
工具註解可以協助客戶端呈現風險，但客戶端必須將不受信任伺服器提供的註解視為不受信任。實際限制要由政策和後端執行。
清楚區分相似工具
功能重疊的工具需要明確的排除事項。如果伺服器提供 search_customers、find_contacts 和 query_accounts，每項描述都應說明自己負責哪一種實體和工作。如果無法寫出清楚區別，就合併工具或移除其中一項。
除錯錯誤工具選擇指南會先從工具清單和調用追蹤開始，而不是先修改系統提示。
分開測試選擇與執行
建立應選擇每一項工具的提示，以及任何工具都不應選擇的提示。固定工具清單、描述、模型和設定，並在執行任何內容前記錄選擇。
接着，以有效、無效、未獲授權和重複輸入測試執行。容易選對的工具，調用時仍可能不安全。
先重寫最接近的一對工具
找出描述中共用最多詞彙的兩項工具，分別寫下工作、使用條件、排除事項、副作用和下一步結果。如果區別仍不清楚，很可能是內部實作邊界洩漏到代理介面。
下方提示會執行這項歧義測試，並建立聚焦的評估集合。