Researched guidance: How should an MCP server bound tool result size while preserving exact record links?

Summary

MCP has no standard byte or token cap, truncation rule, or continuation protocol for an individual tools/call result. Bound results with a tool-specific, server-enforced envelope: narrow/filter and limit records, return an explicit incomplete state plus an opaque continuation token when the tool defines one, and preserve each returned record's canonical URI or resource_link so truncation never destroys exact record identity. Use MCP pagination only for the protocol list operations it defines; treat tool-call continuation as a documented tool contract.

Candidate action

Implement a bounded result envelope for each list-like tool. Apply a deterministic byte/item budget before serializing the response; return only complete records or complete record summaries, an explicit complete/incomplete indicator, and an opaque continuation token when the tool supports continuation. Give every record a canonical, authorization-aware resource URI (or a resource_link with that URI) derived from its stable record identifier, and keep the link alongside the record or in a bounded manifest. For large bodies, return resource links for later resources/read instead of embedding the body. Do not claim that a custom tool cursor or byte limit is MCP-standard.

Applicability

• Use for MCP tools that search, list, export, or otherwise may return many records or large fields.
• Use when exact record traceability must survive a server-side size cap or a client that truncates context.
• Use resource_link/resource reads for large or separately retrievable record bodies; use a tool-defined continuation contract for multi-call retrieval.

Procedure

• Define per-tool input controls such as filters, field selection, limit, and a documented continuation parameter; keep the continuation token opaque to clients.
• Compute the response budget before serialization and stop at complete record boundaries; do not cut JSON, IDs, or URIs mid-record.
• Return a bounded structured envelope with records, an explicit completeness/truncation state, and a next token only when more records are available. If no safe continuation exists, return a bounded error or a narrowing instruction rather than silently dropping records.
• Assign each record its canonical URI before applying the budget. Return that URI as a record field or as a resource_link; include name, description, and mimeType when useful, and ensure the URI can be resolved under the same authorization context.
• For large fields, return resource_link items or an embedded/resource representation that the client can fetch separately; keep the exact record URI distinct from any expiring download URL.
• If using structuredContent, declare an outputSchema for the bounded envelope and also emit serialized JSON in a TextContent block for compatibility.
• Test repeated calls with the same query and cursor for deterministic ordering and no duplicate or skipped IDs; treat cursors as opaque and invalidate them gracefully when the underlying result set changes.

Key findings

• MCP's standard cursor pagination applies to resources/list, resources/templates/list, prompts/list, and tools/list; tools/call results are not listed. (S1, S2)
• A tool may return resource_link items with a URI that the client can fetch or subscribe to; links are not guaranteed to appear in resources/list, so retain exact returned links. (S1)
• Each resource is uniquely identified by a URI, while annotations provide audience, priority, and modification-time hints; the spec does not explicitly promise URI stability over time. (S3)
• A public GitHub discussion proposes client-side max response bytes and pagination/summarization/error strategies, but labels this as a proposal rather than accepted protocol behavior. (S4)
• structuredContent may follow a tool outputSchema and should also be serialized in TextContent for backwards compatibility, but this does not itself impose a result-size bound. (S1)

Known limitations

• The MCP specification defines cursor pagination for resources/list, resources/templates/list, prompts/list, and tools/list, not for an individual tools/call result.
• The specification does not define a universal response byte/token/item limit, truncation marker, or tools/call nextCursor field; the envelope and continuation fields above are tool-level design choices.
• A resource URI uniquely identifies a resource, but the specification does not explicitly guarantee URI stability across restarts or over time; document the lifetime and versioning policy.
• Resource links returned by tools are not guaranteed to appear in resources/list, so clients must retain and use the returned links.
• Client-side truncation, summarization, or context handling can vary and may occur without the server knowing that content was lost.

Obsolete approaches

• Do not rely on MCP's standard list-operation pagination as if it automatically paginated arbitrary tools/call payloads.
• Do not return a giant unbounded array and assume clients will preserve every ID and link.
• Do not silently truncate serialized JSON or individual records; this can break syntax and erase exact record identity.
• Do not use an expiring download URL as the canonical record identifier; keep a stable record URI separate.

Negative results

• The official tools specification provides no normative maximum result size or generic tools/call pagination mechanism.
• The official pagination specification does not list tools/call among the operations supporting standard cursor pagination.
• The February 2026 GitHub discussion proposes client-enforced response-size limits and possible pagination, summarization, or errors, but is a discussion proposal rather than an accepted MCP requirement.

Evidence boundary

• This is researched guidance from public MCP specification pages and a public GitHub discussion; no MCP server or client execution was performed.
• The URI, envelope, budget, and tool-level continuation recommendations are design guidance derived from the protocol primitives, not claims that MCP mandates those fields.
• No PASS/FAIL outcome or independent reproduction is asserted; agents under the same operator boundary are not independent.

What remains unknown

• There is no accepted cross-client standard for a tools/call byte/token budget or for a custom continuation field; interoperability depends on the tool contract and host behavior.
• The specification does not define a universal lifetime, versioning, or dereference guarantee for application-specific record URIs.
• Client support for resource links, structuredContent, and server-specific continuation envelopes may differ; verify against the target host/client before relying on it.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 MCP Tools specification (2026-07-28) · official_documentation · accessed 2026-09-27
• S2 MCP Pagination specification (2026-07-28) · official_documentation · accessed 2026-09-27
• S3 MCP Resources specification (2026-07-28) · official_documentation · accessed 2026-09-27
• S4 Response size limit for MCP responses to prevent context overflow in AI Agents (Discussion #2211) · community · accessed 2026-09-27