Agent tool errors: fix the argument, repair the integration, or stop?

The next correction depends on who controls the defect

An agent asks a tool to search departures and receives an error. Changing the date format may solve an input mistake. It cannot repair a client adapter that omitted the tool name. Neither change grants access to a forbidden record or tells you whether a preceding external write took effect.

Before another call, ask three questions: what defect do the records establish, did the model receive enough information to correct it, and who controls the necessary change? This connects diagnosis to a specific intervention, rather than treating every failure as a request to try again.

The distinction draws on two older sources, not a new October release: MCP's version-bound error-reporting rules and Anthropic's engineering advice on transcripts, descriptions, and useful error feedback.[1][2] The cases below complete a routing decision; they do not report a successful tool execution.

Reporting paths are not repair owners

Model Context Protocol (MCP) is a protocol for connecting applications to tools and other context. Its selected Tools edition distinguishes JSON-RPC protocol errors from tool-execution errors. JSON-RPC is the request-and-response format used here; the error envelope is the surrounding response structure, not a complete account of the cause.[1]

CallToolRequest is the schema for a tool-call request. A request that fails that schema is different from a correctly shaped request whose business argument is rejected. SHOULD and MAY are different requirement levels; neither proves what a particular host actually forwards. The edition describes protocol issues as less likely to lead to successful model recovery, not impossible for models to correct.[1]

An isError: true result can identify a malformed date, but it can also report a backend failure that changing the date would not fix. An unknown-tool protocol error may be model-correctable if the current catalog proves the agent selected an obsolete name. Receiving a result object is not the same as completing the business task. The envelope narrows the investigation; it does not finish it.

Anthropic recommends reading raw transcripts, including tool calls and responses, and considering clearer descriptions or examples when invalid-parameter errors recur. It also recommends specific, actionable error feedback rather than opaque codes or tracebacks, while noting that response structure depends on the task and agent.[2] This is attributed vendor guidance, not independent proof of improvement in another deployment.

Check what the model actually saw

Useful feedback needs a working path to the model. Suppose a server returns “departure_date expects YYYY-MM-DD,” but the host replaces it with “tool failed.” The server supplied an actionable diagnostic; the model did not receive it. Rewriting the description might prevent future format mistakes, but it does not demonstrate that the existing feedback path works.

The proposed mechanism has four links: an accurate diagnostic reaches the model; it identifies a violated contract; the model can change the relevant input without changing the user's intent; and the next action stays within authority and effect constraints. A broken link calls for a different intervention, not more confidence in the same correction.

Compare the user's request, selected tool and arguments, documented contract, emitted request, correlated response, and actual model-visible message. A client adapter is the software that translates the selected call into the protocol request. Those observable records can distinguish a selection mistake from a translation defect; private chain of thought is not needed for this procedure.

Even complete feedback does not prove that the model is the cause. Repeated invalid dates can reflect ambiguous instructions, a misunderstood user request, or a server that rejects values its description permits. Better wording is a candidate intervention, not a diagnosis. Retain only authorized, necessary records: do not put credentials or unrestricted customer logs into model context to make an error more detailed. MCP requires server input validation and access controls and recommends client confirmation for sensitive operations; that wording is not proof of enforcement in a deployed integration.[1]

Hypothetical case 1: correct the format, not the travel date

Assumptions, not observed results: a fictional search_departures tool accepts departure_date in YYYY-MM-DD format. Its actual contract establishes that this search does not mutate external records. At a hypothetical decision time of 14 October 2026, the user unambiguously requests departures on 20 October 2026. Access and the rate/cost allowance for one corrected search are already established.

The assumed transcript shows departure_date set to 20/10/2026 and a tool result with isError: true. The invented diagnostic reads “departure_date expects YYYY-MM-DD; received 20/10/2026,” and reaches the model intact. These names and messages are not an MCP-defined error format or a reproduced provider run.

Completed routing decision: the agent can change departure_date to 2026-10-20 and make the bounded, already-permitted search. That changes representation, not intent. No call was executed here, and no returned departure is claimed.

Countercase: if 20 October is outside the permitted booking window, substituting 21 October changes the user's request. Explain the constraint and obtain the user's choice instead. If the documented window permits 20 October but the server rejects it, route the inconsistency to the tool owner. The evidence needed is the applicable window contract and the correlated rejection, not a date that merely makes the error disappear.

Hypothetical case 2: repair the adapter's missing field

Assume the model selected search_departures with the correctly formatted date 2026-10-20 under the same fictional search contract. An adapter-input record retains that name and those arguments. The emitted tools/call request, however, omits params.name, and the correlated server response reports a malformed request failing the request schema. tools/call is the protocol method; params.name identifies the tool in its parameters.[1] The omission and diagnostic are hypothetical wire evidence, not an observed defect or a universal error-code mapping.

Completed routing decision: send the minimal input record, emitted request, and correlated diagnostic to the client-adapter owner. That owner must correct the serialization—the conversion into the transmitted request—and demonstrate that the intended tool name reaches it. Repeating the same model-selected arguments leaves the omitted field unchanged. Changing the travel date would hide the defect rather than repair it.

A repair needs verification at the affected layer: a permitted non-mutating check should establish that the emitted request carries the intended name and arguments, with ordinary result handling still checked. The absence of an error alone is insufficient. No repair or verification was run here.

Catalog countercase: suppose the emitted request includes the selected name, but the current tool catalog no longer contains it. If the catalog and documented purpose unambiguously establish an equivalent supported tool, the agent may correct its selection within existing scope. If equivalence is unclear, seek catalog or contract clarification. A valid emitted request and an applicable catalog can change the owner of the correction; “protocol error means broken adapter” is too strong.

