Validate tool_choice-only sampling answers against the tools-mode result

The capability gate already treats tool_choice alone as tools-mode; the
answer model now shares the same predicate, so array-capable answers to
a tool_choice-only request validate instead of being rejected as the
wrong kind. Also rewords 'form elicitation' to 'form-mode elicitation'
in the docs.

Author: maxisbey

docs/handlers/dependencies.md

@@ -136,13 +136,13 @@ That's the right default for a precondition: no answer, no order. When declining
 
 ## Ask the client, not the user
 
-Elicitation is one of the three questions a resolver can ask, and the multi-round-trip flow allows no others. The other two go to the **client** rather than the user: return `Sample(...)` to run an LLM call through the client (a `sampling/createMessage` request), or `ListRoots()` to fetch the client's current roots. Neither has an accept/decline outcome; the consumer annotates the result type directly, `CreateMessageResult` (`CreateMessageResultWithTools` when the request carries tools) or `ListRootsResult`:
+Elicitation is one of the three questions a resolver can ask, and the multi-round-trip flow allows no others. The other two go to the **client** rather than the user: return `Sample(...)` to run an LLM call through the client (a `sampling/createMessage` request), or `ListRoots()` to fetch the client's current roots. Neither has an accept/decline outcome; the consumer annotates the result type directly, `CreateMessageResult` (`CreateMessageResultWithTools` when the request carries `tools` or `tool_choice`) or `ListRootsResult`:
 
 ```python title="server.py" hl_lines="11-16 22"
 --8<-- "docs_src/dependencies/tutorial004.py"
 ```
 
-* The framework routes these exactly like `Elicit`: inside the multi-round-trip `tools/call` on **2026-07-28**, over the standalone server->client request on **2025-11-25**. An undeclared capability refuses the call with a `-32021` protocol error (`sampling`, `roots`, form `elicitation`; `sampling.tools` when the request carries `tools` or `tool_choice`).
+* The framework routes these exactly like `Elicit`: inside the multi-round-trip `tools/call` on **2026-07-28**, over the standalone server->client request on **2025-11-25**. An undeclared capability refuses the call with a `-32021` protocol error (`sampling`, `roots`, form-mode `elicitation`; `sampling.tools` when the request carries `tools` or `tool_choice`).
 * Everything the info box above says about questions applies unchanged: a `Sample` request is matched to its recorded result by its exact rendering, so build it deterministically from the tool's arguments and earlier answers; the client then pays for the LLM call once per tool call, not once per round. The recorded result rides `request_state` for the rest of the call, so a very large completion makes every remaining round-trip heavier.
 * The standalone sampling and roots *features* are deprecated at 2026-07-28 (SEP-2577). New servers that need the client's model ask through this carrier; servers that don't should integrate with an LLM provider directly. `include_context` values other than `"none"` are themselves deprecated; avoid them.
 

docs/handlers/sampling-and-roots.md

