Before an AI agent reports “all overdue requests” or “no matching issues,” check whether its tool retrieved the full relevant result set. A successful response may contain only the first page. The integration should preserve the query scope, expose any continuation marker and make an interrupted or capped retrieval distinguishable from a completed one.
This is a developer and workflow-owner problem as much as a prompting problem. If the tool hides that more records exist, the model has little basis for qualifying its answer. This guide proposes a retrieval record and evaluation cases for that boundary. Its maintenance-queue example is fictional; we have not run an agent, API integration or benchmark for this article.
A successful request can return an incomplete collection
GitHub’s REST pagination documentation explains that large collections are returned as subsets and that additional pages can be requested through links in the response headers. It also documents limits on page size. Increasing a supported page-size parameter does not, by itself, establish that the whole collection was retrieved.
For an agent-facing tool, the important question is what survives the integration. The underlying API might return a next-page link while a wrapper forwards only record titles. A developer inspecting the HTTP response would see the continuation signal; the agent inspecting the wrapper’s output would not.
Anthropic’s September 2025 engineering guidance on tools recommends pagination, filtering, range selection or truncation to control large responses, with helpful instructions when truncating. This is vendor practitioner guidance, not independent evidence that any particular wrapper prevents omissions. Our recommendation is to expose both the records and the conditions under which they were obtained.
Define what the tool can enumerate
Start with the distinction between an enumerable collection and a relevance-ranked search. A list endpoint may let a client traverse every record matching specified filters. A search service may return only its top matches or impose a separate result cap. The latter cannot automatically support an exhaustive claim merely because the agent has consumed everything returned.
Write the scope in operational terms: which workspace or repository, which status, which date field and interval, and which records the integration’s identity can access. “All” should refer to that defined scope. It should not silently expand to records in other workspaces, inaccessible projects or unsearched archives.
Keep the scope stable while following pages. If a later call changes the status filter, it is a different query. Combining those results without recording the change can produce a collection that corresponds to neither request. When a service supplies continuation links or tokens, use its documented mechanism rather than reconstructing a presumed next page.
A zero-result response also needs context. “No matches in the completed query for this repository and interval” is a narrower statement than “none exist.” Authentication failures, unsupported filters and retrieval errors should remain errors rather than being converted into empty lists.
Preserve a small retrieval record alongside the rows
For a fictional maintenance report, suppose an agent must identify every overdue open request in one queue at a defined cutoff. Here, the tool lists open requests across pages, and the workflow applies the due-date check after retrieval. A proposed integration record would retain the following information independently of the prose summary.
| Record field | Why it matters | Example meaning |
|---|---|---|
| Scope and filters | Defines what the report can cover | One maintenance queue, open status, agreed due-date cutoff |
| Continuation state | Shows whether traversal remains unfinished | Next-page marker present or documented end reached |
| Unique record identifiers | Supports deduplication and inspection | Distinct request IDs retained across pages |
| Retrieval limits and errors | Prevents a cap from looking like completion | Call budget reached or a page request failed |
| Observation time | Qualifies a changing collection | Retrieval interval, with snapshot status if supported |
These are proposed concepts, not universal API field names. Follow the actual service contract. A connector might exhaust pages internally and return a completion flag; another might require the caller to request each page. The workflow needs to know which behavior it receives.
Prefer deterministic collection handling in the integration when practical. Following continuation markers, deduplicating by stable IDs and recording errors do not need to be reinvented in generated prose. The agent can interpret the collected information while the integration makes the retrieval status explicit.
Keep protocol discovery separate from business-data pagination
The MCP specification dated 25 November 2025 defines opaque cursors and continuation through nextCursor for listed discovery operations, including tools/list and resources/list. Clients must not assume a fixed page size or parse and modify those cursor tokens.
That does not mean every business tool called through MCP uses the same pagination fields. Discovering a tool and invoking it to list maintenance requests are different operations. The request-listing tool needs its own documented result contract. Do not infer that a missing nextCursor means business-data retrieval is complete unless that is what the invoked tool actually promises.
This distinction matters when reviewing an integration labeled “MCP compatible.” Protocol support alone does not establish that a business query is exhaustive. Inspect the tool’s input and output definitions and verify how its wrapper represents partial results.
Challenge the final page and the stopping condition
Use fixtures with known records before trusting an exhaustive report. In an invented two-page example, the first page contains 25 requests and the final page seven more. Place the only overdue qualifying request on the final page. The expected collection contains 32 unique records, and the final answer must include that request. These numbers specify a proposed test; they are not observed API results.
Then interrupt the second request. The expected outcome is a partial report or a visible retrieval failure, not “no overdue requests.” Repeat with an explicit call-budget limit so the workflow proves it can stop honestly without looping indefinitely.
Other useful cases include an overlapping record across pages, a completed empty query and a truncated response with no usable continuation route. Check both the collection and the final wording. Correctly recording “partial” internally does not help the reader if the generated report still says it checked everything.
The ToolSandbox research paper, revised in April 2025, evaluates tool use through stateful, interactive trajectories and intermediate and final milestones. It is Apple-authored research, not a pagination benchmark or proof about today’s agents. Its evaluation design offers a relevant distinction: inspecting the path and state can reveal more than checking whether an isolated call was well formed. The pagination fixtures here are our proposed application of that principle.
Qualify completeness when the underlying data can change
Reaching the documented end of pagination establishes a traversal result under the service’s guarantees. It does not create a frozen snapshot if the service does not provide one. Requests could be added, removed or updated while the report is being collected.
For consequential reports, check whether the API offers snapshot semantics, a supported stable ordering or another documented consistency mechanism. Record what it actually guarantees. A time filter alone should not be described as a snapshot if records can still change within that interval.
Set a reasonable retrieval budget and define the output when it is exhausted. A bounded partial result can still be useful if its scope and missing coverage are clear. Exhaustive work may instead require a supported export, a narrower query or a different reporting path. Do not ask the model to compensate for inaccessible data with a more confident summary.
Our long-document coverage guide addresses a different boundary: whether supplied material supports the requested report. With paginated tools, first establish which records reached the workflow at all. Review one recurring “all records” claim, inspect its continuation and stopping behavior, and keep that evidence attached to the report before expanding the workflow.