Large MCP results: return a useful summary without flooding model context

A large MCP result should provide enough inline evidence for the immediate task while keeping bulk data behind a separately authorized retrieval contract. Bound rows and bytes, label truncation, and return a summary plus a resource reference only when the supported host can use it. structuredContent is server result data; it is not a guarantee that the model generated or validated a particular structured answer.

Budget the result for the question

Start with what the user needs to decide. A synthetic report with thousands of rows may require a count, reporting interval and three relevant exceptions rather than every underlying record. Define the inline limit in bytes or tokens as well as row count because one free-text row can be large. Include scope, generation time, applied filters and a completeness indicator so a summary cannot be mistaken for the entire dataset.

The MCP tools specification describes text content, structured content and resource-related result forms. Host behavior and supported revision determine which forms are useful in practice. Verify resource reading, not merely schema acceptance. A server can construct a valid reference that the current host never follows, leaving the user with an inaccessible report.

MCP tools specification: structured results and resource references

Define the synthetic report envelope

For an illustrative monthly exception report, return a bounded summary containing the selected period, total row count, exception count and a few representative IDs. The resource reference resolves the authorized full report. Use a fictional URI in design material and keep its scheme consistent with the mechanism your server actually implements; a custom URI is not automatically a public download endpoint.

{
  "reportId": "fixture-report-7",
  "period": "2026-10",
  "rowCount": 2400,
  "inlineRows": 3,
  "completeInline": false,
  "summary": "Three selected exceptions are shown.",
  "resourceUri": "report://fixture-report-7"
}

The numbers are synthetic inputs, not observed customer volume or a performance result. Three selected rows must not imply only three exceptions exist; expose the actual selection rule and total exception count when those values are known. If the report is pending, return that state rather than an empty completed summary. If a count is unavailable, say unknown instead of making a model infer it from the sample.

Resource access is another authorization boundary

Authorize creation and later reads separately. A member removed after generation should receive the behavior promised by the resource policy. Define expiry, retention, content type, maximum size and whether the artifact is immutable. If the reference ultimately becomes a signed storage URL, account revocation and URL expiry are separate considerations. Avoid embedding bearer capabilities in routine logs or durable chat summaries when a renewable report identifier is sufficient.

A missing or expired resource needs a recovery path: recheck access and regenerate or renew where permitted, return a clear expired state otherwise. Do not silently substitute another user's report with the same display name. Keep report identity tied to tenant scope, parameters and generation version. Caching by report label alone is insufficient when two workspaces can request a report for the same month.

Test the host and the fallback

Use synthetic rows to test a host that can read the resource and one that cannot. The fallback should still answer the bounded question or explain how an authorized user can obtain the full artifact. Measure the actual serialized inline size after encoding; estimating from database row count misses text expansion, duplicated text representations and metadata. Validate both text and structured forms when the server returns both so they cannot disagree about completion.

No resource server or host experiment is executed in this guide. The envelope is a proposed interface contract. Before publishing a compatibility claim, verify the exact SDK, revision, host retrieval behavior and expiry handling. Keep full report generation outside the model's immediate context where that fits the workflow, while preserving enough inline evidence to make the assistant's answer inspectable.

LLM structured output validation

Evaluate the tool action, not just the answer.

Bring one tool workflow, supported hosts and a sanitized failure trace for a scoped AI integration review.

AptixLabs ai agent development