feat: Add output schema generation for tools and update documentation

Author: PratyushNag

README.md

@@ -73,7 +73,7 @@ The Model Context Protocol allows applications to provide context for LLMs in a
 
 ### Adding MCP to your python project
 
-We recommend using [uv](https://docs.astral.sh/uv/) to manage your Python projects. 
+We recommend using [uv](https://docs.astral.sh/uv/) to manage your Python projects.
 
 If you haven't created a uv-managed project yet, create one:
 
@@ -89,6 +89,7 @@ If you haven't created a uv-managed project yet, create one:
    ```
 
 Alternatively, for projects using pip for dependencies:
+
 ```bash
 pip install "mcp[cli]"
 ```
@@ -128,11 +129,13 @@ def get_greeting(name: str) -> str:
 ```
 
 You can install this server in [Claude Desktop](https://claude.ai/download) and interact with it right away by running:
+
 ```bash
 mcp install server.py
 ```
 
 Alternatively, you can test it with the MCP Inspector:
+
 ```bash
 mcp dev server.py
 ```
@@ -245,6 +248,67 @@ async def fetch_weather(city: str) -> str:
         return response.text
 ```
 
+#### Output Schemas
+
+Tools automatically generate JSON Schema definitions for their return types, helping LLMs understand the structure of the data they'll receive:
+
+```python
+from pydantic import BaseModel
+
+# Tools with primitive return types
+@mcp.tool()
+def get_temperature(city: str) -> float:
+    """Get the current temperature for a city"""
+    # In a real implementation, this would fetch actual weather data
+    return 72.5
+
+# Tools with dictionary return types
+@mcp.tool()
+def get_user(user_id: int) -> dict:
+    """Get user information by ID"""
+    return {"id": user_id, "name": "John Doe", "email": "john@example.com"}
+
+# Using Pydantic models for structured output
+class WeatherData(BaseModel):
+    temperature: float
+    humidity: float
+    conditions: str
+
+@mcp.tool()
+def get_weather_data(city: str) -> WeatherData:
+    """Get structured weather data for a city"""
+    # In a real implementation, this would fetch actual weather data
+    return WeatherData(
+        temperature=72.5,
+        humidity=65.0,
+        conditions="Partly cloudy"
+    )
+
+# Complex nested models
+class Location(BaseModel):
+    city: str
+    country: str
+    coordinates: tuple[float, float]
+
+class WeatherForecast(BaseModel):
+    current: WeatherData
+    location: Location
+    forecast: list[WeatherData]
+
+@mcp.tool()
+def get_weather_forecast(city: str) -> WeatherForecast:
+    """Get detailed weather forecast for a city"""
+    # In a real implementation, this would fetch actual forecast data
+    return WeatherForecast(
+        current=WeatherData(temperature=72.5, humidity=65.0, conditions="Partly cloudy"),
+        location=Location(city=city, country="USA", coordinates=(37.7749, -122.4194)),
+        forecast=[
+            WeatherData(temperature=75.0, humidity=62.0, conditions="Sunny"),
+            WeatherData(temperature=68.0, humidity=80.0, conditions="Rainy")
+        ]
+    )
+```
+
 ### Prompts
 
 Prompts are reusable templates that help LLMs interact with your server effectively:
@@ -381,6 +445,7 @@ if __name__ == "__main__":
 ```
 
 Run it with:
+
 ```bash
 python server.py
 # or
@@ -458,18 +523,17 @@ app.mount("/math", math.mcp.streamable_http_app())
 ```
 
 For low level server with Streamable HTTP implementations, see:
+
 - Stateful server: [`examples/servers/simple-streamablehttp/`](examples/servers/simple-streamablehttp/)
 - Stateless server: [`examples/servers/simple-streamablehttp-stateless/`](examples/servers/simple-streamablehttp-stateless/)
 
-
-
 The streamable HTTP transport supports:
+
 - Stateful and stateless operation modes
 - Resumability with event stores
-- JSON or SSE response formats  
+- JSON or SSE response formats
 - Better scalability for multi-node deployments
 
-
 ### Mounting to an Existing ASGI Server
 
 > **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
@@ -637,6 +701,7 @@ async def query_db(name: str, arguments: dict) -> list:
 ```
 
 The lifespan API provides:
+
 - A way to initialize resources when the server starts and clean them up when it stops
 - Access to initialized resources through the request context in handlers
 - Type-safe context passing between lifespan and request handlers

src/mcp/server/fastmcp/server.py

@@ -253,6 +253,7 @@ async def list_tools(self) -> list[MCPTool]:
                 name=info.name,
                 description=info.description,
                 inputSchema=info.parameters,
+                outputSchema=info.output_schema,
                 annotations=info.annotations,
             )
             for info in tools

src/mcp/server/fastmcp/tools/base.py

@@ -23,6 +23,9 @@ class Tool(BaseModel):
     name: str = Field(description="Name of the tool")
     description: str = Field(description="Description of what the tool does")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
+    output_schema: dict[str, Any] | None = Field(
+        None, description="JSON schema for tool output format"
+    )
     fn_metadata: FuncMetadata = Field(
         description="Metadata about the function including a pydantic model for tool"
         " arguments"
@@ -45,6 +48,8 @@ def from_function(
         annotations: ToolAnnotations | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
+        from pydantic import TypeAdapter
+
         from mcp.server.fastmcp.server import Context
 
         func_name = name or fn.__name__
@@ -70,6 +75,32 @@ def from_function(
         )
         parameters = func_arg_metadata.arg_model.model_json_schema()
 
+        # Generate output schema from return type annotation if possible
+        output_schema = None
+        sig = inspect.signature(fn)
+        if sig.return_annotation != inspect.Signature.empty:
+            try:
+                # Handle common return types that don't need schema
+                if sig.return_annotation is str:
+                    output_schema = {"type": "string"}
+                elif sig.return_annotation is int:
+                    output_schema = {"type": "integer"}
+                elif sig.return_annotation is float:
+                    output_schema = {"type": "number"}
+                elif sig.return_annotation is bool:
+                    output_schema = {"type": "boolean"}
+                elif sig.return_annotation is dict:
+                    output_schema = {"type": "object"}
+                elif sig.return_annotation is list:
+                    output_schema = {"type": "array"}
+                else:
+                    # Try to generate schema using TypeAdapter
+                    return_type_adapter = TypeAdapter(sig.return_annotation)
+                    output_schema = return_type_adapter.json_schema()
+            except Exception:
+                # If we can't generate a schema, we'll leave it as None
+                pass
+
         return cls(
             fn=fn,
             name=func_name,
@@ -79,6 +110,7 @@ def from_function(
             is_async=is_async,
             context_kwarg=context_kwarg,
             annotations=annotations,
+            output_schema=output_schema,
         )
 
     async def run(
@@ -92,9 +124,11 @@ async def run(
                 self.fn,
                 self.is_async,
                 arguments,
-                {self.context_kwarg: context}
-                if self.context_kwarg is not None
-                else None,
+                (
+                    {self.context_kwarg: context}
+                    if self.context_kwarg is not None
+                    else None
+                ),
             )
         except Exception as e:
             raise ToolError(f"Error executing tool {self.name}: {e}") from e

src/mcp/types.py

@@ -338,7 +338,7 @@ class ProgressNotificationParams(NotificationParams):
     """
     total: float | None = None
     """
-    Message related to progress. This should provide relevant human readable 
+    Message related to progress. This should provide relevant human readable
     progress information.
     """
     message: str | None = None
@@ -741,7 +741,7 @@ class ToolAnnotations(BaseModel):
 
     idempotentHint: bool | None = None
     """
-    If true, calling the tool repeatedly with the same arguments 
+    If true, calling the tool repeatedly with the same arguments
     will have no additional effect on the its environment.
     (This property is meaningful only when `readOnlyHint == false`)
     Default: false
@@ -767,6 +767,8 @@ class Tool(BaseModel):
     """A human-readable description of the tool."""
     inputSchema: dict[str, Any]
     """A JSON Schema object defining the expected parameters for the tool."""
+    outputSchema: dict[str, Any] | None = None
+    """A JSON Schema object defining the expected output format of the tool."""
     annotations: ToolAnnotations | None = None
     """Optional additional tool information."""
     model_config = ConfigDict(extra="allow")