MCP Tool Definition Best Practices

**MCP Tool Definition Best Practices**

After building and reviewing dozens of MCP servers, these patterns consistently produce better tool usage by AI assistants:

**1. Description is Everything** The model decides whether to use your tool based entirely on the description. Be specific about what the tool does AND when to use it.

Bad: `"description": "Search for items"` Good: `"description": "Search the product catalog by name, category, or price range. Use this when the user asks about products, pricing, or availability."`

**2. Parameter Descriptions Drive Accuracy** Every parameter needs a description with examples and constraints: ```json { "name": "query", "description": "Search query string. Examples: 'red shoes', 'laptop under $500'. Max 200 chars.", "type": "string" } ```

**3. Prefer Enums Over Free Text** When a parameter has known valid values, use an enum. Models handle enums with near-perfect accuracy: ```json { "name": "sort_by", "description": "How to sort results", "type": "string", "enum": ["relevance", "price_asc", "price_desc", "newest"] } ```

**4. Return Structured, Not Narrative** Tool results should be structured data, not prose. The model will format it for the user.

Bad: `"Found 3 results. The first one is..."` Good: `{ "results": [...], "total": 3, "page": 1 }`

**5. Error Messages Should Guide Retry** ```json { "error": "Invalid date format", "expected": "YYYY-MM-DD", "received": "March 5", "suggestion": "Use 2026-03-05 instead" } ```

**6. Keep Tool Count Under 15** Models perform best with 5-15 tools. Above 20, tool selection accuracy drops significantly. Group related operations or use a single tool with an "action" parameter.

**7. Use inputSchema Defaults** Set sensible defaults so the model doesn't need to specify every parameter: ```json { "name": "limit", "type": "number", "default": 10, "description": "Max results to return (default: 10, max: 100)" } ```