mcp-tool-dev

What this skill does

# MCP Tool Creation

Create individual MCP tool functions that follow Anthropic's tool design best practices and the Model Context Protocol specification.

## What MCP Tools Are

An MCP tool is a single function exposed via the Model Context Protocol that an LLM can invoke. Each tool has:
- **Name**: Verb-noun format (`search_documents`, `get_user`, `create_issue`)
- **Description**: 3-4 sentences explaining what the tool does, when to use it, and when not to
- **Input schema**: JSON Schema defining parameters with clear descriptions
- **Handler**: Async function that processes the input and returns MCP content blocks

Tools can be standalone (single-file utilities) or part of an MCP server (grouped related tools).

## When to Use This Skill

- Creating a single tool function for an existing or new MCP server
- Designing tool schemas and descriptions
- Implementing tool input validation and error handling
- Adding capabilities to a FastMCP server

## When NOT to Use

- Building a complete multi-tool MCP server from scratch — use `mcp-server-dev` instead
- Creating Claude Code agents, skills, or commands — use their respective creation skills

## Tool Anatomy

Every MCP tool consists of four parts:

### 1. Name
Use `snake_case` with verb-noun pattern. Be specific — `search_files_by_content` beats `search`.

### 2. Description
Write 3-4 sentences covering:
1. What the tool does (capability statement)
2. When to use it (primary use cases)
3. When NOT to use it (scope boundaries, suggest alternatives)
4. Key behavior notes (pagination, rate limits, return format)

Good descriptions prevent misuse and reduce wasted calls. Include parameter semantics — if "query" means regex vs full-text vs exact match, say so.

### 3. Input Schema
Define parameters using JSON Schema with:
- Clear `description` for each parameter explaining expected format and semantics
- `enum` constraints where values are known
- `default` values for optional parameters
- Required vs optional distinction

### 4. Handler Function
Async function that:
- Validates inputs early (fail fast with specific error messages)
- Returns MCP content blocks: `[{"type": "text", "text": "..."}]`
- Handles errors with corrective guidance (tell the caller what to do differently)

## Quick Reference: FastMCP Pattern (Primary)

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
async def search_documents(query: str, max_results: int = 10) -> str:
    """Search documents by content.

    Performs full-text search across all indexed documents. Use this tool
    when the user wants to find documents containing specific terms or phrases.
    Do not use for metadata-only searches — use list_documents with filters instead.

    Args:
        query: Full-text search query. Supports AND/OR operators.
        max_results: Maximum results to return (1-100, default 10).
    """
    if not query.strip():
        return "Error: query cannot be empty. Provide a search term."
    max_results = min(max(1, max_results), 100)
    results = await do_search(query, max_results)
    return format_results(results)
```

FastMCP infers the JSON Schema from the function signature and docstring. Type hints drive the schema; the docstring `Args:` section populates parameter descriptions.

## Creation Workflow

### Step 1: Design the Tool Interface

Define what the tool does before writing code:
- Name (verb_noun)
- 3-4 sentence description
- Parameters with types and descriptions
- Return format
- Error cases

### Step 2: Write the Schema

For FastMCP, the schema is implicit in the function signature. For manual schemas:

```python
TOOL_SCHEMA = {
    "name": "search_documents",
    "description": "Search documents by content...",
    "inputSchema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Full-text search query"},
            "max_results": {"type": "integer", "default": 10, "minimum": 1, "maximum": 100}
        },
        "required": ["query"]
    }
}
```

### Step 3: Implement the Handler

Write the async handler function. Key principles:
- Validate inputs at the top
- Keep handlers focused — one tool, one job
- Return structured text (markdown tables, JSON snippets) rather than raw data dumps
- Include context in error messages

### Step 4: Write Tests

Test the handler directly by calling it with a dict:

```python
async def test_search_documents():
    result = await search_documents("test query", max_results=5)
    assert "results" in result.lower() or isinstance(result, str)

async def test_search_documents_empty_query():
    result = await search_documents("")
    assert "error" in result.lower()
```

### Step 5: Validate

- Verify the tool appears in `tools/list` response
- Test with Claude to check description clarity
- Confirm error messages guide the caller to correct usage

## Template Reference

Use `templates/mcp-tool-template.py` as a starting point. It includes the FastMCP decorator pattern, input validation, content block returns, and error handling.

## Common Mistakes

1. **Vague descriptions** — "Does stuff with files" gives the LLM no guidance on when to call the tool
2. **Missing parameter descriptions** — parameters without descriptions force the LLM to guess semantics
3. **Generic error messages** — "Error occurred" wastes a tool call; "Query too long (max 500 chars), truncate and retry" helps recovery
4. **Returning raw data** — dumping an entire JSON response; instead format key fields into readable text
5. **Too many parameters** — more than 5-6 parameters signals the tool should be split
6. **No input validation** — trusting all inputs leads to cryptic downstream errors

For detailed SDK examples, Anthropic best practices, and real-world patterns, see `references/tool-design-patterns.md`.