MCP 工具的結構化錯誤回應

MCP Tool 的 Structured Error Responses 這個主題，落在 CCA-F Domain 2（Tool Design 與 MCP Integration，佔比 18%）的任務說明 2.2 之中。它是整個 Claude Certified Architect Foundations 考試中槓桿最高的頁面之一，因為每個情境叢集——客服解決方案、多 agent 研究、程式碼生成、CI/CD、結構化資料擷取、開發者生產力——都至少包含一個可能失敗的工具，而考試反覆懲罰那些把這些失敗建模成純文字字串（而非結構化封包）的考生。MCP Tool 的 Structured Error Responses 是讓 agentic loop 能夠智慧復原的合約——而不是盲目重試、靜默放棄，或向使用者道歉後什麼也不做。

這份學習筆記涵蓋 CCA-F 考生需要內化的 MCP Tool Structured Error Responses 完整面向：告訴 Claude 工具呼叫未成功的 isError 旗標、分類「為什麼」失敗的 errorCategory 分類系統、通知復原決策的 isRetryable 布林值，以及給 agent 推理依據的人類可讀 content 內文。筆記同時劃出 access failure（工具無法回答問題）與 valid empty result（工具正確回答了、但答案是「沒有符合的資料」）之間的清晰界線——這個區分一旦被忽略，客服 agent 就會崩潰。最後的練習錨點章節，將所有詞彙連回多 agent 研究情境，在這個情境中，structured error 上下文必須從 subagent 乾淨地傳播到 coordinator。

為什麼 Structured Error Responses 很重要 — 讓 Agent 智慧復原而非靜默失敗

呼叫 MCP tool 的 Claude agent，有三種可能的觀察結果：工具成功並回傳有用內容、工具成功並回傳 valid empty result，或者工具失敗了。MCP Tool Structured Error Responses 的工作，就是讓第三種情況對 agent 而言清晰可讀，使迴圈的下一次迭代能夠採取合理的行動。

通用的錯誤處理有兩個缺點。第一，"Operation failed" 這樣的統一字串無法給 Claude 任何訊號來區分不同的復原路徑。第二，沒有 isError 布林值，模型可能會把純文字錯誤字串當成有效資料繼續執行，彷彿一切都成功了——這就是生產環境中的 agent 在退款工具實際拋出 permission exception 時，卻告訴使用者「您的退款已處理完成」的根本原因。

Structured error responses 通過給 Claude 三個正交維度來修正這兩個缺點：是否失敗（isError）、什麼類型的失敗（errorCategory），以及是否應該重試（isRetryable）。每一道 CCA-F 關於 MCP Tool Structured Error Responses 的情境題，在表面之下都是在問你：能否選出讓 coordinator agent 在不需要人工介入的情況下最大化復原能力的三個欄位組合。

MCP Tool Result 封包 — content、isError、errorCategory、isRetryable

每次 MCP tool 呼叫都會回傳一個 tool result 封包，由 Claude 在下一輪消化。在 Messages API 中，這個封包是附加在 user 角色訊息上的 tool_result 內容區塊；在 Claude Code 中，它以觀察結果的形式呈現，回饋進 agentic loop。四個欄位是 MCP Tool Structured Error Responses 的核心承重結構：

1. content — 人類可讀的有效載荷。成功情況下是工具產出的資料；錯誤情況下是描述出了什麼問題的文字。
2. isError — 布林值。true 表示工具呼叫未成功；false 或缺席表示成功。
3. errorCategory — 分類字串（TRANSIENT、VALIDATION、PERMISSION、BUSINESS、NOT_FOUND、UNKNOWN）。僅在 isError 為 true 時使用。
4. isRetryable — 布林值。true 表示立即重試有合理的成功機會；false 表示在不介入的情況下重試會產生相同的失敗。

即使 isError: true，content 內文也不是選填的。Claude 需要文字來推理。一個失敗卻不回傳任何失敗描述的工具，會迫使 agent 猜測——這正是考試干擾答案看起來像「agent 道歉後結束對話，沒有採取任何行動」的原因。

