fastmcp 2.9.1__tar.gz → 2.10.0__tar.gz

fastmcp-2.10.0/.ccignore

@@ -0,0 +1,7 @@
+.pre-commit-config.yaml
+.github/
+docs/changelog.mdx
+docs/python-sdk/
+examples/
+src/fastmcp/contrib/
+tests/contrib/

{fastmcp-2.9.1 → fastmcp-2.10.0}/CLAUDE.md

@@ -1,5 +1,14 @@
 # FastMCP Development Guidelines
 
+## Git
+
+This project uses `pre-commit` to run checks on all commits. If your commit doesn't pass the checks, it will not be created. Do not attempt to amend commits to pass checks.
+
+## Documentation
+
+- Documentation uses the Mintlify framework
+- Files must be present in docs.json to be included in the documentation
+
 ## Testing and Investigation
 
 ### In-Memory Transport - Always Preferred
@@ -34,4 +43,4 @@ async with Client(transport=StreamableHttpTransport(server_url)) as client:
 - You must always run pre-commit if you open a PR, because it is run as part of a required check.
 - When opening PRs, apply labels appropriately for bugs/breaking changes/enhancements/features. Generally, improvements are enhancements (not features) unless told otherwise.
 - NEVER modify files in docs/python-sdk/**, as they are auto-generated.
-- Use # type: ignore[attr-defined] in unit tests when accessing an MCP result of indeterminate type instead of asserting its type
+- Use # type: ignore[attr-defined] in unit tests when accessing an MCP result of indeterminate type instead of asserting its type

{fastmcp-2.9.1 → fastmcp-2.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.9.1
+Version: 2.10.0
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -20,8 +20,9 @@ Requires-Python: >=3.10
 Requires-Dist: authlib>=1.5.2
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp<2.0.0,>=1.9.4
+Requires-Dist: mcp>=1.10.0
 Requires-Dist: openapi-pydantic>=0.5.1
+Requires-Dist: pydantic[email]>=2.11.7
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: typer>=0.15.2

{fastmcp-2.9.1 → fastmcp-2.10.0}/docs/clients/client.mdx

@@ -109,7 +109,7 @@ config = {
         },
         "local_server": {
             # Local stdio server
-            "transport": "stdio"
+            "transport": "stdio",
             "command": "python",
             "args": ["./server.py", "--verbose"],
             "env": {"DEBUG": "true"},

fastmcp-2.10.0/docs/clients/elicitation.mdx

@@ -0,0 +1,126 @@
+---
+title: User Elicitation
+sidebarTitle: Elicitation
+description: Handle server-initiated user input requests with structured schemas.
+icon: message-question
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx";
+
+<VersionBadge version="2.10.0" />
+
+## What is Elicitation?
+
+Elicitation allows MCP servers to request structured input from users during tool execution. Instead of requiring all inputs upfront, servers can interactively ask users for information as needed - like prompting for missing parameters, requesting clarification, or gathering additional context.
+
+For example, a file management tool might ask "Which directory should I create?" or a data analysis tool might request "What date range should I analyze?"
+
+## How FastMCP Makes Elicitation Easy
+
+FastMCP's client provides a helpful abstraction layer that:
+
+- **Converts JSON schemas to Python types**: The raw MCP protocol uses JSON schemas, but FastMCP automatically converts these to Python dataclasses
+- **Provides structured constructors**: Instead of manually building dictionaries that match the schema, you get dataclass constructors that ensure correct structure
+- **Handles type conversion**: FastMCP takes care of converting between JSON representations and Python objects
+- **Runtime introspection**: You can inspect the generated dataclass fields to understand the expected structure
+
+When you implement an elicitation handler, FastMCP gives you a dataclass type that matches the server's schema, making it easy to create properly structured responses without having to manually parse JSON schemas.
+
+## Elicitation Handler
+
+Provide an `elicitation_handler` function when creating the client. FastMCP automatically converts the server's JSON schema into a Python dataclass type, making it easy to construct the response:
+
+```python
+from fastmcp import Client
+from fastmcp.client.elicitation import ElicitResult
+
+async def elicitation_handler(message: str, response_type: type, params, context):
+    # Present the message to the user and collect input
+    user_input = input(f"{message}: ")
+    
+    # Create response using the provided dataclass type
+    # FastMCP converted the JSON schema to this Python type for you
+    response_data = response_type(value=user_input)
+    
+    # You can return data directly - FastMCP will implicitly accept the elicitation
+    return response_data
+    
+    # Or explicitly return an ElicitResult for more control
+    # return ElicitResult(action="accept", content=response_data)
+
+client = Client(
+    "my_mcp_server.py",
+    elicitation_handler=elicitation_handler,
+)
+```
+
+### Handler Parameters
+
+The elicitation handler receives four parameters:
+
+<Card icon="code" title="Elicitation Handler Parameters">
+<ResponseField name="message" type="str">
+  The prompt message to display to the user
+</ResponseField>
+
+<ResponseField name="response_type" type="type">
+  A Python dataclass type that FastMCP created from the server's JSON schema. Use this to construct your response with proper typing and IDE support. If the server requests an empty object (indicating no response), this will be `None`.
+</ResponseField>
+
+<ResponseField name="params" type="ElicitRequestParams">
+  The original MCP elicitation request parameters, including the raw JSON schema in `params.requestedSchema` if you need it
+</ResponseField>
+
+<ResponseField name="context" type="RequestContext">
+  Request context containing metadata about the elicitation request
+</ResponseField>
+</Card>
+
+### Response Actions
+
+The handler can return data directly (which implicitly accepts the elicitation) or an `ElicitResult` object for more control over the response action:
+
+<Card icon="code" title="ElicitResult Structure">
+<ResponseField name="action" type="Literal['accept', 'decline', 'cancel']">
+  How the user responded to the elicitation request
+</ResponseField>
+
+<ResponseField name="content" type="dataclass instance | dict | None">
+  The user's input data (required for "accept", omitted for "decline"/"cancel")
+</ResponseField>
+</Card>
+
+**Action Types:**
+- **`accept`**: User provided valid input - include their data in the `content` field
+- **`decline`**: User chose not to provide the requested information - omit `content`  
+- **`cancel`**: User cancelled the entire operation - omit `content`
+
+## Basic Example
+
+```python
+from fastmcp import Client
+from fastmcp.client.elicitation import ElicitResult
+
+async def basic_elicitation_handler(message: str, response_type: type, params, context):
+    print(f"Server asks: {message}")
+    
+    # Simple text input for demonstration
+    user_response = input("Your response: ")
+    
+    if not user_response:
+        # For non-acceptance, use ElicitResult explicitly
+        return ElicitResult(action="decline")
+    
+    # Use the response_type dataclass to create a properly structured response
+    # FastMCP handles the conversion from JSON schema to Python type
+    # Return data directly - FastMCP will implicitly accept the elicitation
+    return response_type(value=user_response)
+
+client = Client(
+    "my_mcp_server.py", 
+    elicitation_handler=basic_elicitation_handler
+)
+```
+
+

{fastmcp-2.9.1 → fastmcp-2.10.0}/docs/clients/messages.mdx

@@ -7,7 +7,7 @@ icon: envelope
 
 import { VersionBadge } from "/snippets/version-badge.mdx";
 
-<VersionBadge version="2.9.0" />
+<VersionBadge version="2.9.1" />
 
 MCP clients can receive various types of messages from servers, including requests that need responses and notifications that don't. The message handler provides a unified way to process all these messages.
 

fastmcp-2.10.0/docs/clients/tools.mdx

@@ -0,0 +1,241 @@
+---
+title: Tool Operations
+sidebarTitle: Tools
+description: Discover and execute server-side tools with the FastMCP client.
+icon: wrench
+---
+
+import { VersionBadge } from '/snippets/version-badge.mdx'
+
+<VersionBadge version="2.0.0" />
+
+Tools are executable functions exposed by MCP servers. The FastMCP client provides methods to discover available tools and execute them with arguments.
+
+## Discovering Tools
+
+Use `list_tools()` to retrieve all tools available on the server:
+
+```python
+async with client:
+    tools = await client.list_tools()
+    # tools -> list[mcp.types.Tool]
+    
+    for tool in tools:
+        print(f"Tool: {tool.name}")
+        print(f"Description: {tool.description}")
+        if tool.inputSchema:
+            print(f"Parameters: {tool.inputSchema}")
+```
+
+## Executing Tools
+
+### Basic Execution
+
+Execute a tool using `call_tool()` with the tool name and arguments:
+
+```python
+async with client:
+    # Simple tool call
+    result = await client.call_tool("add", {"a": 5, "b": 3})
+    # result -> CallToolResult with structured and unstructured data
+    
+    # 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
+
+The `call_tool()` method supports additional parameters for timeout control and progress monitoring:
+
+```python
+async with client:
+    # With timeout (aborts if execution takes longer than 2 seconds)
+    result = await client.call_tool(
+        "long_running_task", 
+        {"param": "value"}, 
+        timeout=2.0
+    )
+    
+    # With progress handler (to track execution progress)
+    result = await client.call_tool(
+        "long_running_task",
+        {"param": "value"},
+        progress_handler=my_progress_handler
+    )
+```
+
+**Parameters:**
+- `name`: The tool name (string)
+- `arguments`: Dictionary of arguments to pass to the tool (optional)
+- `timeout`: Maximum execution time in seconds (optional, overrides client-level timeout)
+- `progress_handler`: Progress callback function (optional, overrides client-level handler)
+
+## Handling Results
+
+<VersionBadge version="2.10.0" />
+
+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"})
+    
+    # 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
+
+### Exception-Based Error Handling
+
+By default, `call_tool()` raises a `ToolError` if the tool execution fails:
+
+```python
+from fastmcp.exceptions import ToolError
+
+async with client:
+    try:
+        result = await client.call_tool("potentially_failing_tool", {"param": "value"})
+        print("Tool succeeded:", result.data)
+    except ToolError as e:
+        print(f"Tool failed: {e}")
+```
+
+### Manual Error Checking
+
+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:
+    result = await client.call_tool_mcp("potentially_failing_tool", {"param": "value"})
+    # result -> mcp.types.CallToolResult
+    
+    if result.isError:
+        print(f"Tool failed: {result.content}")
+    else:
+        print(f"Tool succeeded: {result.content}")
+        # Note: No automatic deserialization with call_tool_mcp()
+```
+
+## Argument Handling
+
+Arguments are passed as a dictionary to the tool:
+
+```python
+async with client:
+    # Simple arguments
+    result = await client.call_tool("greet", {"name": "World"})
+    
+    # Complex arguments
+    result = await client.call_tool("process_data", {
+        "config": {"format": "json", "validate": True},
+        "items": [1, 2, 3, 4, 5],
+        "metadata": {"source": "api", "version": "1.0"}
+    })
+```
+
+<Tip>
+For multi-server clients, tool names are automatically prefixed with the server name (e.g., `weather_get_forecast` for a tool named `get_forecast` on the `weather` server).
+</Tip>

{fastmcp-2.9.1 → fastmcp-2.10.0}/docs/docs.json

@@ -12,7 +12,7 @@
     "decoration": "windows"
   },
   "banner": {
-    "content": "[FastMCP Cloud](https://fastmcp.link/x0Kyhy2) is coming!"
+    "content": "FastMCP Cloud is here! [Join the beta](https://fastmcp.link/x0Kyhy2)."
   },
   "colors": {
     "dark": "#f72585",
@@ -69,8 +69,18 @@
                     "pages": [
                       "servers/tools",
                       "servers/resources",
-                      "servers/prompts",
-                      "servers/context"
+                      "servers/prompts"
+                    ]
+                  },
+                  {
+                    "group": "Advanced Features",
+                    "icon": "stars",
+                    "pages": [
+                      "servers/context",
+                      "servers/elicitation",
+                      "servers/logging",
+                      "servers/progress",
+                      "servers/sampling"
                     ]
                   },
                   {
@@ -106,6 +116,7 @@
                     "group": "Advanced Features",
                     "icon": "stars",
                     "pages": [
+                      "clients/elicitation",
                       "clients/logging",
                       "clients/progress",
                       "clients/sampling",
@@ -130,6 +141,7 @@
                   "integrations/claude-desktop",
                   "integrations/gemini",
                   "integrations/openai",
+                  "integrations/eunomia-authorization",
                   "integrations/contrib"
                 ]
               },

{fastmcp-2.9.1 → fastmcp-2.10.0}/docs/integrations/chatgpt.mdx

@@ -13,7 +13,7 @@ MCP integration with ChatGPT is currently limited to **Deep Research** functiona
 </Note>
 
 <Tip>
-OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Check out their [sample MCP server](https://github.com/openai/mcp-server-sample) which demonstrates FastMCP in action.
+OpenAI's official MCP documentation and examples are built with **FastMCP v2**! Check out their [simple Deep Research-style MCP server example](https://github.com/openai/sample-deep-research-mcp) for a quick reference similar to the one in this document, or their [more complete Deep Research example](https://github.com/openai/openai-cookbook/tree/main/examples/deep_research_api/how_to_build_a_deep_research_mcp_server) from the OpenAI Cookbook, which includes vector search and more.
 </Tip>
 
 ## Deep Research
@@ -42,7 +42,7 @@ A Deep Research-compatible server must implement these two required tools:
 
 The `search` tool should take a query (of any kind!) and return IDs. The `fetch` tool should take an ID and return the record.
 
-Here's a reference server implementation you can adapt (see also [OpenAI's sample server](https://github.com/openai/mcp-server-sample) for comparison):
+Here's a reference server implementation you can adapt (see also [OpenAI's sample server](https://github.com/openai/sample-deep-research-mcp) for comparison):
 
 ```python server.py [expandable]
 import json

fastmcp-2.10.0/docs/integrations/eunomia-authorization.mdx

@@ -0,0 +1,108 @@
+---
+title: Eunomia Authorization + FastMCP
+sidebarTitle: Eunomia Authorization
+description: Add policy-based authorization to your FastMCP servers
+icon: layer-group
+tag: NEW
+---
+
+Add **policy-based authorization** to your FastMCP servers with minimal code changes using Eunomia authorization middleware.
+
+Control which actions MCP clients can perform on your server by restricting how the agent can access resources, tools and prompts by using JSON-based policies, while obtaining a comprehensive audit log of all access attempts and violations.
+
+## Eunomia Authorization Middleware
+
+The middleware intercepts all MCP requests to your server and automatically maps MCP methods to authorization checks.
+
+```mermaid
+sequenceDiagram
+    participant MCPClient as MCP Client
+    participant EunomiaMiddleware as Eunomia Middleware
+    participant MCPServer as FastMCP Server
+    participant EunomiaServer as Eunomia Server
+
+    MCPClient->>EunomiaMiddleware: MCP Request
+    Note over MCPClient, EunomiaMiddleware: Middleware intercepts request to server
+    EunomiaMiddleware->>EunomiaServer: Authorization Check
+    EunomiaServer->>EunomiaMiddleware: Authorization Decision (allow/deny)
+    EunomiaMiddleware-->>MCPClient: MCP Unauthorized Error (if denied)
+    EunomiaMiddleware->>MCPServer: MCP Request (if allowed)
+    MCPServer-->>MCPClient: MCP Response (if allowed)
+```
+
+<Note>
+Eunomia is an AI-specific standalone authorization server that handles policy decisions. You must have an Eunomia server running alongside your FastMCP server for the middleware to function.
+
+Run it in the background with Docker:
+
+```bash
+docker run -d -p 8000:8000 ttommitt/eunomia-server:latest
+```
+
+</Note>
+
+### Create a Server with Authorization
+
+First, install the `eunomia-mcp` package:
+
+```bash
+pip install eunomia-mcp
+```
+
+Then create a FastMCP server and add the Eunomia middleware with a few lines of code:
+
+```python server.py
+from fastmcp import FastMCP
+from eunomia_mcp import create_eunomia_middleware
+
+mcp = FastMCP("Secure FastMCP Server 🔒")
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+middleware = [create_eunomia_middleware()]
+app = mcp.http_app(middleware=middleware)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8080)
+```
+
+### Configure Access Policies
+
+Use the `eunomia-mcp` CLI in your terminal to manage your authorization policies:
+
+```bash
+# Create a default policy configuration file
+eunomia-mcp init
+```
+
+This creates a policy file you can customize to control access to your MCP tools and resources.
+
+```bash
+# Once ready, validate your policy
+eunomia-mcp validate mcp_policies.json
+
+# And push it to the Eunomia server
+eunomia-mcp push mcp_policies.json
+```
+
+### Run the Server
+
+Start your FastMCP server normally:
+
+```bash
+python server.py
+```
+
+The middleware will now intercept all MCP requests and check them against your policies. Requests include agent identification through headers like `X-Agent-ID`, `X-User-ID`, or `Authorization` and an automatic mapping of MCP methods to authorization resources and actions.
+
+<Tip>
+  For detailed policy configuration, custom authentication, and advanced
+  deployment patterns, visit the [Eunomia MCP Middleware
+  repository][eunomia-github].
+</Tip>
+
+[eunomia-github]: https://github.com/whataboutyou-ai/eunomia/tree/main/pkgs/extensions/mcp

{fastmcp-2.9.1 → fastmcp-2.10.0}/docs/patterns/cli.mdx

@@ -46,6 +46,7 @@ This command runs the server directly in your current Python environment. You ar
 | Host | `--host` | Host to bind to when using http transport (default: 127.0.0.1) |
 | Port | `--port`, `-p` | Port to bind to when using http transport (default: 8000) |
 | Log Level | `--log-level`, `-l` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
+| No Banner | `--no-banner` | Disable the startup banner display |
 
 
 #### Server Specification

{fastmcp-2.9.1 → fastmcp-2.10.0}/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