Skip to content

Commit 8705d39

Browse files
committed
examples: clarify alternative-modelcontextprotocol#2 in SPEC.md rationale
The original wording assumed readers could reverse-engineer the rejected alternative from the rejection clauses. Rewrite to spell out the alternative explicitly first ("redefine tools/list as the compact surface; add tools/search for full schemas"), then state the two rejection reasons clearly: 1. Silent backward-compat break: existing clients expecting full schemas from tools/list would get structurally valid responses with the schemas silently absent. The worst kind of break. 2. Semantic mismatch: a method named "list" should return the things themselves, not a directory of references with summaries. No protocol or behaviour change.
1 parent f55277f commit 8705d39

1 file changed

Lines changed: 1 addition & 1 deletion

File tree

  • examples/progressive-disclosure

‎examples/progressive-disclosure/SPEC.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@ SEP-1821 made the right call here: query format is server-defined, and the serve
257257
### Alternatives considered
258258

259259
1. **Single `tools/list` method with a `fields` projection parameter** (à la GraphQL field selection or Google APIs partial responses). Rejected: pushes complexity into both client and server for a use case that has only two practical projections (lightweight vs. full).
260-
2. **A separate `tools/search` method, leaving `tools/list` as the lightweight surface**. Rejected: changing the meaning of an existing method is a backward-compatibility hazard, and "list" is a poor name for the lightweight surface once `summary` is added.
260+
2. **Inverting the surfaces**: keep the lightweight payload on `tools/list` and add a new `tools/search` for full-schema fetches. Concretely: redefine `tools/list` so it returns the compact `ToolCatalogEntry[]` proposed here, and add `tools/search` returning full `Tool[]` for matching names. Rejected for two reasons. First, redefining `tools/list` to return a fundamentally different payload shape (no `inputSchema`, no `outputSchema`) under the same method name is a silent backward-compatibility break — every existing client expecting full schemas from `tools/list` would still receive a structurally valid response, but with the schemas they need silently absent. The worst kind of break, because it doesn't error. Second, `list` is a poor name for the catalog-style payload: a method named `list` should return the things themselves, the way `ls` does, not a directory of references-plus-summaries pointing to where the things live. The compact surface is genuinely a catalog, and naming it as such avoids both the compatibility hazard and the semantic mismatch.
261261
3. **Embedding the catalog in `InitializeResult`**. Rejected: catalogs change, and `initialize` is the wrong place to gate the connection on a potentially expensive enumeration.
262262
4. **Reusing `-32602` (Invalid params) for unknown tool names in `tools/describe`**. Rejected: see §3. Conflates resource-availability with request-shape validity, and forces clients to inspect `data` to disambiguate.
263263

0 commit comments

Comments
 (0)