isError 欄位 — 工具執行未成功的布林訊號

isError 是封包中最重要的單一位元。它是「這是資料」與「這是失敗描述」之間的分水嶺。一個設計良好的 MCP tool，在呼叫無法產出呼叫端所要求的語義答案時設 isError: true，而在工具成功時設為 false（或省略）——即使答案是空的。

isError: true 與「僅僅是不成功的結果」之間的區別是微妙的，也是高頻考點。若一個客服 agent 向 lookup_order 工具查詢訂單 #12345，但訂單不存在，正確的回應取決於合約內容：

• 若工具的合約是「回傳訂單，或告知沒有符合的結果」，正確的封包是 isError: false，加上 content: "找不到 ID 為 12345 的訂單。" 這是 valid empty result。
• 若工具的合約是「回傳訂單」，而查詢無法完成是因為資料庫無法連線，正確的封包是 isError: true，加上 errorCategory: "TRANSIENT" 和 isRetryable: true。這是 access failure。

從單純的 HTTP 角度看，兩者很像——都可能是 404 或 5xx——但對 agent 的下一步行動有完全相反的含義。搞混這個區分，agent 就會對已被正確回答的查詢反覆重試（浪費 token 和延遲），或把資料庫靜默失敗接受為「沒有資料」（在對話中產生假陰性）。

errorCategory 值 — TRANSIENT、VALIDATION、PERMISSION、BUSINESS、NOT_FOUND、UNKNOWN

errorCategory 是告訴 Claude「為什麼」呼叫失敗的分類系統。CCA-F 關於 MCP Tool Structured Error Responses 的題目，非常依賴你能否為特定情境選出正確的類別。

TRANSIENT

可能在重試後消除的暫時性狀況：網路超時、上游速率限制、服務不可用、暫時性資料庫競爭。通常搭配 isRetryable: true，並預期 agent 會進行退避（backoff）。

VALIDATION

呼叫端提供的輸入違反了工具的 schema 或領域限制：格式錯誤的日期、無效的幣別代碼、超過最大長度的欄位、缺乏語義合理性的必填參數。搭配 isRetryable: false，並給 agent 足夠的資訊來修正呼叫（指出有問題的參數及原因）。以相同輸入重試將產生完全相同的失敗。

PERMISSION

呼叫端已通過身份驗證，但未被授權執行此操作：agent 嘗試存取屬於不同客戶的記錄、被策略封鎖的工具呼叫、缺少必要 scope 的 API 金鑰。搭配 isRetryable: false。Agent 應該升級給人類、切換到有更廣泛 scope 的工具，或向使用者解釋限制。

BUSINESS

即使輸入在技術上有效且呼叫端已被授權，領域層級的規則仍然拒絕了該操作：違反退款期限政策的退款請求、超過每日限額的轉帳、因履行已開始而無法取消的訂單。搭配 isRetryable: false 和人類可讀的政策描述。這是最常被錯標為 VALIDATION 的類別；差異很重要，因為 agent 的復原路徑根本不同——business error 需要解釋政策，而不是修正輸入。

NOT_FOUND

請求了一個特定資源但它不存在。許多工具設計偏好將 NOT_FOUND 呈現為普通的空結果（isError: false），但當呼叫端需要明確的訊號時——例如，需要先前記錄才能執行的寫入操作——明確的 NOT_FOUND 錯誤比靜默的空成功更清晰。搭配 isRetryable: false，除非缺少的資源可能在重試後出現。

UNKNOWN

保留給工具無法分類的失敗。視為 transient 加上需要運營商關注：預設設 isRetryable: false，並在 content 中包含所有現有的診斷細節。只要工具能區分，就優先使用精確的類別；過度使用 UNKNOWN 是設計壞味道。

isRetryable 欄位 — 通知 Agent 立即重試是否值得

isRetryable 是將「agent 是否應該再試一次？」這個政策決策，壓縮成單一布林值的二階訊號。這個欄位不是對重試邏輯的描述（退避、抖動、最大嘗試次數）；它是對底層失敗性質的陳述——該失敗是否可能在相同呼叫下成功。

