Update docs

2026-08-21 04:54:17 +02:00 · 2025-06-27 22:38:55 -04:00 · 2025-06-27 22:38:55 -04:00 · c412a63d4e
commit c412a63d4e
parent 5520102821
7 changed files with 575 additions and 46 deletions
--- a/docs/clients/tools.mdx
+++ b/docs/clients/tools.mdx
@ -37,10 +37,13 @@ Execute a tool using `call_tool()` with the tool name and arguments:
 async with client:
    # Simple tool call
    result = await client.call_tool("add", {"a": 5, "b": 3})
-    # result -> list[mcp.types.TextContent | mcp.types.ImageContent | ...]
+    # result -> CallToolResult with structured and unstructured data
    
-    # Access the result content
-    print(result[0].text)  # Assuming TextContent, e.g., '8'
+    # Access structured data (automatically deserialized)
+    print(result.data)  # 8 (int) or {"result": 8} for primitive types
+    
+    # Access traditional content blocks  
+    print(result.content[0].text)  # "8" (TextContent)
 ```

 ### Advanced Execution Options
@ -72,21 +75,97 @@ async with client:

 ## Handling Results

-Tool execution returns a list of content objects. The most common types are:
+<VersionBadge version="2.10.0" />

- **`TextContent`**: Text-based results with a `.text` attribute
- **`ImageContent`**: Image data with image-specific attributes
- **`BlobContent`**: Binary data content
+Tool execution returns a `CallToolResult` object with both structured and traditional content. FastMCP's standout feature is the `.data` property, which doesn't just provide raw JSON but actually hydrates complete Python objects including complex types like datetimes, UUIDs, and custom classes.
+
+### CallToolResult Properties
+
+<Card icon="code" title="CallToolResult Properties">
+<ResponseField name=".data" type="Any">
+  **FastMCP exclusive**: Fully hydrated Python objects with complex type support (datetimes, UUIDs, custom classes). Goes beyond JSON to provide complete object reconstruction from output schemas.
+</ResponseField>
+
+<ResponseField name=".content" type="list[mcp.types.ContentBlock]">
+  Standard MCP content blocks (`TextContent`, `ImageContent`, `AudioContent`, etc.) available from all MCP servers.
+</ResponseField>
+
+<ResponseField name=".structured_content" type="dict[str, Any] | None">
+  Standard MCP structured JSON data as sent by the server, available from all MCP servers that support structured outputs.
+</ResponseField>
+
+<ResponseField name=".is_error" type="bool">
+  Boolean indicating if the tool execution failed.
+</ResponseField>
+</Card>
+
+### Structured Data Access
+
+FastMCP's `.data` property provides fully hydrated Python objects, not just JSON dictionaries. This includes complex type reconstruction:

 ```python
+from datetime import datetime
+from uuid import UUID
+
 async with client:
    result = await client.call_tool("get_weather", {"city": "London"})
    
-    for content in result:
-        if hasattr(content, 'text'):
-            print(f"Text result: {content.text}")
-        elif hasattr(content, 'data'):
-            print(f"Binary data: {len(content.data)} bytes")
+    # FastMCP reconstructs complete Python objects from the server's output schema
+    weather = result.data  # Server-defined WeatherReport object
+    print(f"Temperature: {weather.temperature}°C at {weather.timestamp}")
+    print(f"Station: {weather.station_id}")
+    print(f"Humidity: {weather.humidity}%")
+    
+    # The timestamp is a real datetime object, not a string!
+    assert isinstance(weather.timestamp, datetime)
+    assert isinstance(weather.station_id, UUID)
+    
+    # Compare with raw structured JSON (standard MCP)
+    print(f"Raw JSON: {result.structured_content}")
+    # {"temperature": 20, "timestamp": "2024-01-15T14:30:00Z", "station_id": "123e4567-..."}
+    
+    # Traditional content blocks (standard MCP)  
+    print(f"Text content: {result.content[0].text}")
+```
+
+### Fallback Behavior
+
+For tools without output schemas or when deserialization fails, `.data` will be `None`:
+
+```python
+async with client:
+    result = await client.call_tool("legacy_tool", {"param": "value"})
+    
+    if result.data is not None:
+        # Structured output available and successfully deserialized
+        print(f"Structured: {result.data}")
+    else:
+        # No structured output or deserialization failed - use content blocks
+        for content in result.content:
+            if hasattr(content, 'text'):
+                print(f"Text result: {content.text}")
+            elif hasattr(content, 'data'):
+                print(f"Binary data: {len(content.data)} bytes")
+```
+
+### Primitive Type Unwrapping
+
+<Tip>
+FastMCP servers automatically wrap non-object results (like `int`, `str`, `bool`) in a `{"result": value}` structure to create valid structured outputs. FastMCP clients understand this convention and automatically unwrap the value in `.data` for convenience, so you get the original primitive value instead of a wrapper object.
+</Tip>
+
+```python
+async with client:
+    result = await client.call_tool("calculate_sum", {"a": 5, "b": 3})
+    
+    # FastMCP client automatically unwraps for convenience
+    print(result.data)  # 8 (int) - the original value
+    
+    # Raw structured content shows the server-side wrapping
+    print(result.structured_content)  # {"result": 8}
+    
+    # Other MCP clients would need to manually access ["result"]
+    # value = result.structured_content["result"]  # Not needed with FastMCP!
 ```

 ## Error Handling
@ -101,14 +180,32 @@ from fastmcp.exceptions import ToolError
 async with client:
    try:
        result = await client.call_tool("potentially_failing_tool", {"param": "value"})
-        print("Tool succeeded:", result)
+        print("Tool succeeded:", result.data)
    except ToolError as e:
        print(f"Tool failed: {e}")
 ```

 ### Manual Error Checking

