enable tool to explicitly state output schema to override automatic output schema detection

Author: davemssavage

src/mcp/client/session.py

@@ -142,7 +142,9 @@ def __init__(
         self._list_roots_callback = list_roots_callback or _default_list_roots_callback
         self._logging_callback = logging_callback or _default_logging_callback
         self._message_handler = message_handler or _default_message_handler
-        self._tool_output_validator_provider = tool_output_validator_provider or _default_tool_output_validator
+        self._tool_output_validator_provider = (
+            tool_output_validator_provider or _default_tool_output_validator
+        )
 
     async def initialize(self) -> types.InitializeResult:
         sampling = types.SamplingCapability()

src/mcp/server/fastmcp/server.py

@@ -324,6 +324,7 @@ def add_tool(
         name: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
+        output_schema: dict[str, Any] | None = None,
     ) -> None:
         """Add a tool to the server.
 
@@ -335,9 +336,15 @@ def add_tool(
             name: Optional name for the tool (defaults to function name)
             description: Optional description of what the tool does
             annotations: Optional ToolAnnotations providing additional tool information
+            output_schema: Optional json schema that the tool should output. If
+            not specified the schema will be inferred automatically
         """
         self._tool_manager.add_tool(
-            fn, name=name, description=description, annotations=annotations
+            fn,
+            name=name,
+            description=description,
+            annotations=annotations,
+            output_schema=output_schema,
         )
 
     def tool(

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

@@ -47,6 +47,7 @@ def from_function(
         description: str | None = None,
         context_kwarg: str | None = None,
         annotations: ToolAnnotations | None = None,
+        output_schema: dict[str, Any] | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
         from mcp.server.fastmcp.server import Context
@@ -71,6 +72,7 @@ def from_function(
         func_arg_metadata = func_metadata(
             fn,
             skip_names=[context_kwarg] if context_kwarg is not None else [],
+            output_schema=output_schema,
         )
         parameters = func_arg_metadata.arg_model.model_json_schema()
         output = func_arg_metadata.output_schema

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

@@ -37,10 +37,15 @@ def add_tool(
         name: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
+        output_schema: dict[str, Any] | None = None,
     ) -> Tool:
         """Add a tool to the server."""
         tool = Tool.from_function(
-            fn, name=name, description=description, annotations=annotations
+            fn,
+            name=name,
+            description=description,
+            annotations=annotations,
+            output_schema=output_schema,
         )
         existing = self._tools.get(tool.name)
         if existing:

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

@@ -112,7 +112,9 @@ def pre_parse_json(self, data: dict[str, Any]) -> dict[str, Any]:
 
 
 def func_metadata(
-    func: Callable[..., Any], skip_names: Sequence[str] = ()
+    func: Callable[..., Any],
+    skip_names: Sequence[str] = (),
+    output_schema: dict[str, Any] | None = None,
 ) -> FuncMetadata:
     """Given a function, return metadata including a pydantic model representing its
     signature.
@@ -137,7 +139,6 @@ def func_metadata(
     sig = _get_typed_signature(func)
     params = sig.parameters
     dynamic_pydantic_model_params: dict[str, Any] = {}
-    output_schema: dict[str, Any] | None = None
     globalns = getattr(func, "__globals__", {})
     for param in params.values():
         if param.name.startswith("_"):
@@ -183,14 +184,17 @@ def func_metadata(
         __base__=ArgModelBase,
     )
 
-    # TODO this could be moved to a constant or passed in as param as per skip_names
-    ignore = [inspect.Parameter.empty, None, types.Image]
-    if sig.return_annotation not in ignore:
-        type_schema = TypeAdapter(sig.return_annotation).json_schema()
-        if type_schema.get("type", None) == "object":
-            output_schema = type_schema
+    return_output_schema = output_schema
 
-    return FuncMetadata(arg_model=arguments_model, output_schema=output_schema)
+    if return_output_schema is None:
+        # TODO this could be moved to a constant or passed in as param as per skip_names
+        ignore = [inspect.Parameter.empty, None, types.Image]
+        if sig.return_annotation not in ignore:
+            type_schema = TypeAdapter(sig.return_annotation).json_schema()
+            if type_schema.get("type", None) == "object":
+                return_output_schema = type_schema
+
+    return FuncMetadata(arg_model=arguments_model, output_schema=return_output_schema)
 
 
 def _get_typed_annotation(annotation: Any, globalns: dict[str, Any]) -> Any:

tests/server/fastmcp/test_func_metadata.py

@@ -449,6 +449,9 @@ def test_simple_function_output_schema():
 
     assert func_metadata(simple_no_annotation_fun).output_schema is None
     assert func_metadata(simple_str_fun).output_schema is None
+    assert func_metadata(
+        simple_str_fun, output_schema={"type": "string"}
+    ).output_schema == {"type": "string"}
     assert func_metadata(simple_bool_fun).output_schema is None
     assert func_metadata(simple_int_fun).output_schema is None
     assert func_metadata(simple_float_fun).output_schema is None