Models decide whether and how to call MCP tools from their descriptions. Good descriptions are the difference between a useful server and a confusing one.
Names
Use clear, specific names like search_invoices rather than query or do_action. When many servers are connected, distinct names avoid collisions and confusion.
Descriptions
Explain:
- What the tool does.
- When to use it — and when to use another tool instead.
- What it returns.
- Important limits: result caps, date ranges, required permissions.
Input Schemas
- Describe every parameter, with formats and examples.
- Use enums for fixed options.
- Mark required fields correctly.
- Prefer a few meaningful parameters over many optional ones.
Outputs
Return concise, readable results with meaningful identifiers. Indicate truncation and how to get more.
Annotations
The protocol lets tools carry hints, such as whether they are read-only or destructive. Hosts may use these for approval decisions, but they're hints, not guarantees — hosts shouldn't trust them from untrusted servers.
Test and Refine
Try realistic requests and check that the model picks the right tool with correct arguments.