Strengthen Toolsets draft reference tests and docs.

Cover unknown pins on tools/call, omit unregistered membership names, and frame the feature as an incubating SEP reference.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: palmertron

docs/advanced/toolsets.md

@@ -1,14 +1,15 @@
 # Toolsets
 
-**Toolsets** are named, SemVer-versioned, immutable capability surfaces: a fixed
+**Toolsets** are named, semantically versioned, immutable capability surfaces: a fixed
 membership of tool names that a client can discover and pin on `tools/list` and
 `tools/call`. They address uncontrolled tool-surface expansion when agents discover
 tools dynamically — a client pinned to `core-ops@1.2.0` never sees tools that only
 exist in a later Toolset version.
 
-This SDK ships Toolsets as the built-in `Toolsets` extension
-(`io.modelcontextprotocol/toolsets`), matching the Toolset Versioning SEP draft.
-If [Extensions](extensions.md) are new to you, skim that page first.
+This page documents the SDK's **draft reference** implementation of the Toolset
+Versioning SEP (`Toolsets` / `io.modelcontextprotocol/toolsets`). The surface is
+opt-in and may change while the SEP is under review — treat it as incubating, not a
+frozen stable API. If [Extensions](extensions.md) are new to you, skim that page first.
 
 ## Advertise and publish
 
@@ -65,7 +66,12 @@ async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
 
 Omitting `toolset` keeps today's full flat catalog. Calling a non-member under a
 pin returns a protocol `MCPError` (`reason: tool_not_in_toolset`), not a tool
-`is_error` result.
+`is_error` result. Membership names with no registered tool are omitted from a
+pinned `tools/list` (the list does not fail).
+
+When `tools/list` pagination is used, membership filtering applies **before**
+paging: build the pin's tool sequence, then apply `cursor` / `nextCursor` to that
+filtered sequence.
 
 ## Cache keys
 

src/mcp/server/toolsets.py

@@ -1,6 +1,6 @@
 """Toolset Versioning extension (`io.modelcontextprotocol/toolsets`).
 
-Implements the wire shape from the Toolset Versioning SEP: named, SemVer'd,
+Draft reference implementation of the Toolset Versioning SEP: named, semantically versioned,
 immutable capability surfaces that clients discover via `toolsets/list` and pin
 on `tools/list` / `tools/call`.
 

tests/server/test_toolsets.py

@@ -1,4 +1,4 @@
-"""In-memory tests for the Toolset Versioning extension prototype."""
+"""In-memory tests for the Toolset Versioning SEP draft reference implementation."""
 
 from __future__ import annotations
 
@@ -108,6 +108,39 @@ async def test_unknown_toolset_pin_on_list_raises_mcp_error() -> None:
         assert exc_info.value.data["reason"] == "unknown_toolset"
 
 
+async def test_unknown_toolset_pin_on_call_raises_mcp_error() -> None:
+    """Spec: unknown (name, version) on tools/call returns unknown_toolset."""
+    mcp, _ = _crm_server()
+    pin = ToolsetRef(name="core-ops", version="9.9.9")
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
+        with pytest.raises(MCPError) as exc_info:
+            await client.call_tool("search_contacts", {"query": "acme"}, toolset=pin)
+        assert exc_info.value.code == TOOLSET_ERROR
+        assert exc_info.value.data["reason"] == "unknown_toolset"
+
+
+async def test_pinned_tools_list_omits_membership_names_without_registered_tools() -> None:
+    """Spec: pinned tools/list omits membership names that have no registered tool."""
+    toolsets = Toolsets()
+    mcp = MCPServer("crm", extensions=[toolsets])
+
+    @mcp.tool()
+    def search_contacts(query: str) -> str:
+        return f"found:{query}"
+
+    toolsets.add_toolset(
+        name="core-ops",
+        version="1.0.0",
+        status="stable",
+        tools=["search_contacts", "ghost_tool_not_registered"],
+    )
+    pin = ToolsetRef(name="core-ops", version="1.0.0")
+
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
+        result = await client.list_tools(toolset=pin)
+        assert [t.name for t in result.tools] == ["search_contacts"]
+
+
 async def test_pinned_call_rejects_non_member_and_allows_member() -> None:
     """Spec: tools/call under a pin rejects non-members and runs members."""
     mcp, _ = _crm_server()