Reconcile docs with the negotiated elicitation transport

The Dependencies tutorial explains that the framework picks the question's
transport from the negotiated protocol version, scopes the run-once claim
to what is guaranteed (each question asked once; a non-eliciting resolver
may re-run when a call resumes), and documents the determinism constraint
on questions. Multi-round-trip requests no longer claims @mcp.tool() has
no high-level path to InputRequiredResult - resolver dependencies are that
path. The eliciting tutorial snippets are tested on both transports.

Author: maxisbey

docs/advanced/multi-round-trip.md

@@ -19,7 +19,7 @@ That's the whole protocol. Every leg is an ordinary request from the client to t
 
 ## The server side
 
-The high-level `@mcp.tool()` decorator has no sugar for this yet. Today you write it on the **low-level** `Server`, whose `on_call_tool` handler is allowed to return either result type:
+On `@mcp.tool()` you rarely build this by hand: declare a dependency that asks the user and the SDK returns the `InputRequiredResult` for you - that form is the **[Dependencies](../tutorial/dependencies.md)** tutorial. The manual form is the **low-level** `Server`, whose `on_call_tool` handler is allowed to return either result type:
 
 ```python title="server.py" hl_lines="44-47"
 --8<-- "docs_src/mrtr/tutorial001.py"
@@ -93,6 +93,6 @@ Drop to the underlying session, where `allow_input_required=True` hands you the
 * `input_requests` is what it needs. `request_state` is an opaque resume token only the server reads.
 * `Client` runs the retry loop for you: register `elicitation_callback` / `sampling_callback` / `list_roots_callback` and `call_tool` returns a plain `CallToolResult`. `input_required_max_rounds` (default 10) bounds it.
 * To inspect or persist rounds, use `client.session.call_tool(..., allow_input_required=True)` and own the `while isinstance(result, InputRequiredResult)` loop yourself.
-* The server side is the **low-level** `Server` only; `@mcp.tool()` has no sugar for this yet.
+* On `@mcp.tool()`, a dependency that asks the user produces this result for you (**[Dependencies](../tutorial/dependencies.md)**); the **low-level** `Server` is the manual form.
 
 This is the mechanism that replaces server-initiated sampling and the rest of the push-style back-channel; see **[Deprecated features](deprecated.md)**.

docs/tutorial/dependencies.md

@@ -116,11 +116,24 @@ And if the user won't answer at all - declines the question, or cancels it?
 
 That's the right default for a precondition: no answer, no order. When declining is an outcome your tool wants to handle - skip the backorder but still suggest another title - annotate `ElicitationResult[Backorder]` instead and the tool receives the full accept/decline/cancel outcome to branch on. **[Elicitation](elicitation.md)** shows that form, and everything else about asking: the schema rules, the three answers, the client's side of the conversation.
 
+!!! info
+    The framework picks the question's transport from the negotiated protocol version; the code
+    above is identical on both. On **2026-07-28** and later the question rides inside a
+    multi-round-trip `tools/call` - the server returns it, the client's `elicitation_callback`
+    answers it, and the `Client` retries the call for you (**[Multi-round-trip requests](../advanced/multi-round-trip.md)**). On
+    **2025-11-25** and earlier it is a synchronous elicitation request mid-call. Each question is
+    asked exactly once per call; a resolver that answered *without* asking, like `check_stock`,
+    may run again when the call resumes after a question. When it resumes, each answer is matched
+    back to its question, so an eliciting resolver must derive its question deterministically from
+    the tool's arguments and earlier answers - a per-call generated value (a `default_factory` id,
+    a timestamp) is re-derived on each round and must not appear in a question the answer is meant
+    to bind to.
+
 ## Recap
 
 * `Annotated[T, Resolve(fn)]` on a tool parameter: the SDK runs `fn` and injects its return value.
 * A resolved parameter is invisible to the model and cannot be supplied by a client. Values the model must not invent - prices, identities, permissions - belong here.
-* A resolver's parameters are resolved the same way: the `Context`, another `Resolve(...)`, or a tool argument by name. The graph runs each resolver at most once per call.
+* A resolver's parameters are resolved the same way: the `Context`, another `Resolve(...)`, or a tool argument by name. The graph runs each resolver at most once, however many consumers it has; a resolver that never asked may run again when a call resumes after a question.
 * Bad graphs fail at registration with `InvalidSignature`, not mid-call.
 * Return `Elicit(message, Model)` to ask the user, only when you have to. Unwrapped annotations abort on decline; `ElicitationResult[T]` lets the tool branch.
 

tests/docs_src/test_dependencies.py

@@ -1,5 +1,7 @@
 """`docs/tutorial/dependencies.md`: every claim the page makes, proved against the real SDK."""
 
+from typing import Literal
+
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import ElicitRequestParams, ElicitResult, TextContent
@@ -79,47 +81,56 @@ def get(self, key: str, default: int) -> int:
         assert inventory.lookups == ["Dune", "Dune"]
 
 
-async def test_an_in_stock_order_asks_no_question() -> None:
+# The `!!! info` claims the tutorial003 behaviour is transport-independent, so each claim is
+# proved on both: mode="legacy" elicits synchronously mid-call (2025-11-25 and earlier), while
+# mode="auto" negotiates 2026-07-28, where the question rides a multi-round-trip `tools/call`
+# and `Client` drives the retries.
+@pytest.mark.parametrize("mode", ["legacy", "auto"])
+async def test_an_in_stock_order_asks_no_question(mode: Literal["legacy", "auto"]) -> None:
     """tutorial003: `confirm_backorder` returns directly when stock exists - no round-trip."""
 
     async def never(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:  # pragma: no cover
         raise AssertionError("an in-stock order must not elicit")
 
-    async with Client(tutorial003.mcp, mode="legacy", elicitation_callback=never) as client:
+    async with Client(tutorial003.mcp, mode=mode, elicitation_callback=never) as client:
         result = await client.call_tool("order_book", {"title": "Dune"})
 
     assert result.content == [TextContent(type="text", text="Ordered 'Dune'.")]
 
 
+@pytest.mark.parametrize("mode", ["legacy", "auto"])
 @pytest.mark.parametrize(
     ("confirm", "expected"),
     [
         (True, "Backordered 'Neuromancer'; it ships in 2-3 weeks."),
         (False, "No order placed."),
     ],
 )
-async def test_an_out_of_stock_order_asks_and_honours_the_answer(confirm: bool, expected: str) -> None:
+async def test_an_out_of_stock_order_asks_and_honours_the_answer(
+    mode: Literal["legacy", "auto"], confirm: bool, expected: str
+) -> None:
     """tutorial003: the resolver elicits, the SDK validates the answer, the tool reads it."""
     asked: list[str] = []
 
     async def on_elicit(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
         asked.append(params.message)
         return ElicitResult(action="accept", content={"confirm": confirm})
 
-    async with Client(tutorial003.mcp, mode="legacy", elicitation_callback=on_elicit) as client:
+    async with Client(tutorial003.mcp, mode=mode, elicitation_callback=on_elicit) as client:
         result = await client.call_tool("order_book", {"title": "Neuromancer"})
 
     assert result.content == [TextContent(type="text", text=expected)]
     assert asked == ["'Neuromancer' is out of stock (2-3 weeks). Order anyway?"]
 
 
-async def test_declining_an_unwrapped_dependency_aborts_the_call() -> None:
+@pytest.mark.parametrize("mode", ["legacy", "auto"])
+async def test_declining_an_unwrapped_dependency_aborts_the_call(mode: Literal["legacy", "auto"]) -> None:
     """tutorial003: no answer, no order - the error text on the page is the real one."""
 
     async def decline(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
         return ElicitResult(action="decline")
 
-    async with Client(tutorial003.mcp, mode="legacy", elicitation_callback=decline) as client:
+    async with Client(tutorial003.mcp, mode=mode, elicitation_callback=decline) as client:
         result = await client.call_tool("order_book", {"title": "Neuromancer"})
 
     assert result.is_error