Tighten comments and docstrings across the extension surface

Comments state only non-inferable constraints, one line where possible;
docstrings follow Google format with a single-sentence summary and
tightened Raises sections; development narration and restated-code
comments are gone. Prose sticks to ASCII.

Author: maxisbey

docs/advanced/extensions.md

@@ -157,16 +157,16 @@ client-side behaviour behind one identifier. Pass instances to
 
 `call_tool("buy", ...)` returns a plain `CallToolResult`, like every other call. What
 the extension changed: the server may now answer `buy` with a `receipt` **result
-shape** instead of a final result, and `Receipts` finishes it — here by redeeming the
-receipt with a follow-up call — before `call_tool` returns. Nothing about the call
+shape** instead of a final result, and `Receipts` finishes it (here by redeeming the
+receipt with a follow-up call) before `call_tool` returns. Nothing about the call
 site moves.
 
 Drop the extension and none of this exists: a `receipt` shape arriving at a client
 that didn't declare it fails validation, exactly as the spec requires for an
 unrecognized `resultType`. Off by default, on both ends of the wire.
 
-To advertise an identifier with **no** client-side behaviour — the server gates on
-the capability, the client does nothing, as in the search client above — use
+To advertise an identifier with **no** client-side behaviour (the server gates on
+the capability, the client does nothing, as in the search client above), use
 `advertise()`:
 
 ```python
@@ -189,7 +189,7 @@ kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
 * `claims()` returns `ResultClaim`s: a wire tag, the model that parses it, and the
   resolver that finishes it. The model must pin the tag with
   `result_type: Literal["receipt"]` and must not subclass the verb's core result
-  types — both enforced when the claim is constructed. Vendor fields like
+  types; both are enforced when the claim is constructed. Vendor fields like
   `receipt_token` ride the wire as-is: a substituted shape reaches the client
   verbatim.
 * The resolver receives the parsed model and a `ClaimContext`; `ctx.session` is the
@@ -210,11 +210,10 @@ or reply.
 
 Two quiet rules. Claims are active on 2026-07-28 connections only, and the capability
 ad follows them: on a legacy connection the claims dissolve and the identifier drops
-out of the ad in the same breath, so the client never advertises an extension whose
-shapes it would reject. And when you want the claimed shape yourself instead of the
-resolver, call `client.session.call_tool(..., allow_claimed=True)` — the escape hatch
-`UnexpectedClaimedResult` names when a claimed shape reaches a session-tier caller
-that didn't opt in.
+out of the ad with them, so the client never advertises an extension whose shapes it
+would reject. And when you want the claimed shape yourself instead of the resolver,
+call `client.session.call_tool(..., allow_claimed=True)`; without that flag, a
+claimed shape reaching a session-tier caller raises `UnexpectedClaimedResult`.
 
 ### Extension verbs
 
@@ -233,8 +232,8 @@ missing value fails loudly rather than silently omitting a required header.
 
 ## What an extension cannot do
 
-The contribution surface is **closed** on purpose — on the server: settings, tools,
-resources, methods, one `tools/call` interceptor; on the client: settings, result
+The contribution surface is **closed** on purpose. On the server: settings, tools,
+resources, methods, one `tools/call` interceptor. On the client: settings, result
 claims, notification bindings. An extension cannot:
 
 * **Reach into the host.** It declares data; it holds no server or client reference.

docs/migration.md

@@ -483,9 +483,9 @@ default and never alter behaviour unless registered. (The low-level
 
 Changed in the v2 pre-releases: earlier alphas took
 `Client(extensions={identifier: settings})`, an advertisement-only dict.
-Extensions now contribute behaviour — claims and notification handlers — not
-just an ad, and a sequence of declaration objects is the shape that can carry
-that. An ad-only entry becomes an `advertise()` call:
+Extensions now contribute behaviour (claims and notification handlers), not
+just an ad, so the argument is a sequence of declaration objects. An ad-only
+entry becomes an `advertise()` call:
 
 **Before (v2 alphas):**
 
@@ -501,10 +501,10 @@ from mcp.client import advertise
 client = Client(server, extensions=[advertise("com.example/ui", {"mimeTypes": [...]})])
 ```
 
