What AI agents actually do with your MCP server
Description and use
MCP servers appear healthy yet agents struggle due to missing tools, bad arguments, ambiguous descriptions, looping calls, and hidden response sizes. mcpspan analytics helps identify and fix these issues, improving agent interactions.
Problem
MCP servers appear healthy but agents struggle due to tool mismatches, argument validation failures, ambiguous tool descriptions, looping calls, and hidden response size issues.
Outcome
The server’s agent interactions improved: fewer missing tool errors, reduced argument validation failures, clearer tool usage, fewer loops, and controlled response sizes, leading to better agent performance and more accurate metrics.
Workflow
- 1. Instrument the MCP server with mcpspan to capture tool usage and metrics.
- 2. Analyze logs to find tool names requested that do not exist and map them to closest existing names.
- 3. Inspect argument validation failures to determine if they stem from schema mismatches.
- 4. Refine tool descriptions to match expected input types (e.g., list vs. count).
- 5. Detect and mitigate looping calls by improving response messages with actionable guidance.
- 6. Monitor response sizes and enforce limits or provide summaries to avoid token waste.
- 7. Iterate on tool definitions and descriptions based on observed metrics.
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.
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.
I built [mcpspan](https://github.com/mcpspan/mcpspan) for this: self-hosted analytics for MCP servers, MIT licensed.
- Record date: 2026-11-02T13:14:10.183Z