If you are building MCP tools and still returning entire result sets, you are setting yourself up for silent failure. The recent analysis from DEV.to highlights a critical infrastructure reality: when an MCP tool returns a large payload, the practical limits are not abstract concepts. They are hard walls defined by transport frame sizes, model context windows, and client memory. The result? Your agent either hits a transport error or, worse, acts on a truncated list as if it were complete.

The Silent Killer: Context Window Degradation

The most dangerous failure mode isn't the crash; it's the quiet confusion. As the source notes, the model is not a database, and the MCP transport is not a bulk file channel. When you dump everything into the working context, the model competes with other prompt elements for attention. Past a certain size, marginal records actively reduce reasoning quality. In production, this manifests as the agent summarizing only the first page, missing a record that fell past the cut, or retrying a call that is fundamentally too large for the current context window.

Design for Cursors, Not Offsets

The fix is architectural: design your tool for pagination from the start. The recommended contract includes a bounded page size, an opaque cursor, and a hasMore flag. Why opaque cursors over simple offsets? Because data changes. If rows are inserted or deleted between requests, an offset silently skips or duplicates records. A cursor anchored to the last seen record remains stable, ensuring the agent walks the full set reliably without data integrity issues.

Make Truncation Explicit

Sometimes you cannot paginate cleanly, such as when wrapping a fixed blob like a log file. In these cases, do not just cut the string. Attach metadata that explicitly states the result was truncated and provide a continuation path. The tool schema must describe these fields so the model knows the shape it will receive. A vague schema leads agents to invent their own pagination logic or assume a partial list is exhaustive, which is a recipe for hallucination.

Key Takeaways

  • Transport frames and context windows are hard limits; respect them by bounding every response.
  • Silent truncation causes agents to treat partial lists as complete; always use explicit hasMore flags.
  • Use opaque cursors instead of offsets to handle mutable data sets safely.
  • Document truncation metadata in the tool schema so clients and agents can rely on stable interpretations.

The Bottom Line

Moving design problems into the model's context is the least reliable way to handle data. Build bounded, self-describing tools so your agents can fetch data deliberately rather than guessing at what they missed.