mcp: define semantic pagination and transport limits for math.find

[morluto]

Decision

Define what should bound math.find discovery pages, relationship collections, and exact capability inspection. In particular, decide whether the current 16 KiB serialized-response threshold has a justified role or should be replaced by semantic pagination plus operator-owned transport limits.

Confirmed history

The 16 KiB value is Jacobian policy, not an MCP requirement.

• PR #140 introduced CAPABILITY_DISCOVERY_RESPONSE_BYTE_LIMIT = 16_384 specifically to bound capability discovery to 20 matches and 16 KiB. The preceding integration assertion allowed 128 KiB.
• Neither the PR nor the commit records a host limit, benchmark, token-budget study, SDK constraint, or transport measurement supporting 16 KiB.
• Review of PR #899 exposed the danger of broadening that threshold: applying it to exact CONTRACT/FULL inspection made an ordinary polynomial.expression.normalize FULL descriptor exceed the advertised limit, even though the documented FULL contract promises the complete output schema and provider metadata.

The existing measurement is also not a transport ceiling. It measures a selected JSON projection, not the complete JSON-RPC envelope and not both MCP result channels. It is not a model-context ceiling either: serialized UTF-8 bytes do not map consistently to tokens, and hosts can consume structuredContent, text content, or both.

MCP Python SDK evidence

Jacobian pins mcp==2.0.0 and mcp-types==2.0.0.

The current SDK documentation and the installed 2.0.0 source show:

• typed/Pydantic tool returns are validated against the output schema and serialized into structuredContent;
• tool results may include ResourceLink values for separately readable data;
• cursor pagination is supported for MCP list operations;
• Streamable HTTP has a configurable incoming request-body limit, defaulting to 4 MiB;
• no corresponding SDK-level outgoing tool-result limit was found.

References:

• MCP Python SDK v2 structured output
• MCP Python SDK v2 Streamable HTTP manager
• MCP cursor pagination
• MCP tool results and ResourceLink
• RFC 9110 field limits

Current limitation

One byte threshold is being asked to solve three different problems:

1. keep broad discovery useful and inexpensive;
2. prevent an unbounded related_capabilities collection;
3. protect transports and hosts from oversized messages.

Those have different semantics and recovery requirements.

A deterministic suffix truncation with a boolean indicator prevents growth, but it is not a complete collection protocol. Without a cursor or canonical relationship resource, omitted relationships are not recoverable. Conversely, CONTRACT and FULL are exact projections: truncating or rejecting them at an arbitrary byte boundary changes their promised meaning.

Desired outcome

Separate product-level collection bounds from deployment-level transport safeguards.

• Keep discovery page-oriented, with a stable opaque cursor and explicit total/truncation metadata. Prefer an item/page contract; retain a byte guard only if measurements establish a separate need.
• Make related_capabilities a recoverable collection: paginate it with an opaque cursor or link to a canonical MCP resource. Expose total count and continuation rather than only truncated: true.
• Preserve complete CONTRACT/FULL semantics. If a descriptor should not remain inline, return a small typed projection plus a ResourceLink to the exact complete descriptor instead of silently dropping schema data.
• Treat request/response transport ceilings as operator configuration. They should fail clearly at the transport boundary and should not masquerade as mathematical discovery semantics.
• Document any retained numeric default with evidence from supported hosts/transports and representative catalog sizes.

Success criteria

• Every omitted discovery match or relationship has a deterministic recovery path with no omissions or duplicates across pages.
• CONTRACT and FULL remain validation-equivalent/complete as documented, or their exact canonical resource is explicitly returned.
• Tests cover stdio and Streamable HTTP, structured and text projections, Unicode-heavy metadata, large schemas, and large relationship sets.
• The documented limit model distinguishes request-body protection, response transport policy, collection pagination, and model-context selection.
• No limit is attributed to MCP or the Python SDK unless the cited SDK/protocol contract actually defines it.

Non-goals

• Removing all server resource bounds.
• Returning the entire capability catalog inline in every search.
• Treating every large value as an artifact regardless of whether it needs durable identity.
• Prescribing how an agent should compose mathematical capabilities.