Development

MCP Error Messages Written for Humans Hurt the Smartest Agents Most

A 28 September 2026 preprint finds MCP servers' developer-facing error steps make capable agents fail more, and that naming a server tool in the step fixes it.

“Please run: reddit-mcp-buddy –auth.” “Wait before retrying.” Both are ordinary, sensible lines for a developer, and a 28 September 2026 preprint by Xiaonan Xu and Wenjing Wu quotes them as typical of error text in the Model Context Protocol (MCP) ecosystem. Neither is something an agent that can only call a server’s tools can do. The tension is simple: an error message is meant to tell the reader how to fix the problem, but when that reader cannot type or browse, the better it obeys, the surer the helpful advice makes it fail.

Half the next steps assume a human at a keyboard

The authors surveyed 150 widely used MCP servers (the connectors that let a model reach a service). Of 3,001 error messages, 949 tell the caller what to do next, and half of those steps depend on something the server cannot see about the caller. Among credential errors, 62 of 67 steps ask for a terminal command, a configuration change or a web page. On rate limits, 20 of 30 say to wait and retry without naming the call to repeat.

Then they tested what happens. Agents, which could act only through tools, “did what the step said.” A terminal command in the step left 45% of expired-credential tasks recovered. The loss it caused grew from 18 points for GPT-5.5 to 69 for GPT-6 Astra.

GitHub’s rate-limit message makes the point cleanly. With the bare “Wait before retrying.”, 6% of tasks recovered. Rewrite the step to name the specific call to repeat and recovery rose to 88%. Same model, same task; only the sentence changed.

The doctrine assumed a reader with hands

Read across from the survey, the cause looks like the field’s own advice. Nielsen Norman Group’s error-message guidelines say that “merely stating the problem is also not enough; offer some potential remedies.” Anthropic’s guide to writing tools for agents says you can “prompt-engineer your error responses” to communicate “specific and actionable improvements.” The MCP tools specification says execution errors “contain actionable feedback” that models can use to self-correct.

Each line is sound for a person. Each also assumes that whoever reads the message can carry out the remedy. The paper’s full text notes that neither the spec nor Anthropic’s guide addresses that.

That is an inference, and the paper did not test the doctrine. It measured recovery rates and counted strings. But MCP wraps APIs that were built for humans, and the error text came along unchanged. The message now has a second reader, one with no hands.

One sentence in the string, or one in the prompt

The fix is small, which is the strongest evidence that the copy is at fault and the model is not. Naming a server tool in the step raised recovery to 84% for credentials and 88% for rate limits. Deleting the step with a one-sentence prompt raised it to 82%.

This changes the work for two kinds of people. If you maintain an MCP server or an API that agents call, the error strings you wrote years ago now help decide whether a run recovers or stalls; a one-line rewrite pointing at your own login or retry tool is the cheapest reliability work you will do this quarter. If you build agents on other people’s servers, you cannot edit those strings, but you can tell the model in your prompt to ignore steps it cannot perform.

MCP wraps APIs built for humans, so the error message now has a second reader, one with no hands.

One preprint, five OpenAI models

The limits are real. This is a single preprint. It tested five OpenAI models on Berkeley Function Calling Leaderboard tasks, where the agent acts only through tools, and its limitations section says recovery is judged only by the benchmark’s state checks at the turn where the failure happens. Pipeline found no independent replication and no practitioner reaction yet.

Many real setups are also less exposed. A coding agent with shell access can run the suggested command. The MCP spec says there SHOULD always be a human in the loop, and a human can open the web page. The harm lands mainly on tool-only and unattended agents. The “more capable, more obedient, more harmed” pattern also comes from one model family’s progression, so it is a hypothesis about agents in general, not a measured law.

Still, unattended agents are the ones the protocol is being built for, and a second, agent-only interface tends to drift from the human one unless someone owns both. The old advice was to be helpful to the reader. It never said which reader.

This article was written by AI. How Pipeline works.