Output Schemas

from pydantic import BaseModel, Field

class Issue(BaseModel):
    id: str
    title: str
    status: str = Field(description="Current status: open, closed, or in_progress")

@mcp.tool()
def get_issue(issue_id: str) -> Issue:
    """Fetch an issue by ID."""
    return Issue(id=issue_id, title="Bug report", status="open")

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "title": { "type": "string" },
    "status": {
      "type": "string",
      "description": "Current status: open, closed, or in_progress"
    }
  },
  "required": ["id", "title", "status"]
}

@mcp.tool()
def list_issues() -> list[Issue]:
    """List all issues."""
    return [Issue(...), Issue(...)]

@mcp.tool()
def get_stats() -> dict[str, int]:
    """Get issue statistics."""
    return {"open": 5, "closed": 12}

@mcp.tool()
def count_issues() -> int:
    """Count total issues."""
    return 17

# No return type — no schema generated
@mcp.tool()
def bad_tool():
    return {"data": "value"}

# Untyped dict — schema too generic
@mcp.tool()
def also_bad() -> dict:
    return {"data": "value"}

class SearchResult(BaseModel):
    url: str = Field(description="Full URL to the document")
    title: str = Field(description="Document title")
    score: float = Field(description="Relevance score from 0 to 1")