MCP servers (Model Context Protocol) have become the standard way to give tools to AI agents. But a poorly defined MCP floods the model’s context, triggers wrong calls and drives up the cost of every interaction. These are the best practices we apply at CloudAPPI to design MCPs that LLMs use reliably.
1. Number of tools and granularity
Less is more. Keep 1 to 10 active tools per server. If a tool supports several similar operations, consolidate them into a single tool with an action enum parameter instead of creating one tool per operation. When the catalog exceeds 20 tools, expose a progressive discovery mechanism (for example a search_tools) so the agent only loads what it needs.
2. Tool descriptions
The description is the prompt the model reads to decide. Write it in plain text or Markdown, not JSON. State clearly when to use the tool and, above all, when NOT to use it. Reserve JSON Schema exclusively for inputSchema and outputSchema.
3. Schema and parameter design
- Use strict enums whenever the set of values is closed.
- Define sensible default values.
- Use clear, user-friendly names.
- Limit each tool to fewer than 8 parameters.
- Include input examples in the description.
4. Non-enumerable fields
When a parameter cannot be closed into an enum (for example, a project identifier), put the most frequent values in the description and offer a companion method that returns the full list, so the agent can resolve the right value without guessing.
5. Payloads and error messages
Return only high-value data: every token counts. Use JSON for structured data and Markdown for readable summaries. Error messages must be actionable: instead of a bare 400, explain which parameter failed and how to fix it.
6. Know your consumer’s limits
The leading LLMs (OpenAI, Anthropic, Gemini) perform best with 10-20 active tools. Account for the rigidity of each schema and careful context management: an MCP that ignores these limits degrades the agent’s accuracy.
In short
A good MCP is small, explicit and predictable: few well-described tools, strict schemas, minimal payloads and actionable errors. That is how we build agents that are more reliable and cheaper to operate.
At CloudAPPI we help organizations design, govern and expose their MCPs and APIs for the era of AI agents.
