fastmcp-best-practices

FastMCP Best Practices

Best practices for this FastMCP-based server. See mcp-architecture.mdc for where code lives and pydantic-models.mdc for response model conventions - this file covers FastMCP-specific decorator/documentation/annotation behavior.

Tool Design Principles

Be Selective with Tools

# ❌ BAD - one narrow tool per lookup key
@mcp.tool()
def get_monitor_by_id(monitor_id: int) -> MonitorResponse: ...
@mcp.tool()
def get_monitor_by_name(name: str) -> MonitorResponse: ...

# ✅ GOOD - one well-designed tool with optional filters
@mcp.tool(annotations=READ_ONLY)
def list_all_monitors(
    group_states: str | None = None,
    name: str | None = None,
    tags: str | None = None,
) -> ListMonitorsResponse:
    """List monitors with optional filters.

    Args:
        group_states: Comma-separated states to filter by (e.g. "alert,warn")
        name: Filter by monitor name substring
        tags: Filter by tag query (e.g. "env:prod")
    """
    ...

Why: LLMs perform better with fewer, well-designed tools than many narrow ones. This server currently exposes 30 tools across 7 domains - treat that as close to the practical ceiling, not a floor; a new tool should consolidate related endpoints (see describe_metric, which merges metric metadata + tags into one call) rather than adding a thin wrapper per Datadog endpoint.

Tool Annotations Are Not Optional

Every @mcp.tool in this codebase passes annotations= from utils/annotations.py. Pick the preset honestly - don't default to READ_ONLY for convenience, and don't mark an overwrite as non-destructive just because nothing is "deleted" in the HTTP sense:

from datadog_mcp.utils.annotations import READ_ONLY, WRITE_ADDITIVE, WRITE_OVERWRITE, STATE_TOGGLE

@mcp.tool(annotations=READ_ONLY)       # search/list/get/count/aggregate/validate
def search_logs(...) -> SearchLogsResponse: ...

@mcp.tool(annotations=WRITE_ADDITIVE)  # creates a new resource, not idempotent
def create_alert_monitor(...) -> CreateMonitorResponse: ...

@mcp.tool(annotations=WRITE_OVERWRITE) # overwrites existing state, no undo tool exists
def update_existing_dashboard(...) -> UpdateDashboardResponse: ...

@mcp.tool(annotations=STATE_TOGGLE)    # reversible, has a matching inverse tool
def silence_monitor(...) -> MuteMonitorResponse: ...