Paginated AI Tools: Completeness Is a Protocol

An assistant is asked to review every open support case for a recurring defect. Its tool returns a convincing list, the model identifies a pattern, and the report describes “all open cases”. The connector actually returned the first page. Nothing in the prose reveals that most of the collection was never examined.

This is not a context-window problem. It is a contract failure between a collection API, its adapter and the application that turns retrieved records into a claim. More tokens cannot retrieve a page that was never requested.

The decision is whether the task needs a bounded view, a complete snapshot, or a continuously maintained copy—and what evidence permits the result to be published. This guide concerns enumerating records, not ranking relevant documents. Provider documentation establishes the protocol facts; the proposed controls and examples are AIEngine's engineering synthesis, not a report of a validated deployment. Sources were checked on 16 September 2026.

Define what “all” is allowed to mean

Start by writing the population in operational terms: which tenant, endpoint, record type, filters, permission context and time boundary? “All customers” might really mean active accounts visible to one service identity. A connector cannot certify the existence of records outside that identity's authorised view.

Then choose the required consistency. A completed traversal means the adapter followed the endpoint's continuation protocol to its terminal condition. A consistent snapshot means the records belong to one coherent source state. Those properties are independent: every page can arrive successfully while the dataset changes between requests.

Do not turn an inspection cap into a population definition after the fact. If the approved task is to review at most 500 recent cases, that is a bounded review and should be labelled accordingly. If the task requires every case, reaching a 500-record budget is a partial outcome.

Keep completeness separate from correctness too. A complete export can contain inaccurate records, and a model can misclassify a perfectly complete export. Record collection coverage, extraction success and analytical quality as separate evidence.

Let the protocol decide when a page chain ends

Google's AIP-158 pagination guidance explicitly permits responses smaller than the requested page size, including zero items, before the collection ends. It uses the continuation token—not result count—as the end signal. The guidance also treats tokens as opaque and requires ordinary authorisation even when a token is supplied.

That distinction belongs in adapter code. A model should not decide to stop because the last page “looks short”, nor invent a new offset from the number of records it remembers.

Slack's pagination documentation makes the same practical warning for cursor-paginated methods: fewer records than the limit does not prove completion; inspect the next cursor. It also warns that cursors expire and should not be retained for hours or days. These are Slack-specific operating constraints, not a universal cursor lifetime.

Treat endpoint documentation as a versioned dependency. An SDK iterator may automatically fetch pages, but the wrapper around it may stop after one iteration, impose its own cap or suppress an exception. Test the behaviour exposed to the agent, not just the provider's example.

An empty terminal page is valid only after a successful, schema-valid response. A missing continuation field caused by failed parsing, an error envelope or a truncated payload must never be interpreted as the provider's end signal.

Freeze the request, not just the cursor

A continuation belongs to a particular query. Preserve its tenant, endpoint, filter, projection, ordering, API version and required headers. Changing the search terms midway creates a different traversal, even if the server happens to accept the old token.

Microsoft's Graph paging guide instructs clients to use the full returned next-link URL rather than extract its skip token and rebuild another request. For directory resources, custom headers such as ConsistencyLevel are not automatically carried into subsequent requests and may need to be supplied explicitly.

A useful adapter stores the original query fingerprint beside the current continuation. The model receives a scan identifier and a progress summary; it does not need raw cursor strings. Keep resumable tokens in access-controlled execution state, with redacted logs or keyed digests where correlation is needed.

Following a returned URL also remains a network-authorisation decision. Accept continuation links only within the connector's approved destination rules, preserve their query semantics, and never forward credentials to an arbitrary host. The connection-authorisation guide explains why an apparently valid link is not sufficient authority to open a connection.

If credentials expire, refresh them only within the approved identity boundary. If permissions or query scope change materially, terminate or restart under a new scan identity rather than silently merging two differently authorised populations.

A stable order does not freeze a moving dataset

For SQL-backed tools, PostgreSQL's LIMIT and OFFSET documentation requires a predictable, unique ordering to obtain consistent subsets. It also notes that the server still computes skipped rows, making large offsets potentially inefficient. Ordering by a non-unique timestamp alone is not a complete ordering rule.

Even a unique order cannot prevent offset positions from shifting when rows are removed between independent requests. Consider this synthetic sequence, using ascending stable IDs and a page size of three:

The adapter can reach the end while missing D, which existed throughout the scan. Removing duplicate IDs cannot recover that omission. The result is also not the final collection, because it still contains A.

Keyset pagination can avoid this particular positional shift by continuing after C rather than skipping three current rows. It still needs a unique ordering tuple and a policy for changes to ordering keys, eligibility and record contents. A cursor may implement keyset traversal, a snapshot or something else; its existence alone proves none of them.

Likewise, a creation-time cutoff does not freeze later edits or deletions. When the report needs one coherent state, require an explicit snapshot or export guarantee. The broader temporal-correctness guide distinguishes source validity from when the system observed it.

