> TOOL DESIGN PATTERNS [BEST PRACTICES]

▶ TOOL CATEGORIZATION STRATEGY

Categorize tools by domain: devops, data, creative - with consistent metadata patterns

{
  "categories": {
    "devops": ["git_commit", "deploy_service", "run_tests"],
    "data": ["query_database", "transform_csv", "generate_report"],
    "creative": ["generate_image", "write_story", "compose_music"],
    "analysis": ["analyze_code", "find_patterns", "summarize_data"]
  }
}

▶ STRUCTURED METADATA PATTERN

DEMONSTRATION: annotatedMessage shows structured metadata (error/success/debug)

{
  "tool": "annotatedMessage",
  "response": {
    "content": "Operation completed successfully",
    "metadata": {
      "type": "success",
      "severity": "info",
      "timestamp": "2025-11-19T10:30:00Z",
      "duration_ms": 150,
      "resources_used": ["cpu", "memory"],
      "debug_info": {
        "execution_path": "standard",
        "cache_hit": true,
        "validation_passed": true
      }
    }
  }
}

Metadata Categories:

SUCCESS: Operation completed without issues
WARNING: Completed but with concerns
ERROR: Failed operation with error details
DEBUG: Development and troubleshooting information

▶ ADVANCED DESIGN PATTERNS

🔗 RESOURCE REFERENCES

Tools output resource URIs for large datasets.

🔄 IDEMPOTENT OPERATIONS

Same input always produces the same output for predictable behavior.

📦 DECLARATIVE FRAMEWORKS

Use FastMCP for structure-driven development and schema generation.

▶ RESOURCE REFERENCE PATTERN

┌──────────────────────────────────────────────────────────────┐ │ RESOURCE REFERENCE WORKFLOW │ ├──────────────────────────────────────────────────────────────┤ │ │ │ 1. Tool Execution 2. Large Output 3. Resource Ref │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ query_large │────►│ Generate │────►│ Return URI │ │ │ │ _dataset │ │ 10MB result │ │ resource:// │ │ │ └─────────────┘ └─────────────┘ │ /results/42 │ │ │ └─────────────┘ │ │ │ │ │ 4. Client Access ▼ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Client │────►│ Fetch │ │ │ │ requests │ │ resource │ │ │ │ resource │ │ content │ │ │ └─────────────┘ └─────────────┘ │ │ │ │ Benefits: Efficient memory usage, streaming support │ └──────────────────────────────────────────────────────────────┘

▶ FASTMCP DECLARATIVE FRAMEWORK

from fastmcp import FastMCP

# Declarative tool definition
@app.tool()
def analyze_code(
    file_path: str,
    language: str = "auto",
    include_metrics: bool = True
) -> dict:
    """Analyze code quality and complexity metrics."""
    return {
        "complexity": calculate_complexity(file_path),
        "quality_score": assess_quality(file_path),
        "suggestions": generate_suggestions(file_path),
        "metadata": {
            "language": detect_language(file_path),
            "lines_of_code": count_lines(file_path),
            "analysis_version": "2.1.0"
        }
    }

FastMCP Benefits:

Type Safety: Automatic JSON schema generation
Documentation: Self-documenting tool interfaces
Validation: Built-in parameter validation
Debugging: Enhanced error reporting and logging

🎮 LIVE DEMO: ANNOTATED MESSAGE

$ mcp-inspector
> Call annotatedMessage tool with different scenarios

[SUCCESS SCENARIO]
Input: message="Process completed", type="success"
Output: {
  "content": "✅ Process completed successfully",
  "metadata": {
    "type": "success",
    "severity": "info",
    "execution_time": "0.15s",
    "resource_usage": "low"
  }
}

[ERROR SCENARIO]
Input: message="Database connection failed", type="error"
Output: {
  "content": "❌ Database connection failed",
  "metadata": {
    "type": "error",
    "severity": "high",
    "error_code": "DB_CONN_001",
    "troubleshooting": "Check network connectivity"
  }
}

Pattern Applications:

Consistent structure across all tool responses
Rich debugging information for development
Standardized error handling patterns
Performance monitoring data collection