Abstract

This SEP proposes adding documentation best practices to the MCP specification to establish consistent patterns for tool descriptions versus schema descriptions. Currently, the specification defines the structure of tools (description and inputSchema fields) but provides no guidance on their intended content, leading to inconsistent implementations across MCP servers. This proposal establishes clear separation of concerns: tool descriptions provide high-level functionality explanations while schema descriptions provide parameter-specific details.

Motivation

The existing MCP specification is inadequate for addressing documentation consistency because:

1. Structural Definition Without Usage Guidance: The specification defines tool.description and inputSchema fields but doesn't explain their intended purposes or content patterns.
2. Implementation Inconsistency: Analysis of existing MCP servers reveals mixed patterns:
   • Memory, git, and everything servers properly separate high-level descriptions from parameter details
   • Some filesystem tools include parameter specifics in tool descriptions
   • New implementers lack clear guidance on which approach to follow
3. Real-World Confusion: Recent PR review discussions (e.g., servers PR #2602) demonstrate developer uncertainty about documentation boundaries.
4. LLM Consumption Impact: Inconsistent documentation patterns affect how LLMs understand and utilize tools, potentially degrading the user experience.

Without standardized documentation practices, the MCP ecosystem will continue to suffer from inconsistent tool interfaces that confuse both implementers and consumers.

Specification

Add a new section to the MCP specification titled "Tool Documentation Best Practices":

Tool Documentation Best Practices

Tool Description

The description field should provide a concise, high-level explanation of what the tool accomplishes:

• Purpose: Communicate tool functionality and use cases
• Audience:
  • LLMs who need select appropriate tools
  • Developers who need to understand the tool capabilities
• Content Guidelines:
  • Avoid parameter-specific details

Example:

{
  name: "read_multiple_files",
  description: "Read the contents of multiple files simultaneously. More efficient than reading files individually when analyzing or comparing multiple files."
}

Schema Descriptions

The inputSchema property descriptions should provide parameter-specific documentation:

• Purpose: Guide correct tool invocation
• Audience:
  • LLMs constructing tool calls
  • Developers implementing clients
• Content Guidelines:
  • Specify parameter types and constraints
  • Include validation requirements
  • Provide usage examples where helpful
  • Explain parameter relationships

Example:

const schema = z.object({
  paths: z.array(z.string())
    .min(1, "At least one file path must be provided")
    .describe("Array of file paths to read. Each path must be a valid absolute or relative file path.")
});

Rationale

Separation of Concerns: Tool descriptions and schema descriptions serve different purposes and audiences. Tool descriptions help with tool selection and understanding, while schema descriptions guide proper usage.

Flexibility Over Prescription: The guidelines provide clear direction while allowing implementation flexibility, recognizing that different tools may have unique documentation needs.

LLM-First Design: The practices optimize for LLM consumption patterns, where tools are first discovered via descriptions then invoked via schemas.

Backward Compatibility

This SEP introduces no backward incompatibilities:

• Existing tool implementations remain valid
• No changes to protocol structure or behavior
• Additive guidance only - no breaking changes
• Servers can adopt best practices incrementally

Reference Implementation

This is a doc-only SEP. There is no code implementation.

Security Implications

This SEP has minimal security implications:

1. Clearer documentation may reduce misuse of tools due to misunderstanding.
2. Better validation guidance encourages proper input checking
3. Documentation changes don't affect protocol security