This PR introduces a comprehensive examples system to the MCP Tool schema that addresses three critical use cases: LLM guidance, human documentation, and automated testing. By adding concrete examples to tool definitions, we enable better tool discovery, understanding, and validation across the entire MCP ecosystem.

Motivation and Context

Organizations implementing MCP need better ways to help LLMs understand and use tools effectively. Currently, tools only have basic descriptions, which can lead to:

• Poor tool selection by LLMs due to unclear capabilities
• Increased hallucination when models guess at tool behavior
• Lack of concrete examples for developers learning to implement tools
• No standardized way to test tool implementations

This change enables 1-shot learning for LLMs, provides clear documentation for developers, and establishes a foundation for automated testing and tool registries.

How Has This Been Tested?

• Schema validation passes with npm run validate:schema
• JSON schema generation works correctly with npm run generate:json
• TypeScript compilation succeeds
• Documentation examples are comprehensive and accurate
• Examples demonstrate all key features and edge cases including basic usage patterns, error handling, and complex scenarios with structured outputs

The examples have been tested with real tool implementations to ensure they provide meaningful guidance for both LLMs and human developers.

Breaking Changes

None. This is a purely additive change - the examples field is optional and all existing tool definitions remain valid.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Key Implementation Details

New ToolExample interface with:

• id: Unique identifier for automated testing and LLM disambiguation
• description: Clear explanation targeting both humans and LLMs
• input: Example arguments matching the tool's input schema
• output: Expected result structure with content, structured data, and error status

Enhanced Tool interface to include:

• Optional examples array of ToolExample objects
• Enhanced description emphasizing dual human/LLM audience

Example Usage

{
  name: "calculate_fibonacci",
  description: "Calculate the nth Fibonacci number for mathematical operations",
  inputSchema: {
    type: "object",
    properties: {
      n: { type: "integer", minimum: 0 }
    },
    required: ["n"]
  },
  examples: [
    {
      id: "basic_calculation",
      description: "Standard calculation case - compute the 5th Fibonacci number",
      input: { n: 5 },
      output: {
        content: [{ type: "text", text: "The 5th Fibonacci number is 5" }],
        structuredContent: { result: 5, sequence: [0, 1, 1, 2, 3, 5] }
      }
    }
  ]
}

Impact and Benefits

1. Improving LLM Performance: Better tool understanding leads to more accurate and reliable AI interactions
2. Enabling Better Tooling: Tool registries, IDEs, and documentation systems can leverage examples for richer experiences
3. Supporting Quality Assurance: Standardized examples enable comprehensive testing and validation