we can use Annotated to still support output schemas

Author: BrandonShar

examples/fastmcp/direct_call_tool_result_return.py

@@ -2,14 +2,22 @@
 FastMCP Echo Server with direct CallToolResult return
 """
 
+from typing import Annotated
+
+from pydantic import BaseModel
+
 from mcp.server.fastmcp import FastMCP
 from mcp.types import CallToolResult, TextContent
 
 mcp = FastMCP("Echo Server")
 
 
+class EchoResponse(BaseModel):
+    text: str
+
+
 @mcp.tool()
-def echo(text: str) -> CallToolResult:
+def echo(text: str) -> Annotated[CallToolResult, EchoResponse]:
     """Echo the input text with structure and metadata"""
     return CallToolResult(
         content=[TextContent(type="text", text=text)], structuredContent={"text": text}, _meta={"some": "metadata"}

src/mcp/server/fastmcp/utilities/func_metadata.py

@@ -105,6 +105,9 @@ def convert_result(self, result: Any) -> Any:
         the structured output.
         """
         if isinstance(result, CallToolResult):
+            if self.output_schema is not None:
+                assert self.output_model is not None, "Output model must be set if output schema is defined"
+                self.output_model.model_validate(result.structuredContent)
             return result
 
         unstructured_content = _convert_to_content(result)
@@ -271,9 +274,13 @@ def func_metadata(
     output_info = FieldInfo.from_annotation(_get_typed_annotation(sig.return_annotation, globalns))
     annotation = output_info.annotation
 
-    # if the typehint is CallToolResult, the user intends to return it directly without validation
+    # if the typehint is CallToolResult, the user either intends to return without validation
+    # or they provided validation as Annotated metadata
     if isinstance(annotation, type) and issubclass(annotation, CallToolResult):
-        return FuncMetadata(arg_model=arguments_model)
+        if output_info.metadata:
+            annotation = output_info.metadata[0]
+        else:
+            return FuncMetadata(arg_model=arguments_model)
 
     output_model, output_schema, wrap_output = _try_create_model_and_schema(annotation, func.__name__, output_info)
 

tests/server/fastmcp/test_func_metadata.py

@@ -845,6 +845,39 @@ def func_returning_call_tool_result() -> CallToolResult:
     assert isinstance(meta.convert_result(func_returning_call_tool_result()), CallToolResult)
 
 
+def test_tool_call_result_annotated_is_structured_and_converted():
+    class PersonClass(BaseModel):
+        name: str
+
+    def func_returning_annotated_tool_call_result() -> Annotated[CallToolResult, PersonClass]:
+        return CallToolResult(content=[], structuredContent={"name": "Brandon"})
+
+    meta = func_metadata(func_returning_annotated_tool_call_result)
+
+    assert meta.output_schema == {
+        "type": "object",
+        "properties": {
+            "name": {"title": "Name", "type": "string"},
+        },
+        "required": ["name"],
+        "title": "PersonClass",
+    }
+    assert isinstance(meta.convert_result(func_returning_annotated_tool_call_result()), CallToolResult)
+
+
+def test_tool_call_result_annotated_is_structured_and_invalid():
+    class PersonClass(BaseModel):
+        name: str
+
+    def func_returning_annotated_tool_call_result() -> Annotated[CallToolResult, PersonClass]:
+        return CallToolResult(content=[], structuredContent={"person": "Brandon"})
+
+    meta = func_metadata(func_returning_annotated_tool_call_result)
+
+    with pytest.raises(ValueError):
+        meta.convert_result(func_returning_annotated_tool_call_result())
+
+
 def test_structured_output_with_field_descriptions():
     """Test that Field descriptions are preserved in structured output"""