何時 isRetryable: true 是正確的

• 網路超時、連線重置、DNS 失敗。
• HTTP 429（速率限制）——速率限制視窗會滾動更新。
• HTTP 503（服務不可用）——上游可能恢復。
• 暫時性資料庫死鎖。

何時 isRetryable: false 是正確的

• 任何 VALIDATION 錯誤——輸入完全相同，會被完全相同地拒絕。
• 任何 PERMISSION 錯誤——呼叫端的 scope 沒有改變。
• 任何 BUSINESS 錯誤——政策引擎將做出相同的判斷。
• 大多數 NOT_FOUND 錯誤（除非資源預期會出現）。

為什麼 isRetryable 與 errorCategory 是分開的

從類別到可重試性沒有確定性的對應關係。一個已耗盡上游重試預算的 TRANSIENT 失敗，應該以 isRetryable: false 呈現，讓 agent 不會持續重擊。一個正在被非同步建立的記錄的 NOT_FOUND 錯誤，可能合理地是可重試的。保持兩個欄位獨立，並都明確設定。

Error Message Content — content 欄位中的人類可讀描述

structured error 封包的 content 內文是 Claude 實際閱讀的文字。它應該給 agent 足夠的細節，以便：

• 用非技術性語言向終端使用者解釋失敗。
• 決定是否需要切換到不同的工具、調整參數，或升級處理。
• 產生人類審查者在事後除錯時可以追蹤的記錄。

好的錯誤 content 字串會指名失敗的操作、在適用時識別有問題的輸入、說明狀況是否為暫時性，並對 business 規則以客戶友善的語言摘要政策。糟糕的錯誤 content 字串是「Error.」或原始的 Python stack trace。

對於面向客戶的 agent 中的 BUSINESS 錯誤，文字應明確為終端使用者所寫。「退款僅限購買後 30 天內申請；此訂單是 47 天前下的」比「policy_engine_violation: rule_id=REFUND_WINDOW_EXCEEDED」有用了無數倍。

復原策略矩陣 — isError + isRetryable + errorCategory → Agent 決策

完整的決策空間是三個欄位構成的立方體，但在實務上，考試情境中只會出現少數幾種組合。請把這個對應關係背下來。

這個矩陣中的每一列都是合理的 CCA-F 干擾選項；考試的工作是看你能否根據情境的超時、使用者輸入或政策規則線索，選出正確的組合。

Transient 錯誤處理 — isRetryable: true 觸發指數退避

Transient 失敗是標準的重試情況。當 agent 看到 isError: true、errorCategory: "TRANSIENT"、isRetryable: true 時，正確的迴圈行為是：

1. 遞增這次工具呼叫的重試計數器。
2. 以指數排程加抖動計算出的間隔進行退避（例如，base × 2^attempt × random(0.5, 1.5)）。
3. 以完全相同的輸入重新呼叫工具。
4. 若重試預算耗盡，呈現原始錯誤或切換到備用方案。

retry 政策存在於 agent 迴圈中，而不在工具內部。工具唯一的工作是為失敗貼上標籤，讓 agent 做出決策。一個在內部靜默重試的工具，對 agent 而言看起來與成功的呼叫相同，並破壞了迴圈的可觀測性。

Validation 錯誤 — 回傳 VALIDATION 並附上參數修正提示

Validation 錯誤發生在呼叫端違反工具的 schema 或領域限制時。好的 validation 錯誤要做兩件事：

• 指名有問題的參數（例如，"end_date 必須在 start_date 之後或相同日期；收到 end_date=2026-01-15，start_date=2026-02-01"）。
• 明確說明限制，讓 agent 能夠生成一個符合規範的重試。

不要只回傳「輸入無效。」Agent 的迴圈迭代次數是有限的，每一次沒有可行動指引的迭代都是浪費。

Validation 錯誤在工具層級永遠是 isRetryable: false，因為完全相同的重試將產生完全相同的失敗。Agent 預期會在重試之前修改輸入，這是一個不同的操作——不是對相同呼叫的重試。

