MCP tool results that overflow the context window

Symptom: the agent reports a count that is too low, or acts on a partial list

An agent asked to audit, tag or delete across a media library calls a listing tool on the Asset Management MCP server, gets a result, and proceeds. Nothing errors. But the number of assets it reports is a fraction of what the console shows, or the last item it names is one it never finished describing.

Likely cause

A listing call returns a result proportional to the library. The MCP tools specification defines a tool result as content the server returns; nothing in the protocol caps that content at what the client can hold. A server that lists 40,000 resources will happily emit 40,000 resources. The context window is the client’s problem, and the server has no way to know how much of it is left.

Check

Run the same listing directly against the Admin API with the same parameters the tool used, and compare the count of items in the raw response to the count the agent reported. If the raw response is larger, the tool did not fail — the client dropped part of it.

On the Free plan, keep in mind the 500 Admin API requests per hour limit while you reproduce; a listing you repeat in a loop to check counts eats that budget quickly.

Fix

Do not try to make the client hold more. Make the call return less — see the last section.

Symptom: valid-looking JSON that ends mid-object, or a tool call that succeeded but the model’s next step is nonsense

Likely cause

An oversized result is truncated by the client rather than rejected. The model receives whatever fit, with no marker that anything was cut. Truncated JSON read as complete is worse than an error: an error stops the run and tells you why; a truncated list looks like an answer, and the agent builds its next action on it. A deletion or bulk-tag step that runs against half a list is the expensive version of this.

Check

Inspect the raw tool result in the client’s transcript or debug log rather than the model’s summary of it. Look at the tail: an object missing its closing brace, an array with no closing bracket, or a next_cursor that never appears although the item count is suspiciously round. If the client exposes a token or byte count per tool result, compare it against the client’s documented result limit. The general procedure for pulling apart a wrong result is on diagnosing a failing MCP tool call.

Fix

Treat any listing result whose tail is malformed as incomplete, and stop the run before any write. Then reduce the request size, below.

Symptom: it worked yesterday, and it worked on the first call today, but not the third

Likely cause

The failure is intermittent by nature, because whether a result fits depends on how much context the conversation had already consumed before the call. A fresh session with one server connected has room for a large listing; the same listing forty turns later, after several other tool results and with several MCP servers connected at once, does not. Nothing about the call changed. The headroom did.

Check

Reproduce the call in a fresh session and in a long one, same parameters. If the fresh session returns a complete result and the long one does not, the result size is fixed and the available context is the variable. That rules out the server and the API and points at the request size.

Fix

Size every listing call for the worst case — a nearly full window — not for the fresh session where you tested it. That means the same two changes as above.

The fix: ask for less, on two axes

Row count. Pagination parameters exist on the underlying API. The Admin API listing methods take max_results and return next_cursor when more remains; the Search method does the same, with max_results and next_cursor on the response. An MCP tool that wraps these calls passes the parameters through, so set max_results explicitly on every listing call and loop on the cursor. A page that fits is a result the model can actually read; a cursor is a signal that more exists, which is exactly what a truncated result lacks.

Field selection. This matters as much as row count. Most listing calls return far more per item than the task needs — a full resource record when the agent wanted a public ID and a byte size. The Search method lets you name the fields you want back with fields, and the per-item payload shrinks accordingly. Fifty rows of two fields fit where five rows of forty do not.

If a workflow genuinely needs to walk a whole library, the honest comparison is whether it should be an MCP tool call at all rather than a scripted REST loop: a script has no context window, and pagination there is a for loop, not a prayer that the client leaves enough room.