工具是外掛程式的 MCP 伺服器提供給 ChatGPT 與 Codex 的動作和資料。請先 構思使用案例，再定義工具，最後才實作 伺服器。
每個工具都應協助使用者達成目標。不要直接照搬內部 API， 而不考慮使用者會如何提出需求及使用這項功能。
將使用案例對應至工具
針對每個支援的使用案例：
- 寫下使用者預期的結果。
- 列出達成該結果所需的資訊。
- 找出伺服器必須執行的讀取、寫入或外部動作。
- 將共同構成一個完整動作的操作歸為一組。
- 若操作的權限、安全風險或 確認要求不同，請將它們分開。
例如，專案外掛程式可以提供：
list_projects：尋找專案。get_project：檢視單一專案。create_project：建立專案。update_project：變更專案詳細資料。archive_project：執行會造成重大影響的狀態變更。
將讀取與寫入行為分開，讓模型和使用者能區分 資訊檢索與會變更狀態的動作。
定義各工具的契約
針對每個規劃中的工具，記錄以下內容：
| 欄位 | 需定義的內容 |
|---|---|
| 名稱 | 穩定且能表達動作的識別碼。 |
| 標題 | 簡潔易懂的動作名稱。 |
| 說明 | 應觸發此工具的使用者目標與條件。 |
| 輸入結構描述 | 必要與選用參數、型別、允許的值及限制。 |
| 輸出結構描述 | 模型可檢視及重複使用的結構化欄位。 |
| 授權 | 伺服器必須驗證的帳戶、角色或資源存取權。 |
| 副作用 | 工具可變更的資料或外部狀態。 |
| 失敗時的行為 | 模型能說明或能從中復原的錯誤。 |
明確指定輸入。不要依賴模型猜測識別碼、帳戶範圍， 或其他確保操作正確所需的值。
回傳穩定的識別碼與足夠的結構化資訊，以供後續呼叫使用。 結果中不應包含機密資訊、存取權杖、內部診斷資訊， 以及不必要的個人資料。
撰寫有助於選擇工具的說明
模型會根據工具說明，判斷工具是否適合處理某項請求。 說明應描述使用者意圖，而非實作方式。
好的說明應：
- 指出工具的功能。
- 解釋何時該使用它。
- 說明它與類似工具的差異。
- 點出重要限制或必要條件。
避免只重述工具名稱， 或使用使用者不熟悉的內部服務術語。
規劃安全註記
請依據實際行為設定註記。請參閱 MCP
ToolAnnotations
結構描述，
了解這些提示的標準定義、預設值及彼此之間的交互作用：
- 只有在工具無法變更狀態時，
readOnlyHint才能設為true。 - 當工具可能造成無法復原或難以復原的結果時，
destructiveHint應設為true。 - 當工具會存取公開網際網路或範圍未限定的外部實體時，
openWorldHint應設為true，即使只是執行網頁搜尋等唯讀動作也一樣。 範圍明確的私人帳戶或工作區，並不會僅因 託管於外部就被視為開放世界。
註記不能取代伺服器端的授權、輸入驗證， 或執行重大影響動作前的確認。
檢查涵蓋範圍與界線
將規劃中的工具與完整的使用案例清單逐一比對：
- 確認每個支援的使用案例都有可行的途徑，能產生有用的結果。
- 找出未對應任何已記錄使用案例的工具。
- 檢查是否遺漏了使用者在執行寫入動作前所需的讀取操作。
- 確認遇到不支援的請求時，系統會清楚說明限制， 而不是以不安全的方式勉強處理。
- 測試兩個類似工具的說明是否有重疊， 導致選擇工具時產生混淆。
保留整理好的工具計畫，作為實作與評估的檢查清單。 接著建置 MCP 伺服器，並使用具代表性、無效及未經授權的輸入， 測試每項契約。