Permission 錯誤 — PERMISSION_DENIED 訊號升級或替代路徑

Permission 錯誤表示呼叫端已知但未被授權。常見形狀：

• 客服 agent 嘗試存取屬於不同客戶的記錄。
• 開發者生產力 agent 嘗試寫入使用者沒有 commit 權限的 repository。
• 多 agent 研究 subagent 嘗試呼叫其工具許可清單以外的 API。

structured response 應在 content 中識別缺少的許可，讓 coordinator agent 能夠選擇補救措施：重新要求使用者驗證身份、升級給人類，或切換到有適當 scope 的不同工具。isRetryable: false 旗標至關重要——以相同憑證重試將產生完全相同的失敗，浪費迴圈迭代。

Business 錯誤 — isRetryable: false 搭配對政策違規的客戶友善解釋

Business 錯誤是大多數生產 agent 崩潰的地方。一個回傳 "error: REFUND_WINDOW_EXCEEDED" 但沒有進一步說明的退款工具，讓 agent 只剩兩個糟糕的選擇：重試（錯——政策會做出完全相同的拒絕）或泛泛道歉（錯——使用者值得得到具體的解釋）。

正確的 structured response 是：

{
  "isError": true,
  "errorCategory": "BUSINESS",
  "isRetryable": false,
  "content": "退款僅限購買後 30 天內申請。此訂單（#12345）是 47 天前下的，已超出退款期限。若您認為此案屬例外情況，請升級至主管處理。"
}

Agent 可以直接向客戶引用 content 字串，讀起來像一個禮貌且具體的解釋。isRetryable: false 旗標防止 agent 在無法成功的重試上浪費迭代。errorCategory: "BUSINESS" 讓 coordinator 能將情況路由到升級佇列，而非技術除錯佇列。

這是 CCA-F 考試上單一最高價值的模式，因為它明確出現在客服解決方案情境叢集中，並隱性地出現在所有其他涉及政策的情境。社群的通過報告點名了這個模式：「對 business 規則違規使用帶有 errorCategory/isRetryable 和客戶友善描述的 structured error responses。」

Access Failure vs Valid Empty Result — 最常被考的區分

失敗的工具呼叫與回傳空值的成功工具呼叫，在傳輸層看起來很相似，但需要截然相反的 agent 行為。MCP Tool Structured Error Responses 封包正是劃定這條界線的工具。

Access Failure

工具無法完成其工作：資料庫無法連線、上游 API 超時、驗證失敗、schema 拒絕輸入。Agent 需要做出重試 / 中止 / 升級的決策。

封包形狀：

{
  "isError": true,
  "errorCategory": "TRANSIENT",
  "isRetryable": true,
  "content": "無法連線到訂單資料庫（5 秒後超時）。"
}

Valid Empty Result

工具完成了其工作，答案合理地為「沒有資料」。客戶沒有未完成的訂單。搜尋回傳零筆結果。此帳戶沒有未結工單。

封包形狀：

{
  "isError": false,
  "content": "找不到客戶 #8421 的任何訂單。"
}

這兩種形狀有截然相反的含義。第一種說「我無法回答這個問題，請採取行動。」第二種說「我回答了這個問題，答案是空的，請帶著這個認知繼續。」

包裝外部 API 錯誤 — 將 HTTP 狀態碼轉換為 MCP 錯誤欄位

大多數 MCP tool 是對第三方 API 的薄包裝層。工具的工作是將上游錯誤層翻譯成 Claude 理解的 structured 封包。HTTP 語義到 MCP 欄位的粗略對應：

這個對應是指引，不是規則。了解上游語義的工具作者應該願意重新分類：代表 business 規則衝突的 409 屬於 BUSINESS；代表版本衝突、透過重試加上重新讀取可解決的 409 屬於 TRANSIENT。

白話文解釋 Structured Error Responses for MCP Tools

抽象的分類系統，一旦錨定在熟悉的情境上就會變得直觀。以下三個類比涵蓋了 MCP Tool Structured Error Responses 的完整面貌。

