Model Context Protocol does what it promises: write a server once and it works across hosts, with schemas travelling alongside the tools. Adopting it takes an afternoon. Getting a model to use your tools well is the actual project.
What works
- —One server, many hosts — no per-client rewrites.
- —Schemas travel with the tools, so the host validates arguments before anything executes.
- —Transport is deliberately boring; the interesting failures are never there.
- —Errors come back as values rather than exceptions, so an agent can reason about them.
What breaks
01Too many toolsPast roughly 15–20, selection accuracy falls off. The model pattern-matches on names and descriptions rather than reading a registry.
02Vague descriptionsA tool described as “gets data” will be called for everything. Descriptions are prompt engineering, not documentation.
03Overlapping toolsTwo tools that could both plausibly answer means the wrong one gets picked a large share of the time.
04Silent retriesWithout limits, a confused model calls the same tool repeatedly and you find out from the bill.
Three fixes worth doing early
- —Merge overlapping tools and name them for the intent they serve, not the endpoint they wrap.
- —Write descriptions for the model: state when to use it and when not to. The negative case prevents more misfires than the positive one.
- —Rate limit per session so a confused agent fails cheaply rather than expensively.
