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, misleading descriptions, looping calls, and hidden response size issues. mcpspan instrumentation uncovered these patterns, enabling smoother agent interactions without code changes.
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
Instrumentation revealed five key failure modes: missing tools, argument mismatches, misleading descriptions, looping calls, and hidden response size spikes. Addressing these improved agent reliability without code changes.
Workflow
- Instrument server with mcpspan
- Collect agent request logs
- Identify missing tool calls
- Detect schema‑rejection errors
- Analyze tool description mismatches
- Track repeated calls per session
- Measure response sizes per tool
- Adjust tool names, descriptions, and limits
- Re‑instrument to verify improvements
Evidence
Agents guess tool names. Some guesses are near misses: searchFlights when the tool is search_flights, seatMap instead of seat_map. Others are a tool the agent assumed should exist, like get_flight_price.
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.
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.
An agent tries check_in, gets "Check-in opens 24 hours before departure", and calls check_in again with exactly the same arguments. Then again.
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.
- Record date: 2026-10-21T14:56:27.901Z