-`advertise()` is only for identifiers with no client-side behaviour.
-For a behavioural extension — e.g. tasks, once its extension ships — construct
-that extension's object instead; advertising an identifier you do not
-implement asserts wire support you don't have.
+`advertise()` is only for identifiers with no client-side behaviour. For a
+behavioural extension (e.g. tasks, once its extension ships), construct that
+extension's object instead; advertising an identifier you do not implement
+asserts wire support you don't have.
 
 ### `McpError` renamed to `MCPError`
 

examples/stories/custom_methods/README.md

@@ -29,8 +29,7 @@ uv run python -m stories.custom_methods.client --http
   collide with a future spec method.
 - `client.py` `client.session.send_request(...)` — `Client` only exposes spec
   verbs, so vendor methods go through the underlying `ClientSession`.
-  `send_request` accepts any `types.Request` subclass, so the vendor request
-  passes as-is, no cast.
+  `send_request` accepts any `types.Request` subclass.
 
 ## Caveats
 

examples/stories/custom_methods/client.py

@@ -27,8 +27,7 @@ async def main(target: Target, *, mode: str = "auto") -> None:
         # `Client` only exposes spec-defined verbs, so vendor methods have to drop one
         # layer to `client.session` today — there is no `Client`-level API for them
         # yet, and whether `.session` stays public is undecided. `send_request`
-        # accepts any `Request` subclass; the unknown method skips the per-spec
-        # result-validation registry.
+        # accepts any `Request` subclass.
         request = SearchRequest(params=SearchParams(query="mcp", limit=3))
         result = await client.session.send_request(request, SearchResult)
         assert result.items == ["mcp-0", "mcp-1", "mcp-2"], result

src/mcp-types/mcp_types/_types.py

@@ -129,10 +129,10 @@ class Request(MCPModel, Generic[RequestParamsT, MethodT]):
     params: RequestParamsT
 
     name_param: ClassVar[str | None] = None
-    """Wire-params key mirrored into the `Mcp-Name` header on sends (SEP-2243
-    family; SEP-2663 requires it for tasks/*). The request type declares; the
-    host emits. Subclasses override by bare assignment (`name_param = "taskId"`)
-    — re-annotating as `ClassVar[str]` trips pyright's ClassVar invariance."""
+    """Wire-params key mirrored into the `Mcp-Name` header on sends; SEP-2663 requires it for tasks/*.
+
+    Subclasses override by bare assignment: re-annotating as `ClassVar` trips pyright's invariance check.
+    """
 
 
 class PaginatedRequest(Request[PaginatedRequestParams | None, MethodT], Generic[MethodT]):

src/mcp/client/client.py

@@ -202,19 +202,11 @@ class _FoldedExtensions:
 
 
 def _fold_extensions(extensions: Sequence[ClientExtension] | None) -> _FoldedExtensions:
-    """Validate extension instances and fold their contributions, once, at `Client` construction.
-
-    Mirrors the server's consumption-time posture (`MCPServer._apply_extension`): a
-    per-instance identifier is validated here because no class attribute existed to
-    validate at definition time. `settings()` is read exactly once per extension and
-    the returned dict is held by reference. Duplicate resultType claims and
-    duplicate notification methods are rejected here, where both owning extensions
-    can be named — the session's own duplicate checks know only methods and tags.
-    """
+    """Fold extension contributions at construction, naming both owners on duplicate tags or methods."""
     if isinstance(extensions, Mapping):
         raise TypeError(
-            "extensions= takes a sequence of ClientExtension instances; the mapping form was "
-            "replaced — use advertise(identifier, settings) for advertise-only entries"
+            "extensions= takes a sequence of ClientExtension instances. The mapping form was "
+            "replaced: use advertise(identifier, settings) for advertise-only entries"
         )
     if not extensions:
         return _FoldedExtensions(ad=None, claims=None, bindings=None, by_model={})