Hypothetical case 3: stop the denied lookup

Assume a fictional record lookup returns an explicit enforced denial for a record outside the user's approved scope. No additional authority has been granted. The refusal uses an implementation-specific response; no universal MCP refusal field or HTTP code is assumed.

Completed routing decision: stop that scoped lookup and retain the denial and target needed for an authorized review. Do not rephrase the call, choose another credential, or use a different tool to obtain the same forbidden record. A helpful diagnostic can explain a scope mismatch without granting access.

Genuine authorization for that target and an available permitted path can change the decision. If authorized investigation instead proves that an already-approved scope was incorrectly enforced, the access-control owner can repair the defect through that path. Until then, the lookup remains stopped, not completed.

Hypothetical case 4: hold repetition while the effect is unknown

Assume a separately authorized tool submitted an external record creation and then returned an API failure with isError: true. No authoritative effect record or applicable safe-repeat contract is available. The error does not establish whether the external provider accepted the creation before the failure.

Completed routing decision: hold automatic repetition and keep the prior effect unresolved. The authorized integration or provider owner must supply the applicable reconciliation or repeat evidence. No absent record, failed creation, receipt, or successful reconciliation is invented.

A definitive applicable no-effect result, a record of the prior accepted effect, or a separately established repeat contract covering this ambiguity can change the next action. This is a stop boundary, not a transport-reconnection tutorial. Knowing which parameter to change is insufficient when the missing evidence concerns what the previous action already did.

A procedure for choosing the next intervention

Use this as proposed application guidance, not an additional set of MCP requirements. Diagnose the failed action proportionately; reuse trusted evidence the application already establishes.

• Preserve intent and scope. Identify the requested target and whether the operation can change or disclose something consequential. An error does not enlarge authority.
• Trace the observable chain. Compare the selected name and arguments with the emitted request, correlated response, and diagnostic actually supplied to the model. Missing visibility is unresolved, not proof that the model ignored feedback.
• Name the evidenced defect. Distinguish invalid representation, a disallowed business value, stale tool selection, malformed request, backend failure, and access refusal when the records support it. An opaque error calls for authorized diagnosis, not speculative edits.
• Route the smallest appropriate change. The agent corrects an evidenced input mistake within intent and authority; the adapter owner repairs a serialization defect; the tool or server owner resolves contract inconsistencies or backend defects; the authorized access owner resolves scope/control questions.
• Check authority and effects before another call. A permitted non-mutating search can allow a bounded representation correction. Stop an explicitly denied action; hold repetition when consequential effects remain unresolved. Use established retry limits instead of stacking blind retries.
• Verify and describe the actual outcome. A corrected request, accepted result, supported answer, and external effect are different achievements. State which was observed and which remains unresolved. A completed stop decision can leave the user's original task unfinished.

Do not turn this into compulsory human approval for every authorized read. Escalate the missing condition, not the whole workflow. If existing contract and runtime evidence already settle a low-consequence correction, use them.

What this method costs—and what would change it

Layered diagnosis may require adapter records, delay completion, or hold a correctable call when records are unavailable. Clear descriptions can prevent an error before investigation is needed; a stronger existing tool contract can settle a condition automatically. The recommendation is proportionate diagnosis, not exhaustive logging.

Evidence can redirect the intervention: a valid emitted request can move attention away from serialization; a current catalog can establish a model-only name correction; a documented transient backend failure covered by existing retry policy can justify that policy; a host message can show that actionable feedback was hidden. Genuine target-specific authority or applicable effect evidence can release a stop. None of these outcomes was observed in a tool run for this article.

Proposed test, not a reported result: in an authorized non-mutating environment, compare matched invalid-format cases with the same diagnostic forwarded intact versus replaced by an opaque failure. Hold the request, contract, and adapter fixed. Examine intent-preserving corrections, blind repetition, wrong-owner routing, and explicit unresolved outcomes; also check whether clearer descriptions prevent the initial mistake. Include a catalog-mismatch case so the method is not rewarded for sending every protocol error to the adapter owner. This is an unexecuted test design, with no validated sample or measured gain.

The visibility recommendation would weaken if clear, correctly delivered feedback did not improve intent-preserving correction on relevant cases, or if contradictory server contracts caused the errors instead. Effort should then shift to the actual contract or implementation defect. Fewer errors achieved by changing the user's task or crossing a permission boundary would not support the recommendation.

Source age and evidence limits

The sources establish documentary semantics and attributed engineering advice—not actual host visibility, deployed control enforcement, recovery rates, latency, savings, or business outcomes. MCP HTML and its official Markdown are two representations from one publisher, not independent empirical confirmation. Anthropic describes its own engineering experience; no claim here depends on its uninspected screenshots or benchmark graphs.

The retained HTML captures were retrieved on 13 October 2026 at 16:43:07 UTC, and the official MCP Markdown at 16:49:37 UTC. The MCP reference is fixed to the historical 2025-11-25 edition. Its editorial publication/update dates are unknown; the edition label establishes neither current deployment compatibility nor a launch date.[1]

Anthropic's captured page displays “Published Sep 11, 2025.” Its publication time, timezone, substantive update date, and agreement with structured date metadata remain unknown.[2] Source dates and retrieval times are distinct from this article's prepared edition date. The analysis uses checked original passages and separately captured official Markdown, not duplicated code tokens from an initial extraction. No SDK, agent-tool recovery, or external action was executed.

The practical conclusion is conditional: change an input when the evidence supports that correction; repair the layer that actually lost or contradicted the intended call; and stop the specific action when authority or effect evidence is missing. A better error message helps diagnosis. It is not, by itself, permission, successful recovery, or a safe-repeat guarantee.