Best Practices

Well-designed tools are easier for AI to understand and use correctly. Follow these best practices to create effective MCP servers.

Naming Conventions

Tool Names

  • Use snake_case for tool names
  • Be descriptive but concise
  • Start with a verb when possible

Good: get_user, create_order, search_products

Avoid: user, doStuff, getData

Parameter Names

  • Use clear, descriptive names
  • Avoid abbreviations
  • Be consistent across tools

Good: user_id, start_date, search_query

Avoid: uid, sd, q

Writing Descriptions

Descriptions help AI understand when and how to use your tools.

Tool Descriptions

Include:

  • What the tool does
  • When to use it
  • Any important constraints
"description": "Retrieves weather forecast for a location. Use when the user asks about weather conditions. Requires a city name or coordinates."

Parameter Descriptions

Explain:

  • What the parameter represents
  • Expected format
  • Valid values or ranges
"date": {
  "description": "The date for the forecast in YYYY-MM-DD format. Must be within the next 7 days.",
  "type": "string"
}

Error Handling

Return clear, actionable error messages:

{
  "error": {
    "code": "INVALID_DATE",
    "message": "Date must be in YYYY-MM-DD format",
    "suggestion": "Try using 2024-01-15 instead of January 15"
  }
}

Response Design

Keep Responses Focused

Return only relevant information. AI works better with concise responses.

Good:

{
  "temperature": 72,
  "condition": "sunny",
  "humidity": 45
}

Avoid: Including unnecessary metadata, debug info, or unrelated fields.

Use Consistent Structures

Maintain consistent response formats across all tools in your server.

Rate Limiting

Implement appropriate rate limits:

  • Per-user limits: Prevent individual abuse
  • Global limits: Protect your infrastructure
  • Graceful degradation: Return helpful messages when limits are hit

Testing

Before publishing:

  1. Test all tools with various inputs
  2. Verify error handling
  3. Check response times
  4. Test edge cases
  5. Validate authentication flows