類比一：急診室的分診台

走進醫院急診室。分診護理師不只說「有問題」。她在一張卡片上寫下三項資訊：是否真的有問題（isError）、是什麼類型的問題（errorCategory——心臟科、骨科、神經科、行政問題），以及病患能否改天再來、還是需要立即處理（isRetryable）。上游的醫生看到這張卡片後，選出具體的處置方案：住院、立即治療、明天排號、轉介其他專科。

若分診護理師只寫「病患有問題」，醫生就必須對每位病患重新診斷。這正是通用錯誤字串對 Claude agent 造成的傷害。MCP Tool Structured Error Responses 就是那張分診卡，讓 agent 以正確的緊迫度和方向採取行動。

類比對應如下：

• isError = 「真的有問題嗎？」
• errorCategory = 「什麼類型的問題？」（TRANSIENT = 輕微且可能自行消失，VALIDATION = 病患提供了錯誤資訊，PERMISSION = 此項治療沒有健保給付，BUSINESS = 政策不給付，NOT_FOUND = 查無病歷，UNKNOWN = 需要進一步檢查）。
• isRetryable = 「病患帶著同樣的資訊改天再來，能被診治嗎？」
• content = 隨卡片傳遞的人類可讀筆記，讓下一位臨床人員理解上下文。

類比二：台灣的快遞系統

一個交給快遞員的包裹，有四種可能的命運。它送達了（isError: false，而內容物就是交付的資料）。它因為道路被颱風封閉而無法投遞（TRANSIENT，isRetryable: true——改天再試）。它因為地址格式錯誤而無法投遞（VALIDATION，isRetryable: false——寄件人必須修正地址）。它因為收件人拒收而無法投遞（PERMISSION，isRetryable: false）。它因為海關禁止進口該品項而無法投遞（BUSINESS，isRetryable: false——向寄件人解釋規定）。

第五種情況微妙但至關重要：快遞員成功投遞了，但收件人沒有需要接收的東西——投遞格是空的，簽收被免除了，是免簽收的配置。這是 valid empty result（isError: false，content: "已投遞，免簽收"），根本不是失敗。把「免簽收」當成投遞失敗，會讓快遞員重試一個已經完成的投遞——這正是 agent 混淆 access failure 與 valid empty result 時的崩潰方式。

類比三：餐廳的出餐記錄板

忙碌的餐廳廚房靠出餐記錄板運作。每張單子，要麼被完成（isError: false），要麼被退回給領班並附上原因。原因至關重要：食材缺貨是 TRANSIENT（廚師明天會補貨，稍後再試）；點錯餐點是 VALIDATION（服務生寫的是雞肉，但客人說的是魚，改正單子）；客人點了之後反悔是 PERMISSION / BUSINESS（視餐廳規定而定，無法重試）；單子上的菜已下架是 NOT_FOUND。

領班——也就是 coordinator——根據退回單子上的類別，決定是把它推回廚房再試、帶著致歉說明給客人，還是路由給主管。只寫「有問題」的單子，迫使領班親自調查每一張退單，嚴重影響出餐效率。Structured error responses 就是維持廚房運轉的餐廳慣例。

考試當天選用哪個類比

• 關於路由決策（哪個類別觸發哪個 agent 分支）的題目 → 急診分診台。
• 關於可重試性和 access failure vs empty result 區分的題目 → 快遞系統。
• 關於多 agent 傳播、subagent 向 coordinator 回報的題目 → 出餐記錄板。

常見考試陷阱 — 通用錯誤、可重試性混淆、空結果混淆

CCA-F 考試反覆利用 MCP Tool Structured Error Responses 周圍的少數陷阱模式。認出它們，你就能拿下三到五道讓多數考生失分的題目。

陷阱一：統一的「Operation Failed」文字

干擾答案提議回傳單一錯誤字串，如「Operation failed」或「An error occurred」。這些答案看起來保守安全，但是錯的——它們剝奪了 agent 復原所需的三個訊號（isError、errorCategory、isRetryable）。正確答案永遠包含結構。

陷阱二：isRetryable: false 表示終止迴圈

