rebase on lowlevel schema validation, address comments

Author: bhosmer-ant

README.md

@@ -252,7 +252,31 @@ async def fetch_weather(city: str) -> str:
 
 #### Structured Output
 
-Tools can return structured data with automatic validation using the `structured_output=True` parameter. This ensures your tools return well-typed, validated data that clients can easily process:
+Tools will return structured results by default, if their return type
+annotation is compatible. Otherwise, they will return unstructured results. 
+
+Structured output supports these return types:
+- Pydantic models (BaseModel subclasses)
+- TypedDicts
+- Dataclasses
+- NamedTuples
+- `dict[str, T]`
+- Primitive types (str, int, float, bool) - wrapped in `{"result": value}`
+- Generic types (list, tuple, set) - wrapped in `{"result": value}`
+- Union types and Optional - wrapped in `{"result": value}`
+
+Structured results are automatically validated against the output schema 
+generated from the annotation. This ensures the tool returns well-typed, 
+validated data that clients can easily process:
+
+**Note:** For backward compatibility, unstructured results are also
+returned. Unstructured results are provided strictly for compatibility 
+with previous versions of FastMCP.
+
+**Note:** In cases where a tool function's return type annotation 
+causes the tool to be classified as structured _and this is undesirable_, 
+the  classification can be suppressed by passing `structured_output=False`
+to the `@tool` decorator.
 
 ```python
 from mcp.server.fastmcp import FastMCP
@@ -270,7 +294,7 @@ class WeatherData(BaseModel):
     wind_speed: float
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_weather(city: str) -> WeatherData:
     """Get structured weather data"""
     return WeatherData(
@@ -285,43 +309,34 @@ class LocationInfo(TypedDict):
     name: str
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_location(address: str) -> LocationInfo:
     """Get location coordinates"""
     return LocationInfo(latitude=51.5074, longitude=-0.1278, name="London, UK")
 
 
 # Using dict[str, Any] for flexible schemas
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_statistics(data_type: str) -> dict[str, float]:
     """Get various statistics"""
     return {"mean": 42.5, "median": 40.0, "std_dev": 5.2}
 
 
 # Lists and other types are wrapped automatically
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def list_cities() -> list[str]:
     """Get a list of cities"""
     return ["London", "Paris", "Tokyo"]
     # Returns: {"result": ["London", "Paris", "Tokyo"]}
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_temperature(city: str) -> float:
     """Get temperature as a simple float"""
     return 22.5
     # Returns: {"result": 22.5}
 ```
 
-Structured output supports:
-- Pydantic models (BaseModel subclasses) - used directly
-- TypedDict for dictionary structures - used directly
-- Dataclasses and NamedTuples - converted to dictionaries
-- `dict[str, T]` for flexible key-value pairs - used directly
-- Primitive types (str, int, float, bool) - wrapped in `{"result": value}`
-- Generic types (list, tuple, set) - wrapped in `{"result": value}`
-- Union types and Optional - wrapped in `{"result": value}`
-
 ### Prompts
 
 Prompts are reusable templates that help LLMs interact with your server effectively:

examples/fastmcp/weather_structured.py

@@ -33,7 +33,7 @@ class WeatherData(BaseModel):
     timestamp: datetime = Field(default_factory=datetime.now, description="Observation time")
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_weather(city: str) -> WeatherData:
     """Get current weather for a city with full structured data"""
     # In a real implementation, this would fetch from a weather API
@@ -49,14 +49,14 @@ class WeatherSummary(TypedDict):
     description: str
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_weather_summary(city: str) -> WeatherSummary:
     """Get a brief weather summary for a city"""
     return WeatherSummary(city=city, temp_c=22.5, description="Partly cloudy with light breeze")
 
 
 # Example 3: Using dict[str, Any] for flexible schemas
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_weather_metrics(cities: list[str]) -> dict[str, dict[str, float]]:
     """Get weather metrics for multiple cities
 
@@ -81,7 +81,7 @@ class WeatherAlert:
     valid_until: datetime
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_weather_alerts(region: str) -> list[WeatherAlert]:
     """Get active weather alerts for a region"""
     # In production, this would fetch real alerts
@@ -106,11 +106,11 @@ def get_weather_alerts(region: str) -> list[WeatherAlert]:
 
 
 # Example 5: Returning primitives with structured output
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_temperature(city: str, unit: str = "celsius") -> float:
     """Get just the temperature for a city
 
