如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
總覽 智慧體存取權 ChatGPT 與 Codex 使用者文件 使用案例

定義工具

根據外掛程式的使用情境,規劃一組用途明確的 MCP 工具。

外掛程式的 MCP 伺服器透過工具,讓 ChatGPT 和 Codex 執行動作及取得資料。請先構思使用情境,再定義工具,最後才實作伺服器。

每個工具都應協助使用者達成目標。設計工具時,請考慮使用者會如何提出需求及使用這項功能,避免直接照搬內部 API。

根據使用情境規劃工具

針對每個支援的使用情境,依序完成以下步驟:

  1. 寫下使用者預期的結果。
  2. 列出產生該結果所需的資訊。
  3. 找出伺服器必須執行的讀取、寫入或外部動作。
  4. 將共同完成同一項動作的操作歸為一組。
  5. 如果各項操作所需的權限、涉及的安全風險或確認要求不同,請將它們拆開。

例如,專案管理外掛程式可以提供下列工具:

  • list_projects 用於尋找專案。
  • get_project 用於查看單一專案。
  • create_project 用於建立專案。
  • update_project 用於修改專案詳細資料。
  • archive_project 用於封存專案,這項動作會變更專案狀態,影響重大。

請將讀取與寫入操作分開,讓模型和使用者都能區分哪些操作只會取得資訊,哪些會變更狀態。

定義每個工具的契約

針對每個預計提供的工具,記錄以下內容:

欄位 定義內容
名稱 能表明工具執行何種動作的穩定識別碼。
標題 以簡短易懂的文字說明工具執行的動作。
說明 使用者的目標,以及應觸發工具的條件。
輸入結構描述 必填與選填參數,以及各參數的型別、允許值和限制。
輸出結構描述 模型可以檢視並重複使用的結構化欄位。
授權 伺服器必須驗證的帳戶、角色或資源存取權限。
副作用 工具可能變更的資料或外部狀態。
失敗時的行為 模型能夠解釋或能從中復原的錯誤。

請明確指定輸入。凡是執行操作時必須正確提供的值,例如識別碼或帳戶範圍,都不應由模型猜測。

請傳回穩定的識別碼,以及後續呼叫所需的足夠結構化資訊。結果中不應包含機密資訊、存取權杖、內部診斷資訊或非必要的個人資料。

撰寫說明,協助模型選擇工具

模型會根據工具說明,判斷工具何時適合處理某項要求。撰寫說明時,請著重於使用者的意圖,避免描述實作細節。

好的工具說明應做到以下幾點:

  • 說明工具能做什麼。
  • 解釋何時應使用這項工具。
  • 說清楚它與類似工具的差異。
  • 指出重要限制或先決條件。

請避免只重述工具名稱,也不要使用使用者不熟悉的內部服務術語。

規劃安全註記

請根據工具的實際行為設定註記。各項提示的正式定義、預設值及彼此之間的關係,請參閱 MCP 的 ToolAnnotations 結構描述。

  • readOnlyHint 只有在工具無法變更狀態時才設為 true。
  • destructiveHint 在工具可能造成不可逆或難以復原的結果時設為 true。
  • openWorldHint 在工具會存取公開網際網路,或會接觸範圍不受限的外部對象時設為 true。即使只執行網頁搜尋等唯讀動作,也適用這項規則。範圍明確的私人帳戶或工作區,即使由外部代管,也不會單憑這一點就被視為開放世界。

即使設定了註記,伺服器端仍須執行授權檢查與輸入驗證,並在執行影響重大的動作前要求確認。

檢查工具的涵蓋範圍與界線

將預計提供的工具與完整的使用情境清單逐一比對:

  1. 確認每個支援的使用情境都有可行的方法,讓使用者取得有用的結果。
  2. 找出沒有對應到任何已記錄使用情境的工具。
  3. 檢查是否缺少使用者在執行寫入動作前所需的讀取操作。
  4. 確認遇到不支援的要求時,系統會以易懂的方式說明限制,避免以不安全的方式勉強滿足要求。
  5. 測試兩個類似工具的說明是否有重疊之處,導致模型難以判斷該選哪一個。

保留這份工具規劃,作為實作與評估時的檢查清單。接著建置 MCP 伺服器,並分別使用具代表性、無效及未經授權的輸入測試每個工具的契約。