-For more granular control, use `call_tool_mcp()` which returns the raw MCP protocol object with an `isError` flag:
+You can disable automatic error raising and manually check the result:
+
+```python
+async with client:
+    result = await client.call_tool(
+        "potentially_failing_tool", 
+        {"param": "value"}, 
+        raise_on_error=False
+    )
+    
+    if result.is_error:
+        print(f"Tool failed: {result.content[0].text}")
+    else:
+        print(f"Tool succeeded: {result.data}")
+```
+
+### Raw MCP Protocol Access
+
+For complete control, use `call_tool_mcp()` which returns the raw MCP protocol object:

 ```python
 async with client:
@ -119,6 +216,7 @@ async with client:
        print(f"Tool failed: {result.content}")
    else:
        print(f"Tool succeeded: {result.content}")
+        # Note: No automatic deserialization with call_tool_mcp()
 ```

 ## Argument Handling
--- a/docs/patterns/tool-transformation.mdx
+++ b/docs/patterns/tool-transformation.mdx
@ -89,6 +89,7 @@ The `Tool.from_tool()` class method is the primary way to create a transformed t
 - `description`: An optional description for the new tool.
 - `transform_args`: A dictionary of `ArgTransform` objects, one for each argument you want to modify.
 - `transform_fn`: An optional function that will be called instead of the parent tool's logic.
