mcp-description-wrapper

MCP Description Wrapper

A Model Context Protocol (MCP) server wrapper that allows you to override tool descriptions for testing AI agent adoption and behavior.

Purpose

This tool enables A/B testing of tool descriptions to measure their impact on AI agent adoption rates. By changing only the descriptions while keeping functionality identical, you can determine which descriptions lead to better tool usage by AI agents.

Usage

Basic Usage

# Wrap an existing MCP server with custom descriptions
./mcp-wrapper --descriptions my-descriptions.json /path/to/upstream-mcp-server

# Or use environment variable for upstream command
export MCP_UPSTREAM_COMMAND="/path/to/upstream-mcp-server --some-flag"
./mcp-wrapper --descriptions my-descriptions.json

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "wrapped-server": {
      "command": "/path/to/mcp-wrapper",
      "args": ["--descriptions", "/path/to/descriptions.json", "/path/to/upstream-server"]
    }
  }
}

Descriptions File Format

Create a JSON file with tool names as keys and new descriptions as values:

{
  "tool_name": "New description for this tool",
  "another_tool": "Different description to test AI agent adoption",
  "file_read": "📖 Intelligent file content retrieval with contextual analysis capabilities"
}

Examples

Testing Different Description Styles

Original: "file_read": "Read file contents"

Descriptive: "file_read": "📖 Intelligent file content retrieval with contextual analysis capabilities"

Action-oriented: "file_read": "🔍 Extract and analyze file contents for processing"

Problem-focused: "file_read": "📋 Solve file access needs with comprehensive content reading"

Sample Descriptions

See sample-descriptions.json for examples of enhanced descriptions that use:

• Emojis for visual appeal
• Power words ("Advanced", "Intelligent", "Comprehensive")
• Benefit statements ("perfect for testing", "optimized for AI")
• Technical specificity ("semantic filtering", "algorithmic support")

Building

go mod init mcp-description-wrapper
go get github.com/mark3labs/mcp-go
go build -o mcp-wrapper

Environment Variables

• MCP_DEBUG=1: Enable debug logging
• MCP_UPSTREAM_COMMAND: Default upstream command if not provided as argument

Testing Methodology

1. Baseline: Run your MCP server normally and measure tool usage
2. Treatment: Use the wrapper with enhanced descriptions
3. Metrics: Compare adoption rates, usage frequency, and task completion
4. Variables: Test different description styles (technical vs. friendly, short vs. detailed, etc.)

Architecture

The wrapper:

1. Starts the upstream MCP server as a subprocess
2. Intercepts tool discovery requests
3. Replaces descriptions from the JSON file
4. Proxies all tool calls to the upstream server unchanged
5. Returns results transparently

This ensures functionality remains identical while only descriptions change.