考生讀到 isRetryable: false，就認為整個 agent 迴圈必須中止。這不是這個欄位的含義。isRetryable: false 的意思是以這個特定輸入的這個特定呼叫，不會在單純的重試下成功。Agent 仍然可以修改輸入（對 VALIDATION）、升級（對 PERMISSION）、向使用者解釋政策（對 BUSINESS），或切換工具。迴圈繼續；被阻止的是重試本身。

陷阱三：VALIDATION 與 BUSINESS 混淆

因為退款期限已過而被拒絕的退款，很容易被標記為 VALIDATION，因為這個請求是「錯的」。但不是。輸入在語法上是有效的，呼叫端已被授權；是領域政策拒絕了它。這是 BUSINESS。BUSINESS 的復原路徑是「解釋政策」。VALIDATION 的復原路徑是「修正輸入後重試」。混淆它們，agent 要麼無限迴圈嘗試修正一個有效的輸入，要麼在沒有引用實際規則的情況下泛泛道歉。

陷阱四：把 Valid Empty Result 當成錯誤

一個回傳零筆結果的搜尋，是一次成功的呼叫。isError: false，content: "No matches found."。CCA-F 情境有時會在干擾選項中呈現 isError: true 加上 errorCategory: "NOT_FOUND"。測試點在於你是否知道工具回答了這個問題。當合約是「回傳零筆或多筆結果」時，零筆是合理的答案。

陷阱五：工具端重試向 Agent 隱藏失敗

干擾選項提議「工具在回傳錯誤前內部重試最多 5 次」。這向 agent 迴圈隱藏了重試預算，並破壞了可觀測性。Retry 邏輯屬於 agent，由工具的 isRetryable 訊號提供資訊。一個在內部重試的工具，只應在單一邏輯呼叫的底層進行優化性重試，絕不能作為回傳 structured failure response 的替代方案。

練習錨點 — 多 Agent 研究情境：Structured Error 上下文讓 Coordinator 復原

多 agent 研究情境是 MCP Tool Structured Error Responses 最豐富的測試場，因為錯誤必須從 subagent 乾淨地傳播到 coordinator，甚至可能進入面向使用者的摘要。

標準設定

一個 coordinator agent 將研究任務分配給三個 subagent。每個 subagent 有自己的 MCP tool 集合：web_search、fetch_url、extract_citations、summarize_source。Subagent A 的 fetch_url 呼叫碰到付費牆，回傳 isError: true、errorCategory: "PERMISSION"、isRetryable: false、content: "來源回傳 403——付費牆需要機構授權。" Subagent B 的 web_search 碰到 429，回傳 isError: true、errorCategory: "TRANSIENT"、isRetryable: true、content: "搜尋速率限制已達到，請在 60 秒後重試。" Subagent C 的 extract_citations 回傳 isError: false、content: "[]"——一個 valid empty result，因為該來源沒有正式引用。

Coordinator 必須做的事

• 對於 Subagent A：跳過付費牆來源，在最終報告中記錄此限制，不要重試。
• 對於 Subagent B：套用退避後重試搜尋；若重試預算耗盡，記錄資料覆蓋不完整。
• 對於 Subagent C：接受空的引用清單為合理結果並繼續。不要重新詢問 subagent。不要把空清單視為失敗。

每道與 MCP Tool Structured Error Responses 相關的 CCA-F 情境題，最終都是在問考生，當封包只相差一兩個欄位時，能否保持這三種反應的清晰區分。

練習題模板 A — 類別選擇

一個客服 agent 呼叫 process_refund 工具。退款針對一個 45 天前下的訂單；公司政策限制退款在 30 天內。哪個錯誤封包是正確的？

• (A) isError: true, errorCategory: VALIDATION, isRetryable: true
• (B) isError: true, errorCategory: BUSINESS, isRetryable: false, content: "退款僅限購買後 30 天內申請。"
• (C) isError: true, errorCategory: UNKNOWN, isRetryable: false
• (D) isError: false, content: "退款不適用。"

