documentation-standards

Documentation Standards

Clear documentation is critical for MCP tools - the agent relies on it to pick the right tool and call it correctly. This convention is verified against how FastMCP actually renders tool descriptions (see fastmcp-best-practices.mdc for the mechanics): everything meant to be visible in the tool's description must come before Args:; nothing meaningful goes after it.

Tool Docstring Template

Every @mcp.tool function's docstring follows this shape, in this order:

1. One-line summary (verb-first, specific, under ~80 chars)
2. Optional IMPORTANT:/disambiguation note against similarly-named tools
3. Optional Use this when: / DO NOT use for: bullet lists
4. Optional inline call examples (plain text, not an Examples: header required)
5. Args: section - always last, one line per parameter

@mcp.tool(annotations=READ_ONLY)
def search_logs(
    query: str,
    from_time: str,
    to_time: str,
    page_size: int = DEFAULT_PAGE_SIZE,
    cursor: str | None = None,
    sort: str = "timestamp",
    indexes: list[str] | None = None,
) -> SearchLogsResponse:
    """Search and VIEW log entries. Returns paginated results.

    IMPORTANT: Use this ONLY when you need to VIEW log content for debugging.
    For COUNTING logs or unique values, use count_logs or count_unique_values
    instead - they are much faster and lighter since they never fetch raw
    log content.

    Use this when:
    - Need to view actual log messages and details
    - Debugging specific issues
    - Investigating error details

    DO NOT use for:
    - Counting logs (use count_logs)
    - Counting unique sessions/users (use count_unique_values)
    - Statistical analysis (use aggregate_logs_by_field)

    Examples:
        search_logs("status:error", "now-1h", "now")
        search_logs("service:api", "2024-01-28T10:00:00Z", "2024-01-28T11:00:00Z", page_size=50)

    Args:
        query: Search query using Datadog log search syntax (e.g. "status:error service:api")
        from_time: Start time - ISO 8601 (e.g. "2024-01-28T10:00:00Z"), relative date
            math (e.g. "now-1h", "now"), or a millisecond timestamp
        to_time: End time - same accepted formats as from_time
        page_size: Logs per page (default: 25, max: 50)
        cursor: Pagination cursor from a previous response's next_cursor field
        sort: Sort order, "timestamp" or "-timestamp" for descending
        indexes: Optional list of index names to search (e.g. ["main", "retention"])
    """