Explain rejected requests without inviting retries

Learning objective

Return non-retryable business-rule violations with a customer-friendly explanation suitable for agent communication.

Core idea

A business-rule rejection means that a valid operation cannot proceed under the applicable policy. It is not a temporary service failure. Return the rejection as an MCP tool execution error and tell the agent both that unchanged retries are ineligible and how to explain the decision to the customer.

A refund tool that returns only “Operation failed” leaves several possibilities open: unavailable payment service, invalid input, insufficient permissions, or an ineligible refund. An agent can recover from some of these, but it cannot repair a policy rejection by repeating the same request. The result must make the finality of that operation explicit without implying that every other customer option is closed.

How it works

Preserve the business decision in the result

MCP lists business logic errors among tool execution errors returned with isError: true. Use that mechanism for an enforced rule rejection from a recognized tool. The tool can also return an application-defined structured object in structuredContent. See 2.2.1 for the response envelope and 2.2.2 for the shared classification contract.

For this lesson’s example contract, a business rejection carries errorCategory: "business", isRetryable: false, an explanation, and a permitted nextAction. These payload keys are your schema, not MCP-defined flags. The exam guide’s phrase retriable: false expresses the same non-retryable intent under a different application field name. Recognize both spellings on the exam, but document one canonical key in an implementation.

The tool should derive the explanation from the rule it actually enforced. A model-provided claim that the customer qualifies does not establish eligibility. See 1.4.2 for verified policy state and 1.5.1 for blocking sensitive calls before side effects. This lesson starts where that enforcement has produced a rejection and asks what information should cross back to the agent.

State the reason in customer language

A useful explanation names the requested action, the reason it cannot proceed, and any allowed next step. Avoid replacing the reason with a traceback or an internal rule code. Anthropic’s tool guidance recommends specific, actionable error responses over opaque codes and tracebacks; a business rejection needs the same care as a validation error.

Suppose a fictional merchant accepts standard refunds only within 30 days of purchase. That number is the scenario’s business policy, not an Anthropic or MCP limit. A customer-safe result can say that the purchase is outside the merchant’s 30-day refund period and that the standard refund was not issued. It should not say the payment service is broken or invite the customer to repeat the request later.

A shortened example structuredContent object is:

{
  "errorCategory": "business",
  "isRetryable": false,
  "explanation": "This purchase is outside the 30-day refund period. No refund was issued.",
  "nextAction": "Offer a support review without promising an exception."
}

The tool returns this object within an isError: true MCP result. See 2.2.2 for schema conformance and the Agent SDK delivery boundary: when structuredContent is present, Claude reads its JSON instead of the text copy. Python in-process handlers carry the explanation in text content instead.

Separate explanation from permission to override

“Offer a support review” names an allowed customer service option in this example. It does not authorize another refund tool call, promise approval, or alter the eligibility rule. Keep the next action within the policy the handler can substantiate. If the business exposes no approved exception path, do not manufacture one in the error response.

The agent can translate the explanation into conversational language while preserving its substance. It can say that the standard refund is unavailable because the purchase falls outside the stated period. It should not recast the rejection as a technical problem, remove the deciding reason, or claim that a review guarantees payment.

A non-retryable operation is not necessarily the end of the conversation. The customer might ask for a policy explanation or choose a separate permitted support process. Those actions address the customer need without retrying the rejected operation. The result contract should distinguish them so the agent does not confuse continued assistance with continued execution attempts.

Keep disclosures within the authorized scope

MCP requires servers to implement access controls and sanitize tool outputs. Customer-friendly wording does not justify revealing another customer’s data, a secret, or an internal exception trace. Explain the rule using the evidence the authorized customer can receive. If a permission failure prevents establishing eligibility, return that limitation rather than asserting a business rejection you have not verified.

Similarly, distinguish an eligibility rejection from an uncertain execution outcome. “No refund was issued” is appropriate only when the handler knows it rejected the operation before issuing a refund. If a dependency timeout leaves the outcome unknown, that is not the same result. Preserve the uncertainty and use the recovery treatment in 2.2.5 rather than falsely declaring a final business decision.

Key distinctions and trade-offs

Business rejection versus transient failure: A policy condition remains false when the same call repeats. A temporary outage can resolve without changing the request. The recovery metadata must distinguish these cases.

Customer explanation versus internal diagnosis: The agent needs a reason it can communicate and a permitted next step. An internal traceback adds implementation detail without explaining the customer’s options.

Non-retryable versus unhelpful: You can stop execution retries while continuing to explain policy or arrange an approved review. Finality belongs to the rejected operation, not automatically to every form of assistance.

A concise explanation is easier to communicate, but omitting the decisive condition can make the rejection sound arbitrary. Include the rule that matters and the supported outcome, then exclude irrelevant internals.

Architecture / decision scenario

A customer support agent requests a refund for a purchase 45 days ago. The fictional merchant’s verified standard-refund policy permits 30 days. The refund handler checks eligibility before payment execution and rejects the request. It returns isError: true with errorCategory: "business", isRetryable: false, and a customer-safe explanation that no refund was issued because the purchase is outside that period.

The agent does not retry the same request or switch tools to obtain the prohibited result. It explains the standard-refund decision and offers the merchant’s approved support review, carefully avoiding a promise of an exception. If the customer asks for that review, it becomes a separate permitted workflow with its own outcome.

Now change the evidence: the handler cannot read the policy service because access is denied. It cannot conclude that the purchase violates the rule. It returns a permission failure instead. The customer-facing explanation says eligibility could not be checked, preserving the distinction between a known business rejection and missing access to the deciding evidence.

Common exam traps

• Retrying a business-rule violation as if it were a timeout.
• Returning retriable: false without an intelligible reason.
• Treating a suggested review as authorization to override policy.
• Claiming a refund was not issued when execution status is unknown.
• Reporting a policy rejection when access prevented checking eligibility.

Where the exam guide differs

What to remember

A final business rejection needs an error signal, explicit non-retryability, and a safe explanation of the enforced condition. Preserve the outcome and allowed next action when the agent communicates it. Continued customer assistance does not require repeating or bypassing the rejected operation.

Knowledge check

References

• Model Context Protocol, Tools
• Anthropic, Writing effective tools for agents
• Anthropic, Claude Certified Architect – Foundations Exam Guide
• Model Context Protocol, Key Changes, protocol revision 2026-07-28