WebMCP 最佳做法

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

發布日期：2026 年 5 月 18 日

WebMCP 工具聲明應清楚明瞭，開發人員或代理商不必查看輸出內容並重試。無論您使用命令式 API 或宣告式 API，都請遵循下列最佳做法：

  • 建構工具前，請先制定工具策略。
  • 使用明確的語言和語意式 HTML。
  • 設計結構定義並處理輸入內容。
  • 建構可靠的工具。
  • 測試及偵錯。

制定工具策略

就像使用任何軟體應用程式一樣，您首先應規劃工具策略：

  • 每個工具都應只包含一個函式。舉例來說，其中一項工具可將使用者導向特定表單類型，另一項工具則應將輸入欄位與使用者資訊相符。請勿建立重疊的工具，否則代理程式可能會不知道該使用哪個工具。請自問：我是否能以同一函式涵蓋多項工作？
  • 管理工具註冊。在特定頁面狀態下註冊實用工具，然後在工具無法再使用時取消註冊。
    • 命令式 API：您可以使用 registerTool 和 unregisterTool 動態管理註冊程序。
    • 宣告式 API：您可以使用 toolName 和 toolDescription，在表單上新增或移除工具屬性，動態管理註冊程序。
  • 降低複雜度：對於大多數應用程式，靜態註冊應為預設方法。
  • 信任代理程式來完成工作*。請勿撰寫僵硬或負面指令，而是假設代理程式能夠瞭解完成工作所需的事項，而非期望代理程式管理確切的步驟流程。

雖然沒有工具數量上限，但每個工具都會占用部分內容視窗，並增加完成時間。提供的工具越多，工具的重疊程度越高，代理就越難正確選擇。透過實驗找出適合應用程式的圖片。

這有助於您建立用途不重複的個別工具，並管理這些工具的可用時間。

使用清楚明瞭的語言和語意程式碼

使用清楚直白的語言命名工具，並說明工具用途。這有助於代理程式找到所需內容、瞭解找到的內容，並按照開發人員的預期使用該資訊。

撰寫工具名稱時，請區分執行和啟動，並使用動詞確切描述發生的情況。舉例來說，create-event 是用於立即建立事件的工具，但 start-event-creation-process 會將使用者重新導向至表單，以便建立事件。

清楚的說明應描述工具的功能及使用時機。使用正向用語和偏好設定，而非負面用語 (例如限制)。

錯誤做法

「Don't use this tool for weather.」

說明應清楚指出限制。
正確做法

「這項工具可以建立日曆活動，並安排在特定日期和時間。」

盡量避免造成認知上的負擔

就像人類在完成複雜工作時應盡量避免認知上的負擔，模型也應盡量避免認知運算：

  • 接受原始使用者輸入內容。請避免要求代理程式執行數學運算或轉換輸入字串。舉例來說，如果使用者說出「11:00 到 15:00」，工具應將此視為字串。請避免要求模型計算這兩個時間點之間的分鐘數。
  • 為參數宣告特定型別，例如字串、數字或列舉。
  • 說明您做出特定選擇的原因。您所做的選擇應該不難理解。瞭解原因有助於代理人做出更明智的選擇。舉例來說，如果你經營電子商務商店，請以自然語言宣告運送類型，而非使用含糊不清的 ID：shipping="Express"，而非 shipping_id=1。

優先考慮可靠性

如果工具的行為符合預期，代理程式和人類都能受益：

  • 設定頻率限制的正常失敗。工具應允許合理的重複次數，例如價格比較。如果工具受到速率限制，請傳回有意義的錯誤，或建議使用者手動執行工作。
  • 在函式完成後更新介面狀態。代理可能會依賴介面規劃後續步驟，而函式完成所需的時間可能比介面載入時間長。介面更新後，代理程式應確認函式已完成，或再次要求更新。
  • 在程式碼中嚴格驗證，在結構定義中寬鬆驗證。對於具有二進位邏輯的函式和程式碼，應使用限制和測試。雖然結構定義限制很有幫助，但不保證一定能解決問題。在函式程式碼中加入描述性錯誤，讓模型自我修正，並使用新的有效參數重試。

Eval 測試和偵錯

建立評估測試，並提供偵錯工具。與確定性單元測試不同，評估作業無法硬式編碼，因為輸出內容可能採取無法預期的形式。

  • 定義問題。您可以將問題架構為 API 合約，包括輸入類型、輸出格式和任何其他限制。
  • 定義基準和理想結果。特別是輸入文字時，請務必瞭解哪些類型的結果可產生您預期的輸出內容。
  • 決定如何評估輸出內容。您可能會根據輸入內容品質、實用性，以及完成後續工作的能力，識別及評估主觀的質性結果。您可以使用多種技術評估輸出內容，包括根據程式碼檢查規則型輸出內容 (字元限制)，以及LLM-as-a-judge。

請勿新增範圍狹窄的規則，以修正特定模型的問題。舉例來說，如果加入敬稱的選取欄位，模型可能會做出錯誤選擇。請抽象化及調整工具，而非新增範圍較窄的規則來修補這個問題。建議將這個欄位設為選填。然後請服務專員詢問使用者哪個選項較合適，確保使用者滿意結果。

參與討論及分享意見

WebMCP 目前仍在討論階段，日後可能會有變動。歡迎試用這些 API 並提供意見。