Split the tools-mode sampling overloads for sound narrowing

The broadened two-overload shape let a caller passing optional
tools/tool_choice variables infer CreateMessageResultWithTools while
the runtime could return the plain result. Three overloads (neither,
tools, tool_choice) keep literal calls exact and type unnarrowed
optional arguments as the result union, which matches the runtime.

Author: maxisbey

src/mcp/server/session.py

@@ -165,11 +165,31 @@ async def create_message(
         stop_sequences: list[str] | None = None,
         metadata: dict[str, Any] | None = None,
         model_preferences: types.ModelPreferences | None = None,
-        tools: list[types.Tool] | None = None,
+        tools: list[types.Tool],
         tool_choice: types.ToolChoice | None = None,
         related_request_id: types.RequestId | None = None,
     ) -> types.CreateMessageResultWithTools:
-        """Overload: With tools or tool_choice, returns array-capable content."""
+        """Overload: With tools, returns array-capable content."""
+        ...
+
+    @overload
+    @deprecated("The sampling capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def create_message(
+        self,
+        messages: list[types.SamplingMessage],
+        *,
+        max_tokens: int,
+        system_prompt: str | None = None,
+        include_context: types.IncludeContext | None = None,
+        temperature: float | None = None,
+        stop_sequences: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        model_preferences: types.ModelPreferences | None = None,
+        tools: list[types.Tool] | None = None,
+        tool_choice: types.ToolChoice,
+        related_request_id: types.RequestId | None = None,
+    ) -> types.CreateMessageResultWithTools:
+        """Overload: With tool_choice, returns array-capable content."""
         ...
 
     @deprecated("The sampling capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)

src/mcp/shared/peer.py

@@ -115,11 +115,29 @@ async def sample(
         stop_sequences: list[str] | None = None,
         metadata: dict[str, Any] | None = None,
         model_preferences: ModelPreferences | None = None,
-        tools: list[Tool] | None = None,
+        tools: list[Tool],
         tool_choice: ToolChoice | None = None,
         meta: Meta | None = None,
         opts: CallOptions | None = None,
     ) -> CreateMessageResultWithTools: ...
+    @overload
+    @deprecated("The sampling capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
+    async def sample(
+        self,
+        messages: list[SamplingMessage],
+        *,
+        max_tokens: int,
+        system_prompt: str | None = None,
+        include_context: IncludeContext | None = None,
+        temperature: float | None = None,
+        stop_sequences: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        model_preferences: ModelPreferences | None = None,
+        tools: list[Tool] | None = None,
+        tool_choice: ToolChoice,
+        meta: Meta | None = None,
+        opts: CallOptions | None = None,
+    ) -> CreateMessageResultWithTools: ...
     @deprecated("The sampling capability is deprecated as of 2026-07-28 (SEP-2577).", category=MCPDeprecationWarning)
     async def sample(
         self,