@@ -15,7 +15,7 @@ A resolver returns `Sample(...)` and the tool receives the completion, through t
 --8<-- "docs_src/sampling_and_roots/tutorial001.py"
 ```
 
-* `Sample(messages, max_tokens=...)` mirrors the `sampling/createMessage` parameters. The injected value is the client's `CreateMessageResult`; pass `tools=[...]` and it becomes a `CreateMessageResultWithTools` instead.
+* `Sample(messages, max_tokens=...)` mirrors the `sampling/createMessage` parameters. The injected value is the client's `CreateMessageResult`; pass `tools` or `tool_choice` and it becomes a `CreateMessageResultWithTools` instead.
 * The client must have declared the `sampling` capability (`sampling.tools` if you pass `tools` or `tool_choice`). If it didn't, the call fails with a `-32021` protocol error instead of sending a request the client cannot handle. A pre-2026 session with no back-channel fails with its usual no-back-channel error, since there is nothing to send on.
 * At `2026-07-28` the request is delivered inside the multi-round-trip flow (**[Multi-round-trip requests](multi-round-trip.md)**); on `2025-11-25` it is a standalone request to the client. The code is the same either way, but mind the multi-round-trip rule: the request must render identically across retry rounds, so build it only from the tool's arguments and other stable data.
 * Leave `include_context` alone: values other than `"none"` are themselves deprecated (SEP-2596) and need a capability almost no client declares.

docs/migration.md

@@ -45,7 +45,7 @@ dependencies elicit via `Resolve(...)`: the resolver owns that tool's
 A v1 server could send elicitation, sampling, and roots requests to clients
 that never declared the matching capability; only tools-bearing sampling was
 checked. In v2 the `Resolve(...)` markers (`Elicit`, `Sample`, `ListRoots`)
-enforce the spec's egress rule: an undeclared capability (form `elicitation`,
+enforce the spec's egress rule: an undeclared capability (form-mode `elicitation`,
 `sampling`, or `roots`, plus `sampling.tools` when the request carries `tools`
 or `tool_choice`) fails the call with a `-32021`
 `MISSING_REQUIRED_CLIENT_CAPABILITY` JSON-RPC error instead of sending a

src/mcp/server/mcpserver/resolve.py

@@ -121,10 +121,11 @@ def __init__(self, message: str, schema: type[T]) -> None:
 class Sample:
     """A resolver's request to sample the client's LLM via `sampling/createMessage`.
 
-    The framework injects a `CreateMessageResult` (`CreateMessageResultWithTools` when `tools` are
-    given); requires the `sampling` capability (`sampling.tools` when `tools` or `tool_choice` are given). On
-    >= 2026-07-28 the request must render identically across retry rounds, and the sampled result
-    rides `request_state` on every later round. `include_context` other than "none" is deprecated in the draft spec.
+    The framework injects a `CreateMessageResult` (`CreateMessageResultWithTools` when `tools` or
+    `tool_choice` are given, which also requires the client's `sampling.tools`); requires the
+    `sampling` capability. On >= 2026-07-28 the request must render identically across retry
+    rounds, and the sampled result rides `request_state` on every later round. `include_context`
+    other than "none" is deprecated in the draft spec.
     """
 
     def __init__(
@@ -679,7 +680,7 @@ def _require_capability(context: Context[Any, Any], marker: _Marker, key: str) -
         name = "form elicitation"
     elif isinstance(marker, Sample):
         sampling = capabilities.sampling if capabilities is not None else None
-        wants_tools = marker.params.tools is not None or marker.params.tool_choice is not None
+        wants_tools = _wants_tools(marker.params)
         if sampling is not None and (not wants_tools or sampling.tools is not None):
             return
         required = ClientCapabilities(
@@ -709,13 +710,18 @@ def _render_request(marker: _Marker) -> InputRequest:
     return ListRootsRequest()
 
 
+def _wants_tools(params: CreateMessageRequestParams) -> bool:
+    """Whether a sampling request is tools-mode: `sampling.tools` gated, array-capable answer."""
+    return params.tools is not None or params.tool_choice is not None
+
+
 def _result_type(
     marker: Sample | ListRoots,
 ) -> type[CreateMessageResult] | type[CreateMessageResultWithTools] | type[ListRootsResult]:
     """The result model a `Sample`/`ListRoots` response must validate against."""
     if isinstance(marker, ListRoots):
         return ListRootsResult
-    return CreateMessageResult if marker.params.tools is None else CreateMessageResultWithTools
+    return CreateMessageResultWithTools if _wants_tools(marker.params) else CreateMessageResult
 
 
 class _StateEntry(BaseModel):

tests/server/mcpserver/test_resolve.py

@@ -2754,3 +2754,28 @@ async def tool(login: Annotated[Login, Resolve(ask)]) -> str:
     assert isinstance(message, SessionMessage)
     assert isinstance(message.message, JSONRPCError)
     assert message.message.error.code == MISSING_REQUIRED_CLIENT_CAPABILITY
+
+
+@pytest.mark.anyio
+async def test_tool_choice_only_sample_validates_as_tools_mode():
+    # Gate and answer model share one predicate: tool_choice alone is tools-mode,
+    # so a single-content answer still validates (WithTools accepts both shapes).
+    mcp = MCPServer(name="ToolChoiceOnly", request_state_security=RequestStateSecurity.ephemeral())
+
+    async def sampler(context: ClientRequestContext, params: CreateMessageRequestParams) -> CreateMessageResult:
+        assert params.tool_choice is not None and params.tools is None
+        return CreateMessageResult(role="assistant", content=TextContent(type="text", text="4"), model="m")
+
+    @mcp.tool()
+    async def calc(answer: Annotated[CreateMessageResultWithTools, Resolve(_ask_with_tool_choice)]) -> str:
+        assert isinstance(answer, CreateMessageResultWithTools)
+        content = answer.content[0] if isinstance(answer.content, list) else answer.content
+        assert isinstance(content, TextContent)
+        return content.text
+
+    async with Client(
+        mcp,
+        sampling_callback=sampler,
+        sampling_capabilities=SamplingCapability(tools=SamplingToolsCapability()),
+    ) as client:
+        assert await _text(client, "calc", {}) == "4"