-    When returning primitives with structured_output=True,
+    When returning primitives as structured output,
     the result is wrapped in {"result": value}
     """
     base_temp = 22.5
@@ -138,7 +138,7 @@ class WeatherStats(BaseModel):
     precipitation_mm: float = Field(description="Total precipitation in millimeters")
 
 
-@mcp.tool(structured_output=True)
+@mcp.tool()
 def get_weather_stats(city: str, days: int = 7) -> WeatherStats:
     """Get weather statistics for the past N days"""
     return WeatherStats(

src/mcp/server/fastmcp/server.py

@@ -9,6 +9,7 @@
     AbstractAsyncContextManager,
     asynccontextmanager,
 )
+from itertools import chain
 from typing import Any, Generic, Literal
 
 import anyio
@@ -37,6 +38,7 @@
 from mcp.server.fastmcp.resources import FunctionResource, Resource, ResourceManager
 from mcp.server.fastmcp.tools import Tool, ToolManager
 from mcp.server.fastmcp.utilities.logging import configure_logging, get_logger
+from mcp.server.fastmcp.utilities.types import Image
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.lowlevel.server import LifespanResultT
 from mcp.server.lowlevel.server import Server as MCPServer
@@ -52,6 +54,7 @@
     AnyFunction,
     ContentBlock,
     GetPromptResult,
+    TextContent,
     ToolAnnotations,
 )
 from mcp.types import Prompt as MCPPrompt
@@ -232,7 +235,10 @@ def run(
     def _setup_handlers(self) -> None:
         """Set up core MCP protocol handlers."""
         self._mcp_server.list_tools()(self.list_tools)
-        self._mcp_server.call_tool()(self.call_tool)
+        # Note: we disable the lowlevel server's input validation.
+        # FastMCP does ad hoc conversion of incoming data before validating -
+        # for now we preserve this for backwards compatibility.
+        self._mcp_server.call_tool(validate_input=False)(self.call_tool)
         self._mcp_server.list_resources()(self.list_resources)
         self._mcp_server.read_resource()(self.read_resource)
         self._mcp_server.list_prompts()(self.list_prompts)
@@ -268,7 +274,7 @@ def get_context(self) -> Context[ServerSession, object, Request]:
     async def call_tool(self, name: str, arguments: dict[str, Any]) -> Sequence[ContentBlock] | dict[str, Any]:
         """Call a tool by name with arguments."""
         context = self.get_context()
-        return await self._tool_manager.call_tool_and_convert_result(name, arguments, context=context)
+        return await self._tool_manager.call_tool(name, arguments, context=context, convert_result=True)
 
     async def list_resources(self) -> list[MCPResource]:
         """List all available resources."""
@@ -318,7 +324,7 @@ def add_tool(
         title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
-        structured_output: bool = False,
+        structured_output: bool | None = None,
     ) -> None:
         """Add a tool to the server.
 
