Tool Development

Patterns for building MCP tools with consistent input validation, error handling, and response formatting.

Tool Anatomy

Every tool consists of:

1. Name — snake_case identifier (e.g., get_user_profile)
2. Description — clear explanation of what the tool does and when to use it
3. Input Schema — JSON Schema defining required and optional parameters
4. Handler — the function that executes when the tool is called

Patterns

CRUD Tools

Standard create, read, update, delete operations. Follow consistent naming: create_item, get_item, update_item, delete_item.

List/Search Tools

Return paginated results with consistent response shapes. Include total count, page info, and filter metadata.

Action Tools

Trigger operations that don't follow CRUD patterns (e.g., send_notification, run_report).

Best Practices

• Write descriptions as if explaining the tool to a new team member
• Validate inputs before processing — fail fast with clear error messages
• Use consistent response shapes across all tools
• Include examples in tool descriptions for complex inputs