AI Tool Pagination: Prove Results Are Complete

“I found no inactive accounts” sounds definitive. It may mean the assistant examined every account, or it may mean no inactive accounts appeared in a single page returned by a tool. Those are different findings, and the tool needs to make the difference visible.

Pagination failures often survive a demonstration because the test data fits on one page. Build the completeness behaviour before increasing the dataset or allowing the assistant to produce audit-style conclusions.

Put the claim in scope

Decide whether the tool performs a search, returns a sample or enumerates a collection. A relevance search normally answers a different question from a complete inventory. Do not call a top-ranked set “all matching documents” unless the underlying operation establishes that coverage.

For a paginated enumeration, expose the records, whether more pages remain, the continuation mechanism and any limit that stopped collection. If the wrapper handles pagination internally, return a completion status and the scope it actually covered.

Useful scope fields include the applied filter, source account, start and end times, and number of distinct records observed. A count is evidence about the run, not automatically the source's authoritative total.

The MCP tool design guide covers the broader interface. Pagination needs an equally deliberate contract because it changes what conclusions the assistant can support.

Respect each API's continuation rules

Microsoft Graph's paging documentation instructs clients to use the complete @odata.nextLink URL for the next request. A page can be empty and still have a next link. Relevant custom headers may need to be reapplied. Rebuilding the URL from an assumed page number can change the query or lose required state.

The MCP pagination specification uses opaque cursors for protocol list operations, including listing tools and resources. It does not automatically paginate the business records returned inside an arbitrary tool result. Your tool's implementation must define that behaviour separately.

Amazon S3's ListObjectsV2 reference uses IsTruncated and NextContinuationToken. A continuation token is opaque; it is not an object key. Grouped prefixes also affect how listings should be interpreted. A wrapper that only copies the objects from the first response can quietly omit much of a bucket.

Keep provider-specific continuation logic in the integration layer. Giving an assistant a token does not mean it should decode or alter it. If a token is invalid or expires, report the failed continuation and follow the source's documented recovery procedure.

Bound the work without hiding the boundary

A complete scan can be expensive or slow. Set sensible limits for pages, elapsed time and returned records. When a limit is reached, the result should say that collection is incomplete and explain why.

An assistant can then report: “I checked the records returned within the current limit; the remaining pages have not been examined.” It should not convert that into a clean bill of health. For a business process that requires full coverage, queue a background enumeration and hold the conclusion until it finishes.

Consider what happens while the source changes. Pagination by itself does not promise a frozen snapshot. Record the observation window and use a documented snapshot or export mechanism if the task needs point-in-time accuracy. Deduplicate by stable record identifier, and decide how changed revisions are handled.

Never infer completion merely because the latest page is shorter than the requested size. Use the API's documented end condition. That keeps the wrapper correct when providers choose variable page sizes or apply filtering during enumeration.

Test the second page and the awkward middle

Create a synthetic collection larger than the page boundary. Put the record that should trigger the important finding near the end. Then exercise a first page with no matches, an empty intermediate page with continuation, a repeated record, an invalid cursor and a failure on a later request.

Check the final wording as well as the integration output. A correctly flagged partial result is still a failed user experience if the model summarises it as a complete search.

Compare a successful enumeration against a trusted export or a known test manifest. Account for legitimate source changes rather than silently accepting any difference. Keep raw pagination diagnostics within the technical logs, while showing the user the meaningful scope and remaining work.

Release the wrapper behind a narrow feature switch. During the first runs, retain the existing manual inventory route. If the new collector cannot demonstrate coverage, return to that route and fix the continuation behaviour before making its findings authoritative.

References

• Microsoft, Paging Microsoft Graph data. Accessed 17 October 2026.
• Model Context Protocol, Pagination, specification dated 18 June 2025. Accessed 17 October 2026.
• Amazon Web Services, ListObjectsV2 API reference. Accessed 17 October 2026.