isErrorフラグ
MCPレスポンスで失敗を明確に通知する方法を学びます
「isErrorフラグ」はCoddyKit上の無料Claude Architectレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはClaude Architect学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Claude Architectコースには全4レッスンが含まれています。
このレッスンの一部はまだ翻訳されておらず、英語で表示されています。
Why Signalling Failure Matters
When an MCP tool runs, two things can happen: it succeeds, or it fails. The model needs to know which — clearly and unambiguously — to decide what to do next.
If a failure looks like a normal result, the agent may treat garbage as truth, hallucinate a recovery, or silently move on. The fix is a dedicated failure signal: the isError flag.
In this lesson you'll learn how to signal failure cleanly so the agentic loop can route intelligently instead of guessing.
What isError Actually Does
A tool result carries an isError boolean. When isError is true, you're telling Claude: this tool did not produce a valid result — treat the content as a failure report, not data.
This is structurally separate from your tool's normal output. The model can branch on it without parsing prose: success path vs. failure path. That separation is the whole point.
tool_result = {
"type": "tool_result",
"tool_use_id": tool_use.id,
"is_error": True,
"content": "..." # structured failure report
}Generic Errors Block Recovery
The classic anti-pattern is a generic error string like "Operation failed". It tells the model that something went wrong but nothing it can act on.
Can it retry? Was the input malformed? Did the user lack permission? Is there partial data to salvage? A generic message answers none of these — so the agent stalls or improvises badly.
Generic errors block recovery. Structured errors enable intelligent routing.
The Anatomy of a Structured Error
A well-formed MCP error pairs isError: true with a structured body. The exam-standard fields are:
errorCategory— one of transient, validation, business, permissionisRetryable— can the same call succeed if tried again?message— human-readable explanationattempted_query— exactly what the tool tried to dopartial_results— anything usable it managed to gather
Together these let the model decide: retry, reformulate, escalate, or proceed with partial data.
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "Upstream inventory service timed out after 5s",
"attempted_query": "GET /inventory?sku=ABX-19",
"partial_results": null
}errorCategory Drives the Decision
The four categories aren't decoration — each implies a different next action:
- transient — temporary fault (timeout, rate limit). Usually retryable; recover locally.
- validation — bad input. Don't blind-retry; fix the arguments first.
- business — a rule was violated (e.g. refund exceeds policy). Often needs escalation, not retry.
- permission — caller lacks access. Retrying won't help; escalate or request credentials.
The category turns a vague failure into a routing instruction the model can follow.
isRetryable: Don't Make the Model Guess
Whether a failure is worth retrying is often invisible from the message text alone. Make it explicit with isRetryable.
A timeout (transient) is retryable. A malformed argument (validation) is not — retrying the same bad input just fails again. A permission denial is not retryable without new credentials.
By stating isRetryable directly, you keep retry decisions deterministic instead of leaving them to probabilistic text-reading.
{
"isError": true,
"errorCategory": "validation",
"isRetryable": false,
"message": "sku must match pattern ^[A-Z]{3}-[0-9]{2}$; got 'abx19'",
"attempted_query": "lookup_inventory(sku='abx19')"
}attempted_query Preserves Context
When the model decides how to recover, it needs to know what was actually tried. Including attempted_query means the agent can reformulate intelligently instead of repeating the same failing call.
This is part of good error propagation: structured context = failure type, attempted query, partial results, and alternatives. The richer the context, the better the recovery routing.
partial_results: Don't Throw Away Good Data
A tool can fail and still have gathered something useful. A multi-source lookup might return 3 of 5 records before the 4th source times out.
Returning partial_results alongside the error lets the agent proceed with what it has, annotate the gap, and avoid restarting from zero. Discarding partial data on any failure wastes work and degrades answers.
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "3 of 5 sources responded; 2 timed out",
"attempted_query": "search_catalog(term='thermostat')",
"partial_results": [{"id": 11}, {"id": 12}, {"id": 19}]
}Failure vs. a Valid Empty Result
A critical distinction: an access failure is not the same as a valid empty result.
isError: true— the tool couldn't complete (timeout, denied, bad input). Maybe retry or escalate.isError: falsewith empty content — the tool ran fine and the honest answer is "no matches."
Conflating these is a common bug: an empty search marked as an error triggers pointless retries, while a real failure marked as empty hides the problem. Keep them distinct.
{
"isError": false,
"errorCategory": null,
"message": "Query succeeded; 0 orders match customer C-7781",
"results": []
}Recover Locally, Escalate When You Must
The structured signal drives where recovery happens. In a multi-agent system, a subagent should recover transient faults locally — retry the timeout, re-issue the call — and only bubble up failures it truly can't resolve.
When it does escalate, it passes the structured error with partial results so the coordinator can decide: route elsewhere, ask for more identifiers, or surface the gap. Never silently suppress a failure, and never abort the whole workflow over one recoverable fault.
Putting It Together in a Tool
Inside an MCP tool handler, wrap the work and return a structured error on failure instead of letting an exception leak as a generic string.
Notice how each branch sets isError, a category, and a retry hint — giving the agentic loop everything it needs to route the next step deterministically.
def lookup_order(order_id: str):
try:
order = db.fetch(order_id)
if order is None:
return {"isError": False, "results": []} # valid empty
return {"isError": False, "results": [order]}
except TimeoutError as e:
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"message": str(e),
"attempted_query": f"fetch(order_id={order_id})",
"partial_results": None,
}Quick Check: Choosing the Right Error Shape
A subagent's MCP tool queries a customer's order history. One of three backend shards is unreachable; the other two return 8 orders. What should the tool return?
Recap: Signalling Failure Cleanly
Key takeaways for the isError flag:
- isError: true is the structural signal that a tool did not produce valid data — separate from normal output.
- Pair it with errorCategory (transient / validation / business / permission), isRetryable, message, attempted_query, and partial_results.
- Generic errors like "Operation failed" block recovery; structured errors enable intelligent routing.
- Distinguish an access failure from a valid empty result — never mark "no matches" as an error.
- Recover transient faults locally; escalate non-recoverable ones with partial results. Avoid silent suppression and avoid aborting the whole workflow on one fault.
よくある質問
「isErrorフラグ」レッスンは無料ですか？
はい。「isErrorフラグ」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Claude Architectコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Claude Architectコースには全4レッスンが含まれています。
「isErrorフラグ」で何を学びますか？
MCPレスポンスで失敗を明確に通知する方法を学びます ブラウザで直接実行するハンズオンコードでClaude Architectを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Claude Architectを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのClaude Architectは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「isErrorフラグ」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このClaude Architectレッスンでコードを書いて実行できますか？
はい。すべてのClaude Architectレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。