Day 17｜Tool 執行完成後，應該回傳哪些資料給 Agent？

安安～我是ChiYu～

昨天的 get_event_details 終於不用再猜 current，能從目前頁面找到正確活動。照理說，
今天應該可以很輕鬆地把資料交給 Agent，讓它整理完就收工。

結果我一看 Tool result，新的問題立刻排隊進場：這份資料究竟是什麼，又應該交代到什麼
程度？

Tool result 是 handler 執行完成後，網站交回給 Agent 的結構化資料。它不是 Agent 最後對
使用者說的答案，也不應該是後端資料物件的完整副本。

一份實用的 result 至少要完成三件事：回答目前問題、提供下一步需要的識別資訊，以及交代
畫面或狀態是否已更新。資料太少，Agent 無法完成任務；資料太多，又可能把內部欄位一起送
進模型。

所以今天不增加新 Tool，而是把三種回傳方式放在一起比較，找出剛好足以完成任務的邊界。

今天沿用 v3-day-15，專心整理回傳契約

今天沒有新的程式里程碑。如果你昨天已經切到 v3-day-15，就留在同一版；單篇閱讀時再
執行 git switch --detach v3-day-15 即可。

原因很單純：昨天驗證的是 Tool 如何找到目前活動，今天則檢查同一支 Tool 找到資料後應該
回傳什麼。先固定 route 與 handler，不增加新功能，才能把「資料太少、資料太多、剛好夠用」
三種 payload 的差別看清楚。

比較三種回傳方式：資料太少、資料太多與剛好夠用

先看完整比較。左邊太省，中間太豪邁，右邊才是目前採用的方向：

圖 1：過度精簡的 result 無法回答問題；原始物件又帶入無關欄位。正式 payload 只保留公開任務、下一步與同步可見 UI 所需的資料。

這張圖裡最值得看的不是 JSON 大小，而是每個欄位有沒有工作。活動名稱要拿來回答使用者，
opaque ID 要交給下一個 Tool，stateVersion 則是用來判斷後續操作面對的是不是同一版狀態。
沒有任務的欄位，就不該因為「反正已經查到了」而一起塞進 result。

只回「找到活動」，execution 成功，任務卻還沒完成

第一種寫法最短：

{
  "message": "找到活動"
}

這份 result 可以證明 Tool 有跑完，卻回答不了使用者剛才問的名稱、地點、時間與剩餘
名額。下一步如果要收藏，Agent 也拿不到合法的 opaque ID。

它很像餐廳叫號只喊「餐點好了」，卻沒說是哪一桌。訊息沒有錯，但現場沒有人知道下一步
該做什麼。

直接回傳 server 物件，省下 mapping，也公開了內部結構

第二種做法對開發者很有誘惑力：API 查到什麼，Tool 就回什麼。

{
  "event": {
    "...": "資料庫欄位、內部旗標與尚未整理的內容"
  }
}

少寫一層 mapping 當下很舒服，代價是前端儲存格式直接變成公開契約。以後資料表改名、
內部狀態拆欄位，Agent 看到的 schema 也跟著震一下。更麻煩的是，像 internalOwnerId、
私人輸入、內部錯誤內容或未整理文案，可能在沒人要求的情況下進入模型 context。

Tool result 是模型的輸入面。資料多不會自動變可靠，只會讓真正要回答的欄位埋得更深，
也擴大隱私、相容性與不受信任內容的風險。

正式 payload 只留下公開任務真的用得到的欄位

最後我把 result 收斂成公開的 EventDetail 契約，再補上 Tool 執行狀態與下一步 guidance：

{
  "ok": true,
  "code": "SUCCESS",
  "data": {
    "event": {
      "id": "evt-webmcp-intro",
      "title": "WebMCP 入門工作坊",
      "summary": "從語意 HTML 到第一個網站 Tool。",
      "startsAt": "2027-01-23T10:00:00+08:00",
      "endsAt": "2027-01-23T12:00:00+08:00",
      "location": "taipei",
      "venue": "台北前端共學空間",
      "price": "free",
      "level": "beginner",
      "remainingCapacity": 8,
      "registrationDeadline": "2027-01-21T23:59:59+08:00",
      "state": "open"
    }
  },
  "guidance": {
    "availableActions": ["save_event"],
    "currentTarget": {
      "kind": "event",
      "id": "evt-webmcp-intro"
    },
    "requiresHumanConfirmation": false
  },
  "uiUpdated": true,
  "stateVersion": 2
}

這份 JSON 比「找到活動」長很多，卻不是為了看起來比較專業。每一組資料都有明確用途：

日期保留時區，避免 Agent 自己猜活動所在地；remainingCapacity、截止時間與 state 放在
一起，才足以判斷目前能不能報名。guidance 也沒有額外開一條捷徑，它只描述既有的
save_event 與目前活動 ID。

result 寫對了，Agent 的最後回答仍要另外驗

做到這裡，很容易看到 unit test 通過就宣布「Agent 已經會回答了」。這兩件事其實隔著一層。

我會把一次 Inspector 紀錄拆成兩段看：先確認 Tool result 是否符合契約，再核對 AI result
有沒有忠實使用這些欄位。假設 Tool 明明回了 venue 與 remainingCapacity，最後回答卻
漏掉名額，問題出在 grounding 或回答整理；如果 Tool result 根本沒有 venue，就不能怪
模型沒報地點，更不能期待它自己補一個。

昨天的 SEL-02 trace 正好可以重播這項核對。Agent 最後回答中的活動名稱、日期、場地與
剩餘 8 名，都能逐項回到 Tool result，沒有靠模型常識補值。

今天沒有把這份舊 trace 改寫成一題新的 Agent invocation。payload shape、欄位白名單與
direct tests 屬於 E1／E2 契約證據；Inspector trace 才是實際 Agent 如何使用 result 的
證據。兩邊合起來能回答完整問題，證據等級卻不能混著算。

uiUpdated: true 是契約回報，畫面仍要親自驗收

WebMCP Tool 就在使用者正在看的頁面執行。get_event_details 成功後，實作會先呼叫
show(event) 更新可見內容，再回傳 uiUpdated: true 與新的 stateVersion。direct test
也會檢查 show 是否真的收到同一份活動資料。

不過 uiUpdated: true 不是一張萬能證書。它是 result 對這次執行的狀態回報；DOM 是否
顯示正確、使用者是否看得到，仍要交給 browser test 或實際畫面驗收。把欄位寫進 JSON，
不代表瀏覽器就會因為感動而自動更新。

私人輸入與內部錯誤不進公開 result

欄位收斂時，我會先從使用者的 Prompt 反推需要回答什麼，再補上後續 Tool 需要的 ID 與
狀態座標，不會拿資料庫 entity 當菜單整份照抄。

因此，正式 result 不包含 session cookie、user ID、Email、stack trace、SQL、內部錯誤
物件或整頁 HTML。活動公開文案若會進入模型，也仍然要當成不受信任內容處理，不能因為
它來自自己的網站就直接升格成系統指令。

今天把成功 result 收到一個能回答、能接續，也能回頭核對的範圍。明天換失敗 result
上場：查無資料、輸入錯誤與服務暫時中斷，如果全部只回一個空陣列，Agent 根本不知道
該換搜尋條件、停下來，還是晚點再試。到時我會故意把服務弄壞一次，看契約能不能把它
安全地帶回來。