CCAR-F - Tool Design & MCP Integration - Section 2.2

Implement structured error responses for MCP tools.

The MCP isError flag communicates a failure back to the agent, but a uniform message such as Operation failed strips the agent of any basis for recovery. Candidates should distinguish transient, validation, business and permission errors, return structured metadata (errorCategory, isRetryable, a human-readable description), recover locally inside a subagent for transient failures, and separate an access failure from a valid empty result that represents a successful query with no matches.

MCP isError flagerrorCategory and isRetryable metadatatransient versus validation versus business errorslocal error recovery in subagentsaccess failure versus valid empty result

Practice question for this objective

Free sampleTool Design & MCP Integrationmedium

A multi-agent research system delegates archive work to a document analysis subagent through the MCP tool corpus_search. When the internal archive holds no passage matching a query, the tool returns a tool result with is_error set to true and the text "no result from archive". The coordinator treats that as an outage, retries three times, then writes into the report that the archive was unavailable. A quality review of 200 runs finds that in 60 percent of the runs carrying that sentence the archive was healthy and the query genuinely matched nothing. Which change most effectively addresses the reviewed defect?

  • ARaise the corpus_search request timeout and increase the coordinator's retry count from three to six so that a slow archive has more opportunity to answer before the run gives up on it.
  • BInstruct the synthesis subagent in its system prompt to read the phrase about the archive being unavailable as possibly meaning that nothing matched, and to soften the report wording accordingly.
  • CReturn a successful tool result whose structured payload states that the search completed and matched no passages, and reserve is_error for cases where the archive could not be read at all. Correct
  • DHave corpus_search widen each query with generated synonyms and re-run it internally before returning, so that a query matching no passage at all becomes far less common in practice.
Reserve the error flag for failures to execute; a query that completes with no matches is a successful result, not an access failure. Overloading the error channel with a valid empty result destroys the distinction the caller needs most, which is whether the source was read at all. Once a completed search that matched nothing is returned as an ordinary success carrying a zero match count, retry logic stops firing on correct answers and the report can state a genuine negative finding.

Why A is wrong: Tempting because retries and timeouts are the usual response to an apparent outage, but the archive is answering correctly and quickly, so every added attempt repeats a call that returns the same accurate empty result at extra cost.

Why B is wrong: Tempting because it addresses the visible report sentence, but it asks a downstream model to guess at an ambiguity the tool created, and the coordinator has already burned three retries before the synthesis subagent sees anything.

Why C is correct: Correct because a query that runs to completion and matches nothing is a valid answer rather than a failure, and separating the two states stops the coordinator converting an accurate negative finding into a false outage claim.

Why D is wrong: Tempting because it reduces how often the empty case arises, but it changes retrieval semantics without consent and leaves the underlying signalling defect intact for any query that still matches nothing.

See more CCAR-F practice questions, answers explained.

More in this domain

Back to all Tool Design & MCP Integration objectives, or the CCAR-F cert hub.

Examworthy is not affiliated with or endorsed by Anthropic. Original, blueprint-aligned practice material only.