@@ -247,8 +239,7 @@ def _fold_extensions(extensions: Sequence[ClientExtension] | None) -> _FoldedExt
                 )
                 raise ValueError(f"{both} resultType {tag!r}; a wire tag can have only one resolver")
             claim_owners[tag] = identifier
-            # One model, one tag: the model's result_type Literal is pinned to exactly
-            # this tag at claim construction, so the type-keyed index cannot collide.
+            # Each model pins its result_type Literal to one tag, so this index cannot collide.
             by_model[claim.model] = claim
         if extension_claims:
             claims[identifier] = extension_claims
@@ -349,13 +340,9 @@ async def main():
     extensions: Sequence[ClientExtension] | None = None
     """Opt-in client extensions (SEP-2133).
 
-    Each instance contributes its capability ad (advertised under
-    `ClientCapabilities.extensions`), its result claims (extra `tools/call` result
-    shapes that `call_tool` resolves transparently through the claim's resolver),
-    and its notification bindings. For an ad-only entry — an identifier plus
-    settings, no client-side behaviour — use `mcp.client.advertise(identifier,
-    settings)`. Each extension's `settings()` is read once, at construction; the
-    returned dict is held by reference."""
+    Each instance contributes its capability ad, its result claims (resolved
+    transparently by `call_tool`), and its notification bindings. For an
+    ad-only entry use `mcp.client.advertise(identifier, settings)`."""
 
     cache: CacheConfig | Literal[False] | None = None
     """Client-side response caching for the SEP-2549 cacheable methods (2026-07-28).
@@ -701,11 +688,9 @@ async def call_tool(
         persist `request_state` across process restarts — use
         `client.session.call_tool(..., allow_input_required=True)`.
 
-        If the server returns a result shape claimed by one of this client's
-        `extensions`, the owning claim's resolver finishes the call and its
-        `CallToolResult` is returned — the claimed shape never surfaces here.
-        Resolver exceptions propagate as-is; the extension owns its error
-        vocabulary. To receive the claimed shape yourself, use
+        Result shapes claimed by this client's `extensions` are finished by the
+        owning claim's resolver, whose `CallToolResult` is returned; resolver
+        exceptions propagate as-is. To receive the claimed shape yourself, use
         `client.session.call_tool(..., allow_claimed=True)`.
 
         Args:
@@ -736,26 +721,21 @@ async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | Inp
                 request_state=s,
                 meta=meta,
                 allow_input_required=True,
-                # The driver's retry leg must also admit claimed shapes — the spec
-                # resolves multi-round-trip input before a claimed result, so a claim
-                # may terminate any round, not just the first.
+                # Input rounds resolve before a claimed result, so a claim may end any round.
                 allow_claimed=True,
             )
 
         result = await self._drive_input_required(await retry(input_responses, request_state), retry)
         if isinstance(result, CallToolResult):
             return result
-        # Only claimed shapes escape the parse (`_drive_input_required` never returns an
-        # `InputRequiredResult`), so the lookup is total; a KeyError here is an SDK bug.
+        # Only claimed shapes reach this point, so the lookup is total.
         claim = self._folded_extensions.by_model[type(result)]
         final = await claim.resolve(
             result,
             ClaimContext(session=self.session, tool_name=name, read_timeout_seconds=read_timeout_seconds),
         )
         if not final.is_error:
-            # The resolver's product gets the same output-schema revalidation as the
-            # direct path (`ClientSession.call_tool`'s own guard); isError results
-            # must not raise, also matching the direct path.
+            # Match the direct path: revalidate the output schema, but never for isError results.
             await self.session.validate_tool_result(name, final)
         return final