@@ -331,7 +337,10 @@ def add_tool(
             title: Optional human-readable title for the tool
             description: Optional description of what the tool does
             annotations: Optional ToolAnnotations providing additional tool information
-            structured_output: If True, validates the tool's output against its return type annotation
+            structured_output: Controls whether the tool's output is structured or unstructured
+                - If None, auto-detects based on the function's return type annotation
+                - If True, unconditionally creates a structured tool (return type annotation permitting)
+                - If False, unconditionally creates an unstructured tool
         """
         self._tool_manager.add_tool(
             fn,
@@ -348,7 +357,7 @@ def tool(
         title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
-        structured_output: bool = False,
+        structured_output: bool | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
 
@@ -361,7 +370,10 @@ def tool(
             title: Optional human-readable title for the tool
             description: Optional description of what the tool does
             annotations: Optional ToolAnnotations providing additional tool information
-            structured_output: If True, validates the tool's output against its return type annotation
+            structured_output: Controls whether the tool's output is structured or unstructured
+                - If None, auto-detects based on the function's return type annotation
+                - If True, unconditionally creates a structured tool (return type annotation permitting)
+                - If False, unconditionally creates an unstructured tool
 
         Example:
             @server.tool()
@@ -956,6 +968,28 @@ async def get_prompt(self, name: str, arguments: dict[str, Any] | None = None) -
             raise ValueError(str(e))
 
 
+def _convert_to_content(
+    result: Any,
+) -> Sequence[ContentBlock]:
+    """Convert a result to a sequence of content objects."""
+    if result is None:
+        return []
+
+    if isinstance(result, ContentBlock):
+        return [result]
+
+    if isinstance(result, Image):
+        return [result.to_image_content()]
+
+    if isinstance(result, list | tuple):
+        return list(chain.from_iterable(_convert_to_content(item) for item in result))  # type: ignore[reportUnknownVariableType]
+
+    if not isinstance(result, str):
+        result = pydantic_core.to_json(result, fallback=str, indent=2).decode()
+
+    return [TextContent(type="text", text=result)]
+
+
 class Context(BaseModel, Generic[ServerSessionT, LifespanContextT, RequestT]):
     """Context object providing access to MCP capabilities.
 

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

@@ -2,18 +2,15 @@
 
 import functools
 import inspect
-from collections.abc import Callable, Sequence
+from collections.abc import Callable
 from functools import cached_property
-from itertools import chain
 from typing import TYPE_CHECKING, Any, get_origin
 
-import pydantic_core
 from pydantic import BaseModel, Field
 
 from mcp.server.fastmcp.exceptions import ToolError
 from mcp.server.fastmcp.utilities.func_metadata import FuncMetadata, func_metadata
-from mcp.server.fastmcp.utilities.types import Image
-from mcp.types import ContentBlock, TextContent, ToolAnnotations
+from mcp.types import ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -38,10 +35,14 @@ class Tool(BaseModel):
 
     @cached_property
     def output_schema(self) -> dict[str, Any] | None:
-        if self.fn_metadata.output_model:
+        if self.fn_metadata.output_model is not None:
             return self.fn_metadata.output_model.model_json_schema()
         return None
 
+    @property
+    def is_structured(self) -> bool:
+        return self.fn_metadata.output_model is not None
+
     @classmethod
     def from_function(
         cls,
@@ -51,7 +52,7 @@ def from_function(
         description: str | None = None,
         context_kwarg: str | None = None,
         annotations: ToolAnnotations | None = None,
-        structured_output: bool = False,
+        structured_output: bool | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
         from mcp.server.fastmcp.server import Context
@@ -73,23 +74,20 @@ def from_function(
                     context_kwarg = param_name
                     break
 
-        fn_metadata = func_metadata(
+        func_arg_metadata = func_metadata(
             fn,
             skip_names=[context_kwarg] if context_kwarg is not None else [],
             structured_output=structured_output,
         )
-        parameters = fn_metadata.arg_model.model_json_schema()
-
-        if structured_output:
-            assert fn_metadata.output_model is not None
+        parameters = func_arg_metadata.arg_model.model_json_schema()
 
         return cls(
             fn=fn,
             name=func_name,
             title=title,
             description=func_doc,
             parameters=parameters,
-            fn_metadata=fn_metadata,
+            fn_metadata=func_arg_metadata,
             is_async=is_async,
             context_kwarg=context_kwarg,
             annotations=annotations,
@@ -99,41 +97,23 @@ async def run(
         self,
         arguments: dict[str, Any],
         context: Context[ServerSessionT, LifespanContextT, RequestT] | None = None,
+        convert_result: bool = False,
     ) -> Any:
         """Run the tool with arguments."""
         try:
-            return await self.fn_metadata.call_fn_with_arg_validation(
+            result = await self.fn_metadata.call_fn_with_arg_validation(
                 self.fn,
                 self.is_async,
                 arguments,
                 {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
-
-    def convert_result(self, result: Any) -> Sequence[ContentBlock] | dict[str, Any]:
-        """Validate tool result and convert to appropriate output format."""
-        output_model = self.fn_metadata.output_model
-        if output_model:
-            # This will raise a ToolError if validation fails
-            return self.fn_metadata.to_validated_dict(result)
-        else:
-            if result is None:
-                return []
 
-            if isinstance(result, ContentBlock):
-                return [result]
+            if convert_result:
+                result = self.fn_metadata.convert_result(result)
 
-            if isinstance(result, Image):
-                return [result.to_image_content()]
-
-            if isinstance(result, list | tuple):
-                return list(chain.from_iterable(self.convert_result(item) for item in result))  # type: ignore[reportUnknownVariableType]
-
-            if not isinstance(result, str):
-                result = pydantic_core.to_json(result, fallback=str, indent=2).decode()
-
-            return [TextContent(type="text", text=result)]
+            return result
+        except Exception as e:
+            raise ToolError(f"Error executing tool {self.name}: {e}") from e
 
 
 def _is_async_callable(obj: Any) -> bool: