refactor: add ToolResult alias and call_tool regression test

Define the call_tool return union once as the ToolResult type alias and
reference it from _handle_call_tool, call_tool, and the migration guide so
the signature can't drift across locations.

Add a regression test that drives a tool with an output schema through
_handle_call_tool and asserts the resulting CallToolResult has both content
and structured_content populated, pinning the reachable tuple path.

Author: Ar-maan05

docs/migration.md

@@ -430,7 +430,11 @@ The internal layers (`ToolManager.call_tool`, `Tool.run`, `Prompt.render`, `Reso
 
 ### `MCPServer.call_tool()` return type corrected
 
-`MCPServer.call_tool()`'s return type signature has been corrected from `Sequence[ContentBlock] | dict[str, Any]` to `CallToolResult | Sequence[ContentBlock] | tuple[Sequence[ContentBlock], dict[str, Any]]` to match what the internal tool manager actually returns when converting tool results.
+`MCPServer.call_tool()`'s return type signature has been corrected from `Sequence[ContentBlock] | dict[str, Any]` to match what the internal tool manager actually returns when converting tool results. The union is now defined once as the `ToolResult` type alias (`mcp.server.mcpserver.server.ToolResult`), so the signature has a single source of truth:
+
+```python
+ToolResult: TypeAlias = CallToolResult | Sequence[ContentBlock] | tuple[Sequence[ContentBlock], dict[str, Any]]
+```
 
 **Before (v1):**
 
@@ -445,7 +449,7 @@ async def call_tool(
 ```python
 async def call_tool(
     self, name: str, arguments: dict[str, Any], context: Context[LifespanResultT, Any] | None = None
-) -> CallToolResult | Sequence[ContentBlock] | tuple[Sequence[ContentBlock], dict[str, Any]]:
+) -> ToolResult:
 ```
 
 ### Registering lowlevel handlers on `MCPServer` (workaround)

src/mcp/server/mcpserver/server.py

@@ -7,7 +7,7 @@
 import re
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Sequence
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
-from typing import Any, Generic, Literal, TypeVar, overload
+from typing import Any, Generic, Literal, TypeAlias, TypeVar, overload
 
 import anyio
 import pydantic_core
@@ -75,6 +75,15 @@
 
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
 
+ToolResult: TypeAlias = CallToolResult | Sequence[ContentBlock] | tuple[Sequence[ContentBlock], dict[str, Any]]
+"""Result of invoking a tool via `MCPServer.call_tool`. One of:
+
+- `CallToolResult`: the tool returned a `CallToolResult` directly.
+- `Sequence[ContentBlock]`: unstructured content from a tool with no output schema.
+- `tuple[Sequence[ContentBlock], dict[str, Any]]`: unstructured content paired with
+  structured content from a tool that has an output schema.
+"""
+
 
 class Settings(BaseSettings, Generic[LifespanResultT]):
     """MCPServer settings.
@@ -308,7 +317,7 @@ async def _handle_call_tool(
     ) -> CallToolResult:
         context = Context(request_context=ctx, mcp_server=self)
         try:
-            result = await self.call_tool(params.name, params.arguments or {}, context)
+            result: ToolResult = await self.call_tool(params.name, params.arguments or {}, context)
         except MCPError:
             raise
         except Exception as e:
@@ -390,14 +399,14 @@ async def list_tools(self) -> list[MCPTool]:
 
     async def call_tool(
         self, name: str, arguments: dict[str, Any], context: Context[LifespanResultT, Any] | None = None
-    ) -> CallToolResult | Sequence[ContentBlock] | tuple[Sequence[ContentBlock], dict[str, Any]]:
+    ) -> ToolResult:
         """Call a tool by name with arguments.
 
         Returns:
-            CallToolResult: If the tool returned a CallToolResult directly.
-            Sequence[ContentBlock]: If the tool returned unstructured content and has no output schema.
-            tuple[Sequence[ContentBlock], dict[str, Any]]: If the tool has an output schema,
-                returning both unstructured content and structured content.
+            ToolResult: One of a `CallToolResult` (returned directly by the tool), a
+                `Sequence[ContentBlock]` (unstructured content from a tool with no output schema),
+                or a `tuple[Sequence[ContentBlock], dict[str, Any]]` (unstructured content paired
+                with structured content from a tool that has an output schema).
         """
         if context is None:
             context = Context(mcp_server=self)

tests/server/mcpserver/test_server.py

@@ -22,6 +22,8 @@
 from mcp.types import (
     AudioContent,
     BlobResourceContents,
+    CallToolRequestParams,
+    CallToolResult,
     Completion,
     CompletionArgument,
     CompletionContext,
@@ -1516,3 +1518,41 @@ async def test_report_progress_passes_related_request_id():
         message="halfway",
         related_request_id="req-abc-123",
     )
+
+
+async def test_handle_call_tool_populates_content_and_structured_content():
+    """A tool with an output schema flows through the tuple branch of `_handle_call_tool`.
+
+    The resulting `CallToolResult` must have both `content` and `structured_content`
+    populated. This pins the reachable tuple path: the converter never returns a raw
+    dict, so the `isinstance(result, dict)` branch removed in #2695 is dead. If that
+    dead branch is ever reintroduced and starts intercepting this path, the structured
+    content would be dropped and this test fails.
+    """
+
+    class Point(BaseModel):
+        x: int
+        y: int
+
+    def make_point(x: int, y: int) -> Point:
+        return Point(x=x, y=y)
+
+    mcp = MCPServer()
+    mcp.add_tool(make_point)
+
+    request_context = ServerRequestContext(
+        session=AsyncMock(),
+        lifespan_context=None,
+        experimental=Experimental(),
+    )
+
+    result = await mcp._handle_call_tool(
+        request_context,
+        CallToolRequestParams(name="make_point", arguments={"x": 1, "y": 2}),
+    )
+
+    assert isinstance(result, CallToolResult)
+    assert result.is_error is False
+    assert result.structured_content == {"x": 1, "y": 2}
+    assert len(result.content) == 1
+    assert isinstance(result.content[0], TextContent)