+- `output_schema`: Control output schema and structured outputs (see [Output Schema Control](#output-schema-control)).
 - `tags`: An optional set of tags for the new tool.
 - `annotations`: An optional set of `ToolAnnotations` for the new tool.
 - `serializer`: An optional function that will be called to serialize the result of the new tool.
@ -439,7 +440,44 @@ mcp.add_tool(new_tool)

 <Tip>
 In the above example, `**kwargs` receives the renamed argument `b`, not the original argument `y`. It is therefore recommended to use with `forward()`, not `forward_raw()`.
-</Tip> 
+</Tip>
+
+## Output Schema Control
+
+<VersionBadge version="2.10.0" />
+
+Transformed tools inherit output schemas from their parent by default, but you can control this behavior:
+
+**Inherit from Parent (Default)**
+```python
+Tool.from_tool(parent_tool, name="renamed_tool")
+```
+The transformed tool automatically uses the parent tool's output schema and structured output behavior.
+
+**Custom Output Schema**
+```python
+Tool.from_tool(parent_tool, output_schema={
+    "type": "object", 
+    "properties": {"status": {"type": "string"}}
+})
+```
+Provide your own schema that differs from the parent. The tool must return data matching this schema.
+
+**Remove Output Schema**
+```python
+Tool.from_tool(parent_tool, output_schema=False)
+```
+Removes the output schema declaration. Automatic structured content still works for object-like returns (dict, dataclass, Pydantic models) but primitive types won't be structured.
+
+**Full Control with Transform Functions**
+```python
+async def custom_output(**kwargs) -> ToolResult:
+    result = await forward(**kwargs)
+    return ToolResult(content=[...], structured_content={...})
+
+Tool.from_tool(parent_tool, transform_fn=custom_output)
+```
+Use a transform function returning `ToolResult` for complete control over both content blocks and structured outputs.

 ## Common Patterns

--- a/docs/servers/tools.mdx
+++ b/docs/servers/tools.mdx
@ -288,28 +288,100 @@ Use `async def` when your tool needs to perform operations that might wait for e

 ### Return Values

-#### Output Conversion

-FastMCP automatically converts the value returned by your function into the appropriate MCP content format for the client:
+FastMCP tools can return data in two complementary formats: **traditional content blocks** (like text and images) and **structured outputs** (machine-readable JSON). When you add return type annotations, FastMCP automatically generates **output schemas** to validate the structured data and enables clients to deserialize results back to Python objects.

- **`str`**: Sent as `TextContent`.
- **`dict`, `list`, Pydantic `BaseModel`**: Serialized to a JSON string and sent as `TextContent`.
- **`bytes`**: Base64 encoded and sent as `BlobResourceContents` (often within an `EmbeddedResource`).
- **`fastmcp.utilities.types.Image`**: A helper class for easily returning image data. Sent as `ImageContent`.
- **`fastmcp.utilities.types.Audio`**: A helper class for easily returning audio data. Sent as `AudioContent`.
- **`fastmcp.utilities.types.File`**: A helper class for easily returning binary data as base64-encoded content. Sent as `EmbeddedResource`.
- **A list of any of the above**: Automatically converts each item appropriately.
- **`None`**: Results in an empty response (no content is sent back to the client).
+Understanding how these three concepts work together:

-FastMCP will attempt to serialize other types to a string if possible.
+- **Return Values**: What your Python function returns (determines both content blocks and structured data)
+- **Structured Outputs**: JSON data sent alongside traditional content for machine processing  
+- **Output Schemas**: JSON Schema declarations that describe and validate the structured output format

-#### Output Schemas
+The following sections explain each concept in detail.
+
+#### Content Blocks
+
+FastMCP automatically converts tool return values into appropriate MCP content blocks:
+
+- **`str`**: Sent as `TextContent`
+- **`bytes`**: Base64 encoded and sent as `BlobResourceContents` (within an `EmbeddedResource`)
+- **`fastmcp.utilities.types.Image`**: Sent as `ImageContent`
+- **`fastmcp.utilities.types.Audio`**: Sent as `AudioContent`
+- **`fastmcp.utilities.types.File`**: Sent as base64-encoded `EmbeddedResource`
+- **A list of any of the above**: Converts each item appropriately
+- **`None`**: Results in an empty response
+
+#### Structured Output

 <VersionBadge version="2.10.0" />

-FastMCP will automatically generate MCP [output schemas](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) for your tools based on their return type annotations. This helps MCP clients understand what type of data to expect from your tool, enabling better validation and type safety.
+The 6/18/2025 MCP spec update [introduced](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content) structured content, which is a new way to return data from tools. Structured content is a JSON object that is sent alongside traditional content. FastMCP automatically creates structured outputs alongside traditional content when your tool returns data that has a JSON object representation. This provides machine-readable JSON data that clients can deserialize back to Python objects.

-When you add a return type annotation to your tool function, FastMCP will generate a JSON schema describing the expected output format and include it in the tool definition sent to MCP clients.
+**Automatic Structured Content Rules:**
+- **Object-like results** (`dict`, Pydantic models, dataclasses) → Always become structured content (even without output schema)  
+- **Non-object results** (`int`, `str`, `list`) → Only become structured content if there's an output schema to validate/serialize them
+- **All results** → Always become traditional content blocks for backward compatibility
+
+<Note>
+This automatic behavior enables clients to receive machine-readable data alongside human-readable content without requiring explicit output schemas for object-like returns.
+</Note>
+
+##### Object-like Results (Automatic Structured Content)
+
+<CodeGroup>
+```python Dict Return (No Schema Needed)
+@mcp.tool
+def get_user_data(user_id: str) -> dict:
+    """Get user data without type annotation."""
+    return {"name": "Alice", "age": 30, "active": True}
+```
+
+```json Traditional Content
+"{\n  \"name\": \"Alice\",\n  \"age\": 30,\n  \"active\": true\n}"
+```
+
+```json Structured Content (Automatic)
+{
+  "name": "Alice", 
+  "age": 30,
+  "active": true
+}
+```
+</CodeGroup>
+
+##### Non-object Results (Schema Required)
+
+<CodeGroup>
+```python Integer Return (No Schema)
+@mcp.tool  
+def calculate_sum(a: int, b: int):
+    """Calculate sum without return annotation."""
+    return a + b  # Returns 8
+```
+
+```json Traditional Content Only
+"8"
+```
+
+```python Integer Return (With Schema)
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Calculate sum with return annotation."""  
+    return a + b  # Returns 8
+```
+
+```json Traditional Content
+"8"
+```
+
+```json Structured Content (From Schema)
+{
+  "result": 8
+}
+```
+</CodeGroup>
+
+##### Complex Type Example

 <CodeGroup>
 ```python Tool Definition
@ -334,19 +406,110 @@ def get_user_profile(user_id: str) -> Person:
 {
  "properties": {
    "name": {"title": "Name", "type": "string"},
-    "age": {"title": "Age", "type": "integer"},
+    "age": {"title": "Age", "type": "integer"}, 
    "email": {"title": "Email", "type": "string"}
  },
  "required": ["name", "age", "email"],
  "title": "Person",
  "type": "object"
 }
- ```
+```
+
+```json Structured Output
+{
+  "name": "Alice",
+  "age": 30,
+  "email": "alice@example.com"
+}
+```
 </CodeGroup>
-The output schema is automatically generated for most common types including basic types, collections, union types, Pydantic models, TypedDict structures, and dataclasses. For FastMCP's special types (`Image`, `Audio`, `File`), the output schema reflects their MCP equivalents rather than the FastMCP wrapper types.
+
+#### Output Schemas
+
+<VersionBadge version="2.10.0" />
+
+The 6/18/2025 MCP spec update [introduced](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) output schemas, which are a new way to describe the expected output format of a tool. When an output schema is provided, the tool *must* return structured output that matches the schema.
+
+When you add return type annotations to your functions, FastMCP automatically generates JSON schemas that describe the expected output format. These schemas help MCP clients understand and validate the structured data they receive.
+
+##### Primitive Type Wrapping
+
+For primitive return types (like `int`, `str`, `bool`), FastMCP automatically wraps the result under a `"result"` key to create valid structured output:
+
+<CodeGroup>
+```python Primitive Return Type
+@mcp.tool
+def calculate_sum(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+```
+
+```json Generated Schema (Wrapped)
+{
+  "type": "object",
+  "properties": {
+    "result": {"type": "integer"}
+  },
+  "x-fastmcp-wrap-result": true
+}
+```
+
+```json Structured Output
+{
+  "result": 8
+}
+```
+</CodeGroup>
+
+##### Manual Schema Control
+
+You can override the automatically generated schema by providing a custom `output_schema`:
+
+```python
+@mcp.tool(output_schema={
+    "type": "object", 
+    "properties": {
+        "data": {"type": "string"},
+        "metadata": {"type": "object"}
+    }
+})
+def custom_schema_tool() -> dict:
+    """Tool with custom output schema."""
+    return {"data": "Hello", "metadata": {"version": "1.0"}}
+```
+
+Schema generation works for most common types including basic types, collections, union types, Pydantic models, TypedDict structures, and dataclasses.
+
+<Warning>
+**Important Constraints**: 
+- Output schemas must be object types (`"type": "object"`)
+- If you provide an output schema, your tool **must** return structured output that matches it
+- However, you can provide structured output without an output schema (using `ToolResult`)
+</Warning>
+
+#### Full Control with ToolResult
+
+For complete control over both traditional content and structured output, return a `ToolResult` object:
+
+```python
+from fastmcp.tools.tool import ToolResult
+
+@mcp.tool
+def advanced_tool() -> ToolResult:
+    """Tool with full control over output."""
+    return ToolResult(
+        content=[TextContent(text="Human-readable summary")],
+        structured_content={"data": "value", "count": 42}
+    )
+```
+
+When returning `ToolResult`:
+- You control exactly what content and structured data is sent
+- Output schemas are optional - structured content can be provided without a schema
+- Clients receive both traditional content blocks and structured data

 <Note>
-If your return type annotation cannot be converted to a JSON schema (e.g., complex custom classes without Pydantic support), the output schema will be omitted from the tool definition. The tool will still function normally, but clients won't receive type information about the expected output.
+If your return type annotation cannot be converted to a JSON schema (e.g., complex custom classes without Pydantic support), the output schema will be omitted but the tool will still function normally with traditional content.
 </Note>

 ### Error Handling