工作層級的代理 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，每項描述都應說明自己負責哪一種實體及工作。如果無法寫出清楚區別，就合併工具或移除其中一項。
偵錯錯誤工具選擇指南會先從工具清單與呼叫追蹤開始，而不是先修改系統提示詞。
分開測試選擇與執行
建立應選擇每一項工具的提示詞，以及任何工具都不該選擇的提示詞。固定工具清單、描述、模型與設定，並在執行任何內容前記錄選擇。
接著，以有效、無效、未授權及重複輸入測試執行。容易選對的工具，叫用時仍可能不安全。
先重寫最接近的一對工具
找出描述中共用最多詞彙的兩項工具，分別寫下工作、使用條件、排除事項、副作用及下一步結果。如果區別仍不清楚，很可能是內部實作邊界洩漏到了代理介面。
下方提示詞會執行這項歧義測試，並建立聚焦的評估集合。