正確答案：(B)。輸入有效且呼叫端已被授權；是領域政策拒絕了它。BUSINESS 加上 isRetryable: false 和客戶友善的描述是正確的形狀。

練習題模板 B — Access Failure vs Empty Result

一個研究 subagent 呼叫 list_open_tickets，查詢客戶 #4421。客戶已知且已授權，但客戶沒有未結工單。哪個封包是正確的？

• (A) isError: true, errorCategory: NOT_FOUND, isRetryable: false
• (B) isError: true, errorCategory: TRANSIENT, isRetryable: true
• (C) isError: false, content: "找不到客戶 #4421 的未結工單。"
• (D) isError: true, errorCategory: UNKNOWN, isRetryable: false

正確答案：(C)。工具履行了其合約；答案合理地是空的。這是 valid empty result，不是 access failure。

練習題模板 C — Coordinator 傳播

Subagent A 在第一次嘗試 fetch_url 後回傳 isError: true, errorCategory: TRANSIENT, isRetryable: true。Coordinator 的每個 subagent 呼叫重試預算為 3 次。Coordinator 應該怎麼做？

• (A) 中止整個研究工作流程。
• (B) 以退避方式重新呼叫 fetch_url，在耗盡剩餘重試預算之前，再呈報失敗。
• (C) 立即重試，不進行退避。
• (D) 放棄這個 subagent，靜默地跳過此來源。

正確答案：(B)。TRANSIENT 加上 isRetryable: true 表示應進行有上限的退避重試；重試預算存在於 coordinator 中，而非工具內。

MCP Tool Structured Error Responses 常見問題 FAQ

MCP tool response 中的 isError 和 isRetryable 有什麼差異？

isError 是一個布林值，告訴 Claude 工具呼叫是否完全成功。當 isError: true 時，content 內文被視為錯誤描述而非資料。isRetryable 是一個獨立的布林值，告訴 Claude 對失敗呼叫進行相同重試是否有合理的成功機會。兩者是獨立的：isError: true 必須搭配明確的 isRetryable 值，因為類別本身無法決定可重試性（TRANSIENT 失敗在預算耗盡後可能不可重試；NOT_FOUND 在資源被非同步建立時可能可重試）。在 CCA-F 上，將兩者視為與 errorCategory 共同構成 agent 選擇復原路徑的三軸決策空間的正交欄位。

如何決定 errorCategory: VALIDATION 與 errorCategory: BUSINESS 之間的選擇？

問輸入是否在語法上有效且呼叫端是否已被授權。如果答案是「否，輸入違反了 schema 或領域限制」（錯誤的型別、缺少必填欄位、超出範圍的值），類別是 VALIDATION，agent 應在重試前修正輸入。如果輸入有效且呼叫端已被授權，但領域政策拒絕了操作（超出期限的退款、超過每日限額的轉帳、履行後的取消），類別是 BUSINESS，agent 應向使用者解釋政策而非嘗試重試。這個區分很重要，因為復原路徑不同：VALIDATION 觸發輸入修正；BUSINESS 觸發政策解釋。混淆它們，會產生要麼無限迴圈嘗試修正有效請求、要麼在沒有引用實際規則的情況下泛泛道歉的 agent。

工具應該在回傳錯誤前內部重試嗎？

不應——retry 政策屬於 agent 迴圈，而不在工具內部。在工具內部重試，會向 Claude 隱藏重試預算，並破壞迴圈可觀測性：agent 無法對 token、延遲或使用者可見的進度訊息進行預算管理，也無法在整體時間預算緊張時切換到備用方案。正確的模式是通過帶有適當 isRetryable 訊號的 structured 封包呈現失敗，讓 coordinator 決定是否套用退避後重試。內部重試可作為效能優化，在單一邏輯呼叫的底層執行（例如，在較大的語義操作中對單一底層 HTTP 請求重試一次），但絕不能作為在整體操作無法成功時回傳 structured failure response 的替代方案。

如何區分 access failure 與 valid empty result？

