MCP Builder:add Tool

Add MCP Tool

You are helping the user add a new tool to their MCP server using best practices.

Philosophy

"MCP servers should NOT be pure API wrappers. Design tools that satisfy user intent in a single call."

Workflow

Phase 1: Understand the Intent

Ask the user:

1. What will someone ask the agent? (User intent)
2. What result satisfies that intent? (Desired outcome)
3. Is there existing code/API to leverage?

Phase 2: Design the Tool

Apply the "True Task" framework:

User Intent → Outcome → Tool Name

Good Examples:

Bad Examples (API Wrapper Anti-pattern):

Phase 3: Define Input Schema

Create a schema with:

• Required fields: What's absolutely needed?
• Optional fields: What provides flexibility?
• Descriptions: Help the agent understand each field

Python (Pydantic):

class SearchTasksInput(BaseModel):
    query: str = Field(..., description="Search term for task subject or content")
    include_details: bool = Field(True, description="Include full task content")
    status: Optional[str] = Field(None, description="Filter by status: pending, in_progress, done")
    limit: int = Field(10, description="Max results (1-50)")

    model_config = ConfigDict(extra="forbid")

TypeScript (Zod):

const SearchTasksSchema = z.object({
  query: z.string().describe("Search term for task subject or content"),
  include_details: z.boolean().default(true).describe("Include full task content"),
  status: z.enum(["pending", "in_progress", "done"]).optional(),
  limit: z.number().min(1).max(50).default(10),
});

Phase 4: Write the Description

The description tells the agent WHEN to use this tool:

Good: "Search for tasks by keyword. Returns full task details including content, assignee, and due date. Use when the user wants to find specific tasks or see what's assigned to them."

Bad: "Searches tasks" (too vague, doesn't explain when to use)

Phase 5: Implement the Tool

Python (FastMCP):

@mcp.tool()
async def search_tasks(
    query: str,
    include_details: bool = True,
    status: Optional[str] = None,
    limit: int = 10
) -> str:
    """Search for tasks by keyword. Returns full task details including
    content, assignee, and due date. Use when the user wants to find
    specific tasks or see what's assigned to them."""

    # Validate input
    payload = SearchTasksInput(
        query=query,
        include_details=include_details,
        status=status,
        limit=limit
    )

    # Business logic
    results = await task_service.search(payload)

    # Return complete result
    return json.dumps(results, indent=2)

Phase 6: Add Error Handling

Return actionable error messages:

try:
    results = await task_service.search(payload)
    return json.dumps(results)
except ValidationError as e:
    return f"Invalid input: {e.errors()}"
except PermissionError:
    return "Access denied. User does not have permission to search tasks."
except Exception as e:
    return f"Search failed: {str(e)}. Please try again or refine your query."

Tool Design Checklist

Before finalizing, verify:

• Name clearly describes purpose (kebab-case)
• Description tells agent WHEN to use it
• Inputs have descriptions for all parameters
• Output is complete (no follow-up call needed)
• Errors are actionable (agent can reason about them)

Tool Annotations (for ChatGPT Apps)

Set appropriate hints:

Update State

After adding the tool, update .mcp-builder/state.json:

{
  "tools": [
    { "name": "search-tasks", "status": "implemented", "type": "query" }
  ]
}

Next Steps

• /mcp-builder:validate - Check tool follows best practices
• /mcp-builder:test - Test with MCP Inspector