Antipadrão: Mensagens de Erro Genéricas

A tool in your agentic loop returns:

{ "status": "error", "message": "Operation failed" }

The model now has to decide: retry, try a different query, escalate to a human, or stop. But "Operation failed" carries zero signal. It cannot tell whether the database was briefly down, the input was malformed, or a business rule blocked the action.

This is the generic error anti-pattern — and it quietly breaks agent reliability.

In the agentic loop, the model inspects each tool result and chooses the next action. A recovery decision depends on what kind of failure occurred:

• Transient outage → retry locally
• Bad input → fix the query and re-call
• Business rule violation → do NOT retry; escalate or stop
• Permission denied → escalate

A generic message collapses all four into one indistinguishable blob. The model is left to guess — often retrying something that will never succeed, or aborting the whole workflow on a fault it could have recovered from.

The fix is a structured error contract. For MCP tool results, an error should carry:

• isError: true — an explicit error flag
• errorCategory — one of transient, validation, business, permission
• isRetryable — whether retrying could plausibly help
• message — human-readable detail
• attempted_query — what the tool actually tried
• partial_results — anything usable already gathered

Each field maps directly to a recovery decision the model can now make deterministically.

The single most important field is errorCategory. It tells the model which branch of the recovery tree to take:

• transient → retry locally in the subagent (network blip, timeout)
• validation → the input was wrong; correct the arguments and re-call
• business → a rule blocked it (e.g. refund over limit); retrying is pointless — escalate
• permission → caller lacks access; escalate, never loop

"Operation failed" forces the model to infer the category from prose, if it can at all. A typed category removes the guessing.

A generic error invites a dangerous behavior: blind retrying. The model re-calls the failing tool, gets "Operation failed" again, and may burn iterations on something that can never succeed.

An explicit isRetryable flag turns a guess into a rule. The model retries only transient faults, and immediately routes business and permission failures elsewhere.

Remember: iteration caps are a safety net, never the primary stop mechanism. Clean error signals are what actually keep the loop honest.

A subtle trap: a generic error blurs the line between "I could not look" and "I looked and found nothing".

• Access failure (timeout, auth error) → the data may exist; retry or escalate.
• Valid empty result (zero matching rows) → the answer is genuinely "none"; do NOT retry.

If both surface as "Operation failed," the model might retry forever on an empty set, or give up on a recoverable outage. A structured contract keeps these two outcomes distinct.

Failures are rarely all-or-nothing. A multi-agent research coordinator might fan out to five sources; one times out. Returning a bare "Operation failed" throws away the four that succeeded.

Include partial_results so the model can synthesize what it has and annotate the gap rather than abort. The architect's rule: recover transient faults locally, and when you must escalate, escalate with partial results attached — never silently suppress and never kill the whole workflow over one failed branch.

When the failure is a validation error, the model needs to know what it sent to fix it. The attempted_query field echoes the exact input back.

This mirrors retry-with-feedback for structured output: you fix format and structural errors by sending the model the original request plus the exact error plus what was attempted. With attempted_query in hand, the model can spot a malformed SKU or a bad date filter and correct the next call — instead of repeating the same broken request.

Structured errors make the model's recovery smarter, but they are still consumed by a probabilistic model. For failures with financial, legal, or safety consequences, pair them with deterministic enforcement.

A PostToolUse hook can inspect a tool result before the model ever sees it, and an outgoing-call hook can block a policy-violating action (e.g. a refund over $500) with 100% determinism. Prompts and structured signals guide ~90% of the time; hooks guarantee the rest. Structured errors enable intelligent routing — they do not replace hard guardrails.

You usually do not have to invent this contract from scratch. For standard integrations, prefer well-maintained community MCP servers over custom ones — they often already return categorized, retryable errors.

When you do build a custom tool, document the error contract in the tool description alongside purpose, return values, input formats, and edge cases. A good description tells the model not just how to call the tool, but how to interpret what comes back when things go wrong.

One more reliability angle: where the error lands in context matters. Models attend most to the start and end of context and least to the middle ("lost in the middle").

So beyond making errors structured, keep them tight: trim verbose tool output to the relevant fields and surface the error signal cleanly rather than burying errorCategory inside a wall of stack trace. A concise, typed error near the point of decision beats a verbose one drowned in noise.

A research coordinator delegates to a subagent whose database lookup tool returns { "status": "error", "message": "Operation failed" }. The coordinator keeps re-calling the tool and eventually aborts the entire report.

Generic errors like "Operation failed" block recovery because they hide the one thing the model needs — what kind of failure it was.

• Return structured errors: isError, errorCategory (transient/validation/business/permission), isRetryable, message, attempted_query, partial_results.
• Category drives routing: retry transient, fix validation, escalate business/permission.
• Distinguish access failure from a valid empty result.
• Carry partial results forward; never silently suppress or abort the whole workflow on one branch.
• For financial/legal/safety stakes, back structured errors with deterministic hooks.

Structured errors turn a dead end into an intelligent recovery decision.