What AI agents actually do with your MCP server

Description and use

MCP servers may appear healthy yet agents struggle due to missing tools, bad arguments, ambiguous descriptions, looping calls, and hidden response size issues. mcpspan revealed five hidden patterns, leading to targeted fixes.

Problem

MCP servers can appear healthy yet agents struggle due to missing tools, bad arguments, misleading descriptions, looping calls, and hidden response size issues.

Outcome

After instrumentation, five hidden failure patterns were uncovered, leading to targeted fixes that improved agent reliability without changing core logic.

Workflow

• Instrument server with mcpspan
• Run simulated traffic
• Collect tool call data
• Analyze missing tool calls
• Identify argument validation failures
• Review tool descriptions
• Detect looping calls
• Measure response sizes
• Apply fixes (add tools, update schemas, rewrite descriptions, add limits)

Evidence

Agents guess tool names. Some guesses are near misses: searchFlights when the tool is search_flights, seatMap instead of seat_map.

Source

When an agent sends arguments that don't match the input schema, the MCP SDK rejects them before your handler runs and sends the validation error back to the model as a normal result.

Source

book_flight took passengers, described as "the passengers". Agents read that as a count and sent 2. The schema wanted a list of names, so the SDK refused the call.

Source

An agent tries check_in, gets "Check-in opens 24 hours before departure", and calls check_in again with exactly the same arguments.

Source

A tool that usually answers with 6 kB and sometimes with 650 kB looks fine on every latency chart, because it's fast. But that answer lands in the agent's context window, crowds out everything else, and costs tokens on every following turn.

Source