An AI agent should not say it checked every record until its retrieval process has demonstrated completion for the requested scope. Many APIs return a page of results and a continuation reference. If a tool wrapper hides that reference, the model can produce a convincing summary of a small subset while believing it has seen the whole collection.
The fix belongs mainly in the retrieval contract. Keep the query scope stable, follow the endpoint's documented continuation mechanism, preserve failures and tell the agent whether collection is complete or partial. This guide explains what that evidence should contain and how to test it. The examples are proposed integration tests, not measurements of a particular production service.
- 01Define the populationKeep account, permissions, filters and date boundaries with the result.
- 02Use the actual continuation ruleFollow provider-issued links or cursors under the endpoint contract.
- 03Expose partial resultsA budget stop or failed page must not become a success claim.
- 04Check the model's input tooComplete retrieval can still be truncated before the model sees it.
01 — ScopeDefine what all means #
Before collecting records, write down the population the task concerns. Account, organization, date range, status, permissions and filters can all change the answer. “All open issues” is incomplete if the system has several repositories or excludes records the service account cannot see. Retrieval can be complete relative to one query while still missing the user's intended scope.
Preserve the query parameters with the result. If an agent is asked to summarize work completed last month, record the exact start and end boundaries and the relevant time zone. Changing a filter halfway through collection creates a mixed population that cannot be interpreted simply by counting the returned rows. The scope is part of the evidence, not incidental request metadata.
Distinguish inaccessible data from absent data. A permission-limited response may be correct for the authenticated identity while incomplete for the user's broader question. Our document-permission guide explains the access boundary. The pagination check starts after that boundary has been identified; it does not prove the account has authority to see every record in the organization.
- Preserve the query, account and permission scope.
- State exclusions before using words such as all or every.
02 — ContinuationFollow the provider's contract #
Pagination is the practice of returning a collection in successive pages. The next page may be identified by a cursor, token, URL or header. A cursor is usually an opaque continuation value: the client should use it under the provider's rules rather than infer its meaning or rebuild it from a row count.
Microsoft Graph's paging documentation instructs clients to follow the returned @odata.nextLink until it is absent, using the entire URL rather than extracting and repurposing its skip token. GitHub's REST guidance instead describes navigation through Link headers, including a next relation where another page exists. The examples show why a universal “increment page number” wrapper is unreliable.
Treat continuation references as endpoint data within a trusted integration. Preserve authentication and required headers according to the provider's documentation, and constrain requests to the expected service. Do not let arbitrary text in a record become a new request destination. The model should receive records and retrieval status, while the integration controls how the next page is fetched.
| Editorial integration comparison based on Microsoft Graph and GitHub pagination documentation checked October 13, 2026. Endpoint-specific rules take precedence. | ||
|---|---|---|
| Mechanism | What the integration preserves | What it must not assume |
| --- | --- | --- |
| Next-page URL | Complete provider-issued continuation URL | That a token can be copied into a different query |
| Opaque cursor | Cursor plus the same collection scope | That cursor contents are meaningful page numbers |
| Link header | The documented next relation | That a last-page link is always available |
| Explicit page number | Provider rules for page size and termination | That every API uses this mechanism |
03 — TerminationProve completion explicitly #
Stopping after a short page is safe only when the endpoint documents that as its completion rule. Some services can return fewer records than requested while still providing continuation. Likewise, an empty page is not universally the end of a collection. Base termination on the selected API's actual contract and preserve the observed completion signal.
A tool should return a status such as complete, partial or failed, together with the evidence behind it. Useful fields include pages fetched, unique records retained, whether continuation remains and the last error. These are not substitutes for provider semantics, but they make the retrieval process inspectable instead of hiding it behind a large list.
If a time or cost budget stops collection, return the records already obtained with a partial status. The agent can still answer a bounded question about them or request more collection. It must not silently convert a budget stop into a completed census. A clear partial answer is more useful than an exhaustive-sounding conclusion based on an unknown fraction of the data. A clean tool response should say whether retrieval finished. The absence of an exception is not evidence that every page was fetched.
04 — ConsistencyAccount for a moving collection #
Records can change while a client is paging through them. New items may appear, old items may disappear and sort positions may move. Whether the API provides a stable snapshot, consistent cursor or only a live view depends on the endpoint. Preserve that distinction in the result instead of assuming the pages describe one frozen moment.
Use stable record identifiers to detect duplicates, but do not treat deduplication as proof against omissions. Removing a repeated row repairs one symptom; it cannot recover a row that was skipped while the collection changed. If the task needs a point-in-time inventory, use a documented snapshot or export mechanism where available, or state the limitation of a live traversal. A hypothetical project audit might collect open tasks while another team closes them. The final set can be a useful observation over the collection interval without being the exact state at either endpoint of that interval. Record the start and finish times, and avoid precise point-in-time claims unless the service's consistency model supports them.
One documented collection state
Use the provider's snapshot guarantees and retain the snapshot identity. Verify that the whole traversal uses the same state.
Records can change during collection
Preserve stable IDs, deduplicate where needed and keep possible omissions or state changes explicit. Deduplication alone does not create a snapshot.
05 — RecoveryResume without changing the question #
A failed page should not erase evidence of the pages already retrieved, nor should it turn the collection into a success. Preserve the last confirmed continuation state and the stable query definition. Retry under the provider's documented rules, taking account of rate limits, token expiry and any restrictions on reusing a continuation value.
After a long , the original continuation may no longer be valid or the collection may have changed substantially. The correct response may be to restart a documented snapshot or perform a new collection, not to invent a replacement cursor. Keep the old partial result distinguishable from the new attempt so the agent cannot merge incompatible runs and call them one complete answer.
Retries also need duplicate handling at the result-assembly layer. A request can succeed while the response is lost, leading the client to fetch an overlapping page again. Stable IDs help reconcile those records. The broader principle in preventing duplicate agent work applies here too: recovery should preserve the identity of the intended operation.
- Keep confirmed progress and errors together.
- Do not merge restarted collections without an explicit reconciliation rule.
06 — SummariesSeparate retrieval from context limits #
Fetching every record does not mean every record fits into one model request. A tool may complete pagination and then truncate its output before returning it to the agent. That creates a second completeness boundary. Report both: the collection completed, but the model received a selected or summarized representation.
For large collections, use deterministic aggregation where possible and preserve a way to inspect the underlying records. A count by status should come from the complete retrieved set, not from the model estimating how many rows it remembers. If summaries are produced in batches, retain the batch boundaries and ensure the final aggregation does not count an overlapping record twice. The agent's final answer should distinguish a complete computation from a sample-based observation. It can say that a finding came from reviewed examples without claiming it holds across the entire population. The related distinction between retrieval quality and ranking quality appears in our reranker diagnosis guide; a sophisticated model cannot compensate for missing candidates it never received.
Track what was fetched, what was retained and what was shown to the model as separate quantities. They answer different completeness questions.
07 — FixturesPlace a decisive record later #
Design a controlled test collection where the fact needed to answer the question appears beyond the first page. Keep its expected result outside the agent's visible input. If the agent answers correctly only when the decisive record moves to the first page, the pipeline has exposed a retrieval defect rather than a reasoning limitation.
Add a duplicate across adjacent pages, a documented empty-page continuation case if the endpoint supports it, and an interruption before the final page. Test that partial results remain labelled partial and that retrying does not inflate counts. These fixtures should reproduce the provider contract rather than invent behavior the production API never exhibits.
Also test the output boundary: allow complete retrieval, then limit the tool's returned text. The application should preserve the full data or a verified aggregate and tell the model what representation it received. A passing test that bypasses the actual tool wrapper says little about a wrapper that drops continuation or truncates results in production.
- Put answer-changing evidence beyond the first page.
- Test interrupted collection and output truncation independently.
08 — ReportingMake the coverage claim reviewable #
A useful retrieval receipt identifies the scope, collection interval, continuation rule, completion status and unresolved errors. Keep sensitive request values out of public logs, but preserve enough information internally to reproduce the query. The final user-facing answer can be concise while the supporting record remains available for review.
For example, report “all records returned for this account and filter were collected” only when that is what the evidence proves. Do not broaden it to “all company records” if permissions or retention limits exclude part of the population. If the source offers only approximate totals, label them as such rather than using them as exact reconciliation targets. In AI transformation projects, this is a small integration detail with a large effect on trust. The model should not have to infer whether its tools finished reading. Give it a clear contract, test that contract with decisive later-page evidence and keep the final answer proportional to the scope actually collected.
- State the completed scope and any known exclusions.
- Retain a retrieval receipt behind exhaustive claims.
Require evidence before saying every record
Keep scope, continuation and completion visible in the tool response. Then verify that the complete result survives aggregation and context limits before the agent makes an exhaustive claim.