MCP Tool Naming Guidelines

Comprehensive guidelines for naming MCP (Model Context Protocol) tools, describing parameters, and documenting tools in a language- and framework-agnostic manner.

Introduction

MCP tools are the building blocks that extend AI assistant capabilities. Consistent naming, clear parameter descriptions, and comprehensive documentation enable agents to understand and use tools effectively across different implementations.

This tile provides language- and framework-agnostic guidelines for:

• Tool naming conventions – Creating predictable, discoverable tool names
• Parameter descriptions – Defining clear, consistent parameter metadata
• Tool documentation – Writing effective descriptions and examples
• Best practices – Ensuring cross-platform compatibility

Naming Conventions

Tool names should be predictable, discoverable, and consistent across implementations.

General Principles

Case Styles

Choose one case style and use it consistently across all tools:

Recommendation: Use snake_case for maximum cross-language compatibility.

Prefixing Strategies

Prefix tools to group related functionality and avoid name collisions:

Tool Name Examples

Parameter Descriptions

Clear parameter descriptions are essential for agents to understand how to use tools correctly.

Parameter Metadata Structure

Each parameter should include:

Writing Effective Descriptions

Type Definitions

Use simple, language-agnostic types that map to common programming language types:

Parameter Examples

{
  "name": "search_web",
  "description": "Search the web for information",
  "parameters": [
    {
      "name": "query",
      "type": "string",
      "description": "Search query string",
      "required": true,
      "examples": ["latest Python release", "weather in London"]
    },
    {
      "name": "limit",
      "type": "integer",
      "description": "Maximum number of results (1-20)",
      "required": false,
      "default": 10,
      "constraints": {"min": 1, "max": 20}
    },
    {
      "name": "use_safe_search",
      "type": "boolean",
      "description": "Enable safe search filtering",
      "required": false,
      "default": true
    }
  ]
}

Tool Documentation

Comprehensive tool documentation helps agents understand when and how to use each tool.

Tool Description Structure

Writing Tool Descriptions

Professional Documentation Guidelines

For production-quality tool documentation, follow these advanced guidelines:

Key Principle: When writing tool descriptions and specs, think of how you would describe your tool to a new hire on your team. Consider the context that you might implicitly bring—specialized query formats, definitions of niche terminology, relationships between underlying resources—and make it explicit.

Error Documentation

Document possible error conditions and their meanings:

Example Tool Documentation

{
  "name": "github_search_repositories",
  "description": "Search for GitHub repositories by keyword, language, or other criteria. Returns matching repositories with metadata.",
  "parameters": [
    {
      "name": "query",
      "type": "string",
      "description": "Search query (supports GitHub search syntax)",
      "required": true,
      "examples": ["language:python", "tensorflow stars:>1000"]
    },
    {
      "name": "sort",
      "type": "string",
      "description": "Sort field: stars, forks, updated",
      "required": false,
      "default": "stars",
      "enum": ["stars", "forks", "updated"]
    },
    {
      "name": "per_page",
      "type": "integer",
      "description": "Results per page (1-100)",
      "required": false,
      "default": 30,
      "constraints": {"min": 1, "max": 100}
    }
  ],
  "returns": {
    "type": "array",
    "description": "List of repository objects with id, name, description, stars, etc."
  },
  "errors": [
    {"code": "INVALID_QUERY", "description": "Search query syntax is invalid"},
    {"code": "RATE_LIMITED", "description": "GitHub API rate limit exceeded"},
    {"code": "NETWORK_ERROR", "description": "Failed to connect to GitHub API"}
  ],
  "examples": [
    {
      "description": "Search for Python machine learning repositories",
      "parameters": {"query": "machine learning language:python", "sort": "stars"}
    }
  ]
}

Best Practices

Language- and Framework-Agnostic Documentation

Consistency Across Tools

• Use the same parameter names for similar concepts (file_path vs filename vs path)
• Maintain consistent ordering of parameters (required first, optional after)
• Follow the same documentation structure for all tools
• Use the same error format across all tools

Discoverability and Organization

• Group related tools with consistent prefixes
• Provide a tool index or categorization
• Include "see also" references to related tools
• Document tool dependencies or prerequisites

Validation and Constraints

• Document all validation rules in parameter descriptions
• Provide meaningful error messages for constraint violations
• Include examples of valid and invalid values
• Document default values for optional parameters

Examples

Good Tool Definition

{
  "name": "weather_get_current",
  "description": "Get current weather conditions for a location",
  "parameters": [
    {
      "name": "location",
      "type": "string",
      "description": "City name, postal code, or coordinates (lat,lon)",
      "required": true,
      "examples": ["New York", "10001", "40.7128,-74.0060"]
    },
    {
      "name": "units",
      "type": "string",
      "description": "Temperature units: metric (Celsius) or imperial (Fahrenheit)",
      "required": false,
      "default": "metric",
      "enum": ["metric", "imperial"]
    }
  ],
  "returns": {
    "type": "object",
    "description": "Weather data including temperature, conditions, humidity, wind"
  }
}

Poor Tool Definition

{
  "name": "getWeather",
  "description": "Gets weather",
  "parameters": [
    {
      "name": "loc",
      "type": "str",
      "required": true
    }
  ]
}

Issues: Inconsistent naming (getWeather vs snake_case), vague description, ambiguous parameter name (loc), language-specific type (str), missing parameter description and examples.

References

• Model Context Protocol (MCP) Specification
• MCP Tools Documentation
• OpenAPI Specification – Inspiration for API documentation patterns
• JSON Schema – For parameter validation definitions

Summary

Effective MCP tool documentation requires:

1. Consistent naming using snake_case with domain prefixes
2. Clear parameter descriptions with types, constraints, and examples
3. Comprehensive tool documentation covering usage, errors, and examples
4. Language-agnostic practices that work across implementations
5. Organized structure for discoverability and maintenance

Following these guidelines ensures that MCP tools are predictable, discoverable, and usable by AI agents across different platforms and implementations.