WebMCP 最佳做法

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

發布日期：2026 年 5 月 18 日

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

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

我們已另行撰寫文章，說明如何打造注重安全性的工具。

制定工具策略

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

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

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

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

使用明確的語言和語意程式碼

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

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

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

錯誤做法
「請勿使用這項工具查詢天氣。」

完善的說明應會隱含限制。

正確做法

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

這種語言會描述工具可執行的動作，而不是告訴模型「該做什麼」。

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

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

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

優先考量可靠性

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

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

評估測試和偵錯

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

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

請避免新增狹義規則來修正特定模型的問題。舉例來說，如果您加入「敬稱」的選取欄位，模型可能會做出錯誤選擇。請抽象化並調整工具，而非新增狹義規則來修正這個問題。將這個欄位設為選填或許是最佳做法。接著，請代理程式詢問使用者哪種選擇較合理，確保使用者對結果感到滿意。

參與討論及分享意見

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