Documentation mixes annotations={} options (dict/ToolAnnotations)

[pamelafox]

Enhancement

The documentation uses both approaches:

@mcp.tool(annotations={"readOnlyHint": True})
def get_user(user_id: str) -> dict:
    """Retrieve user information by ID."""
    return {"id": user_id, "name": "Alice"}

@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
        idempotentHint=True,  # Same result for repeated calls
        openWorldHint=False   # Only internal data
    )
)
def search_products(query: str) -> list[dict]:
    """Search the product catalog."""
    return [{"id": 1, "name": "Widget", "price": 29.99}]

Is that intentional? I would think the ToolAnnotations was the better approach for more type-safety, but I'm confused by the mixing of them in one example.

[gnanirahulnutakki]

I'd like to take this one. My first pass will keep the scope strictly to the docs/examples surface: find the mixed annotations={...} vs ToolAnnotations(...) usage called out here, choose one consistent style for the user-facing examples, and verify the docs still reflect the accepted API without broad refactoring.