The isError Flag
Signalling failure cleanly in MCP responses.
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
}