PATTERN Cited by 1 source
Actionable error messages (as agent-recovery primitive)¶
Actionable error messages replace generic errors
("invalid query") with specific, corrective ones
("unknown field 'stauts' – did you mean 'status'?"). For agent
consumers, this is not a human-ergonomics nicety — it is the
primary recovery primitive that determines whether the agent
converges or loops
(Source: sources/2026-03-04-datadog-mcp-server-agent-tools).
Failure mode¶
Observed by Datadog on V1: an agent sends a malformed query, gets a
generic "invalid query" back, and tries the exact same thing
again (or gives up entirely). The error message carries no signal
the model can act on.
Shape of an actionable error¶
Carries the nearest valid correction:
"unknown field 'stauts' – did you mean 'status'?"- Enumerate the set of valid options when small:
"unknown filter 'sev'; valid filters: severity, service, env". - Echo back the parsed shape of the request so the agent can see what the server understood.
Two complementary channels¶
The Datadog post names two pairing patterns that sit next to error-message quality:
- Discoverable documentation via a
search_datadog_docsRAG-backed tool reachable from MCP server instructions. Agents unsure about syntax or options look it up on demand — the server doesn't have to cram every detail into tool descriptions, which would cost context budget on every call. - Advisory guidance inside successful responses, not just
errors — tool results can carry prose hints like "you searched
for
payment, did you meanpayments?". This is a deliberate departure from REST API conventions where no party on the request side can reason over prose.
Why this departs from traditional API-error design¶
A REST client is code; specific corrective text in an error is wasted on it (the caller already has the schema). An agent client is a language model; specific corrective text is exactly the input shape it uses to recover. Good error messages systematically shift what would be agent retry-loop tokens into server-side localization work.
Seen in¶
- sources/2026-03-04-datadog-mcp-server-agent-tools — cited as one of the design moves that "paid off" once Datadog treated error messages as agent-recovery input, not operator-debug output.