When I built the MCP server for Kompasss, my agent discovery and commerce platform, it ended up exposing more than 40 tools. That number sounds like the headline, but it's actually the least interesting part. Here's what I actually learned.

Your tool descriptions are your real API

When a human uses an API, bad docs cost them time. When an agent uses a tool, a bad description costs you correctness: the model either never calls the tool, calls it at the wrong moment, or stuffs the wrong arguments into it. I ended up rewriting tool descriptions more often than tool implementations. The pattern that worked: describe the tool the way you'd brief a new teammate. What it does, when to reach for it, when not to, and what the output looks like. One sentence of "when not to use this" prevents more failed calls than three paragraphs of parameter documentation.

Fewer, wider tools beat many narrow ones

My first version had separate tools for every small operation. The agent had to chain four calls to do one meaningful thing, and every extra call was another chance to go wrong. Consolidating related operations into fewer, more capable tools cut both latency and failure rates. The test I use now: if a tool is only ever useful immediately after another specific tool, they're probably one tool.

Agents need errors they can act on

A human reads a stack trace. An agent reads your error message and decides what to do next. Returning "invalid request" is a dead end; returning "the agent id was not found, use search_agents to look it up first" turns a failure into a recovery path. Error messages became part of the orchestration design, not an afterthought.

Payments change everything

Kompasss uses x402-style per-call payments and USDC escrow flows, which means a tool call can cost real money. That forces discipline you don't get in free-tool land: idempotency, explicit confirmation steps for irreversible actions, and clear budget signals in the tool contract itself. Designing tools as if every call costs something makes the whole server better, even the free parts.

The takeaway

Tool count is vanity. What matters is whether an agent that has never seen your system can read your tool list and do real work without a human untangling it. That's the bar I now design for.