問工具是否履行了其合約。若合約是「回傳符合的記錄，或告知沒有符合的結果」，而結果是「沒有符合的」，工具成功了，正確的封包是 isError: false 加上描述性 content（valid empty result）。若合約是「回傳記錄」，而工具因超時、permission 問題或上游停機而無法完成，工具失敗了，正確的封包是 isError: true 加上 errorCategory 和 isRetryable 訊號（access failure）。兩種形狀在傳輸層看起來相似，但隱含截然相反的 agent 行為：空結果作為資料被消化，迴圈繼續；access failure 觸發復原決策樹。混淆兩者是 CCA-F 考試中最常被測試的架構錯誤之一。

當 isError: true 時，content 欄位應該放什麼？

滿足兩個受眾的人類可讀文字：agent（讓它路由回應並選擇復原行動）和終端使用者（因為 agent 通常會在面向客戶的回覆中直接引用這段文字）。對於 TRANSIENT 錯誤，指名底層狀況及任何已知的重試提示。對於 VALIDATION，指名有問題的參數及其違反的限制。對於 PERMISSION，說明呼叫端沒有被授權做什麼。對於 BUSINESS，用足夠具體的平易近人語言摘要政策，使直接引用能產生一個禮貌的回覆。避免原始 stack trace、無說明的內部規則 ID，以及「Operation failed」這樣的通用短語——三者都剝奪了訊號，迫使 agent 要麼猜測，要麼泛泛道歉。

Structured error 傳播在多 agent 系統中如何運作？

在 coordinator-subagent 架構中，每個 subagent 的 MCP tool 呼叫，將 structured error 封包回傳給 subagent 本身。Subagent 負責自己的第一線復原——對 TRANSIENT 重試套用退避、對 VALIDATION 修正輸入，諸如此類。Subagent 無法解決的錯誤，作為 subagent 自身向 coordinator 呈報的結果的一部分向上傳播，理想情況下保留 errorCategory 和 isRetryable 訊號，讓 coordinator 能做出明智的決策（路由到不同的 subagent、呈現給使用者、中止工作流程）。多 agent 研究情境明確測試這種傳播：碰到付費牆的 subagent，必須清晰地呈現 PERMISSION，讓 coordinator 能夠跳過該來源並在最終報告中記錄缺口，而不是崩潰或靜默省略。

isRetryable: false 表示 agent 應該終止迴圈嗎？

不表示。isRetryable: false 的意思是以這個特定輸入、這個特定呼叫端的這個特定呼叫，不能在單純的重試下成功。這不表示 agent 已沒有選項。對於 VALIDATION 錯誤，agent 應修正輸入後重試（一個不同的呼叫）。對於 PERMISSION 錯誤，agent 應升級、重新驗證，或切換到 scope 更廣泛的工具。對於 BUSINESS 錯誤，agent 應向使用者解釋政策，並可能提供替代方案。在這三種情況下，迴圈都繼續；被阻止的是對相同失敗呼叫的盲目重試。CCA-F 干擾選項常常建議「對 isRetryable: false 中止工作流程」——這個答案幾乎永遠是錯的。

延伸閱讀

• Anthropic Docs — Handle tool calls (tool_result format and error responses): https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/handle-tool-calls
• Anthropic Docs — Tool use overview and the agentic loop: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
• Model Context Protocol — Introduction: https://modelcontextprotocol.io/introduction
• Model Context Protocol — Build an MCP server: https://modelcontextprotocol.io/docs/develop/build-server
• Anthropic Engineering — Writing tools for agents: https://www.anthropic.com/engineering/writing-tools-for-agents
• Anthropic Docs — Subagents in the Agent SDK (error propagation patterns): https://docs.anthropic.com/en/docs/claude-code/sdk/subagents
• Anthropic Docs — Connect Claude Code to tools via MCP: https://docs.anthropic.com/en/docs/claude-code/mcp

Related ExamHub topics: 工具介面設計：清晰描述與邊界劃定, 將 MCP Server 整合至 Claude Code 與 Agent 工作流程, 跨 Agent 的工具分配與 Tool Choice 設定, 多 Agent 系統的錯誤傳播策略.