func_metadata: re-inspect residual after stripping InputRequiredResult; fix migration.md call_tool return

Stripping InputRequiredResult arms rebound return_type_expr but not
inspected_return_ann, so a single-arm residual that was itself an
Annotated[...] (e.g. -> Annotated[CallToolResult, Model] | InputRequiredResult,
the documented pattern in README.v2.md) skipped the CallToolResult-with-
metadata special case: isinstance(Annotated[...], type) is False and
.metadata was still the union's empty tuple. It fell through to
_create_wrapped_model, advertising {result: CallToolResult} and raising
ValidationError on every successful return.

Re-run inspect_annotation on the residual so the post-strip state is
indistinguishable from a fresh call without InputRequiredResult — the
existing dispatch then handles every case unchanged. This also restores
Annotated metadata for the simpler Annotated[X, meta] | InputRequiredResult
case.

Also: docs/migration.md still said MCPServer.call_tool() 'always returns a
CallToolResult'; amend to note the InputRequiredResult arm.

Author: maxisbey

docs/migration.md

@@ -10,7 +10,8 @@ Version 2 of the MCP Python SDK introduces several breaking changes to improve t
 
 ### `MCPServer.call_tool()` returns `CallToolResult`
 
-`MCPServer.call_tool()` now always returns a `CallToolResult`. It previously
+`MCPServer.call_tool()` now returns a `CallToolResult` (or an
+`InputRequiredResult` when a multi-round tool requests further input). It previously
 advertised `Sequence[ContentBlock] | dict[str, Any]` and leaked the internal
 conversion shapes (a bare content sequence or a `(content, structured_content)`
 tuple), forcing callers to re-assemble a `CallToolResult` themselves.

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

@@ -294,8 +294,12 @@ def func_metadata(
             return FuncMetadata(arg_model=arguments_model)
         if len(residual) != len(args):
             # PEP 604 has no syntax for "union of a runtime tuple"; Union[...] is the only spelling.
-            return_type_expr = residual[0] if len(residual) == 1 else Union[residual]  # noqa: UP007
-            effective_annotation = return_type_expr
+            effective_annotation = residual[0] if len(residual) == 1 else Union[residual]  # noqa: UP007
+            # Re-normalize so the residual is processed exactly as if it had been the declared
+            # return annotation: unwraps a top-level Annotated[...] arm and re-derives metadata,
+            # so the CallToolResult/BaseModel/TypedDict dispatch below sees the bare type.
+            inspected_return_ann = inspect_annotation(effective_annotation, annotation_source=AnnotationSource.FUNCTION)
+            return_type_expr = inspected_return_ann.type
         if len(residual) > 1 and any(
             isinstance(a, type) and issubclass(a, CallToolResult) for a in residual if a is not type(None)
         ):

tests/server/mcpserver/test_func_metadata.py

@@ -862,6 +862,29 @@ def func_returning_annotated_tool_call_result() -> Annotated[CallToolResult, Per
     assert isinstance(meta.convert_result(func_returning_annotated_tool_call_result()), CallToolResult)
 
 
+def test_tool_call_result_annotated_unioned_with_input_required_result_is_equivalent_to_the_bare_annotated_form():
+    """Stripping `InputRequiredResult` makes the residual behave exactly as if it were the
+    declared return annotation, including the `Annotated[CallToolResult, Model]` special case
+    — the schema derives from `Model` and `convert_result` validates `structured_content`
+    against it instead of wrapping the whole `CallToolResult`."""
+
+    class PersonClass(BaseModel):
+        name: str
+
+    def fn_bare() -> Annotated[CallToolResult, PersonClass]:
+        return CallToolResult(content=[], structured_content={"name": "Brandon"})
+
+    def fn_iir() -> Annotated[CallToolResult, PersonClass] | InputRequiredResult:
+        return CallToolResult(content=[], structured_content={"name": "Brandon"})
+
+    bare = func_metadata(fn_bare)
+    iir = func_metadata(fn_iir)
+    assert iir.output_schema == bare.output_schema
+    assert iir.wrap_output == bare.wrap_output
+    assert isinstance(bare.convert_result(fn_bare()), CallToolResult)
+    assert isinstance(iir.convert_result(fn_iir()), CallToolResult)
+
+
 def test_tool_call_result_annotated_is_structured_and_invalid():
     class PersonClass(BaseModel):
         name: str