Choose the collection mode before scheduling the work

A bounded interactive scan is appropriate for browsing or finding examples, provided the response exposes its cap and does not make exhaustive claims. A best-effort traversal can support exploratory summaries when the observation interval and mutation risk are acceptable. Neither should be quietly promoted into a point-in-time inventory.

A snapshot-backed export is the stronger choice for totals, set comparisons and population-wide checks. Kubernetes' chunked-list protocol illustrates what an actual guarantee looks like: continuation pages preserve the collection's resource version. Its documentation also describes token expiry and HTTP 410 when continuation is no longer available.

That guarantee belongs to the particular API, not to pagination in general. If a snapshot expires, restart a new collection generation when consistency is required. Appending fresh pages to an old partial snapshot cannot produce a single-state result.

Incremental synchronisation solves a different problem: maintaining a local view after an initial collection. Microsoft Graph delta queries distinguish a next link, which continues the current round, from a delta link, which supports later change tracking. The documentation warns that entities can repeat and that clients must handle removed objects.

A delta consumer therefore needs resource-specific merge and deletion semantics, durable checkpoints and a recovery path when tracking state expires. Do not assume every endpoint supports delta, or that a completed round constitutes a historical event ledger. Choose the mode your decision requires, then verify the source actually offers it.

Make page admission and progress recover together

The critical failure window is between accepting records and saving the continuation. If the checkpoint advances before durable admission, a crash can skip data. If records are admitted first but progress is not saved, restarting may replay the same page.

Design the sink and checkpoint together. Where possible, commit a page's accepted records, provenance and successor checkpoint atomically. Otherwise use a durable admission ledger and idempotent writes that make replay safe. Deduplication keys must reflect the intended product: an entity-state mirror and a historical change log need different identities.

Keep retry behaviour inside each provider adapter. Retry the interrupted request under its documented rules, retain the last committed checkpoint, and do not treat a retry-produced token as universally interchangeable. A generic pagination loop should delegate provider-specific continuation handling rather than impose one guessed rule.

Do not have the model emit an external action once per raw record while traversal is still uncertain. Stage proposed actions against admitted identities, then apply the application's completion policy before release. The agent-concurrency guide covers duplicate effects and stale workers; pagination adds the requirement that the input population itself be accounted for.

Give restarts explicit generation IDs. Previously processed pages may be useful for diagnostics, but combining their results with a new generation requires a declared reconciliation policy. The convenient fact that both scans used the same filter does not make their populations identical.

Return a completeness receipt with the analysis

A trustworthy tool result includes records or an aggregate plus a machine-readable account of collection progress. The language model may explain that account; it should not be able to upgrade it.

A practical receipt records:

• Scan identity, connector revision and original query fingerprint.
• Authorised population scope and selected collection mode.
• Snapshot or synchronisation identifier where the source supplies one.
• Observation start, last successful page time and completion time.
• Pages admitted, raw records received, unique entities and duplicate handling.
• Terminal protocol evidence, or the precise reason collection stopped.
• Rejected records, parse failures and unresolved reconciliation items.
• The bounded result location and the policy governing its release.

Counts are useful diagnostics, not universal proofs. A server total may be estimated, measured at another instant or based on a different filter. Only reconcile it as an exact invariant when the endpoint contract supports that interpretation.

Distinguish complete, partial, failed and cancelled states. A successful HTTP response to one page does not decide the scan's state; a scan reaching its terminal page does not decide whether every record was admitted successfully.

Store detailed evidence outside the prompt. A large collection can be aggregated or processed in bounded partitions while the assistant sees the receipt and relevant exceptions. This keeps collection integrity independent of how much text the model can consume.

Test interruptions, then measure coverage honestly

Build a deterministic test endpoint with a known population and scripted mutations. Require the connector to behave correctly when it receives a short nonterminal page, an empty nonterminal page, a repeated continuation, a malformed success response or an expired snapshot.

Exercise the crash on both sides of the admission/checkpoint boundary. Include rate limiting, a lost response after server success, duplicate entities, permission changes and records moving across a filter during traversal. For synchronisation, include removal followed by restoration and a restart before the new checkpoint is durable.

Bound the scan by elapsed time, calls, bytes and records. A repeated token or exhausted budget should produce an explicit partial or failed outcome according to policy, not an endless loop. A cancelled parent should stop further page requests through the cancellation protocol, while already admitted evidence retains its partial status.

Measure omitted and duplicated IDs against controlled snapshot fixtures, crash-recovery correctness, checkpoint lag, restart frequency, and time spent in partial state. Track how often downstream reports or actions are blocked because required completeness evidence is missing. In live best-effort scans without a reference population, report the observability limit rather than invent a recall percentage.

Recheck the contract after connector upgrades, SDK changes, new filters, permission-model changes and source API migrations. The release condition is not that the assistant remembers to ask for another page. It is that the application can demonstrate what population it collected, under what consistency, and why the resulting claim is justified.