The MCP-server mistakes that make agents give up

An MCP server is a promise: agents can use this product directly. But the agent reading it can’t ping you on Slack when a tool name is confusing. It makes a guess, and if the guess fails, it moves on. Here are the mistakes we see end runs most often.

1. Tool names that describe your architecture, not the task

execute_query_v2 tells the agent nothing about when to use it. search_customers does. Agents match tools to intent by name first; if the name encodes your internal model instead of the user’s goal, the agent picks the wrong tool or none at all.

2. Schemas that are technically valid and practically unusable

A parameter typed string with no description, no example, and no enum is a coin flip. The agent will fill it with something plausible and wrong. Every field the agent must supply needs a description written for someone who has never read your docs — because the agent hasn’t.

3. Errors that don’t tell the agent what to do next

A human sees 400: invalid request and opens the docs. An agent sees it and retries the same thing, or quits. Good agent-facing errors are instructions: “region is required; valid values are us-east, eu-west.” That single sentence turns a dead end into a completed task.

4. Responses the agent can’t act on

If a tool returns a giant blob the agent has to parse and re-summarize, you’ve spent its budget and its patience. Return the shape the next step needs.

The test

Give an agent a real task, hand it only your MCP server, and read the transcript. The exact line where it hesitates, guesses, or gives up is your fix list — ranked, because the earliest failure matters most.

We do this for a living. If you want the transcript for your server, request an audit.