An agent asked to find one customer, deployment, or invoice often reaches for a broad list endpoint. The tool returns hundreds of full records; the model scans fields it did not ask for and carries them into later turns. It can confuse similar entries or act on a detail visible only in an unrelated record.
The practical move is to make collection access a list-then-inspect workflow. A list tool returns a small, bounded index: stable IDs, short labels, status, and only the fields needed to choose what to inspect. It also returns an opaque continuation token when more results exist. A separate get tool retrieves the complete record only after the agent names one ID and explains why it is relevant.
Google’s pagination guidance notes that collections can grow without bound, increasing lookup time and response size; it specifies an optional page size, a continuation token, and an empty next token at the end of a collection.[1] Microsoft likewise treats collections and individual items as separate resources, so a client can retrieve a specific item after inspecting a collection.[2] For an agent, that separation creates a clean decision boundary: select an ID first; reason from its record second.
Return an index, not a disguised database dump
Treat a collection response as a navigation surface. It should answer: What candidates exist in this authorized scope, and what can I safely inspect next? It should not try to answer every possible future question in one payload.
For tickets, selection fields may be ticket_id, title, status, and updated_at; for deployments, ID, environment, status, commit, and timestamp. Do not include message bodies, payment details, internal notes, credentials, or nested objects merely because they are easy to serialize.
Stable IDs beat display names. Keep lists small enough to compare deliberately, and preserve the scope filter that produced them. A short list is not permission to inspect a different account, page forever, or invoke a write tool.
Copy this list-then-inspect contract
Put this boundary around any tool that exposes a potentially large collection to an agent.
LIST TOOL: list_[resource]
INPUT
- scope: [tenant, project, folder, time range, permissions]
- filters: [allowlisted fields only]
- page_size: [small bounded maximum]
- page_token: [opaque token from this exact prior query or null]
RETURN
{
"ok": true,
"scope_ref": "[stable authorized scope]",
"items": [
{
"id": "[stable resource ID]",
"label": "[short human-readable label]",
"selection_fields": {"status":"...", "updated_at":"..."}
}
],
"returned_count": 0,
"next_page_token": "[opaque token or null]",
"partial": false,
"next_safe_action": "inspect_named_item | continue_same_list | stop"
}
INSPECT TOOL: get_[resource]
INPUT
- id: [one ID returned by the current list or otherwise authorized]
- fields: [small allowlist for the decision]
RULES
1. List before inspect when the target is unknown.
2. Inspect by stable ID, never by a model-reconstructed label.
3. Keep page_token opaque; do not parse, edit, or use it as authorization.
4. Continue only the same scope and filters with a token.
5. Before a consequential write, re-read the named record and use its current
version or other concurrency guard.
The continuation token is a cursor, not an instruction to enumerate everything. A list call can legitimately return fewer items than requested, and it may provide a next token when more data might exist.[1] Make that incompleteness visible. An agent that has inspected one page should say it searched one page, not claim it found every matching record. If the question requires exhaustive coverage, give the workflow an explicit page limit, deadline, and completion rule; otherwise it can loop until context or budget is gone.
Fetch only the decision-shaped fields
A full record is sometimes necessary, but even get should not default to “all fields.” Ask which facts the next decision actually needs. To decide whether a ticket can be reassigned, the agent may need current assignee, status, priority, and a version token—not the customer’s entire history. To explain a deployment failure, it may need status, logs for one attempt, and a release ID—not the logs for every deployment in the project.
Microsoft cautions that large, unneeded objects increase latency and bandwidth, while many tiny resources can become chatty.[2] Use a deliberate middle: enough candidate metadata to choose, then only the named-record fields needed to reason.
Record the scope, filters, candidate ID, and selection reason. A later turn can re-fetch that named record rather than trust a stale list.
Failure mode: pagination that silently changes the search
Pagination can create a subtle correctness error when an agent changes filters, sort order, tenant, or time range between pages. A later token may no longer represent the same candidate set. Google’s guidance says other parameters should remain the same when a client continues with a page token, and says tokens must be opaque and must not authorize resource access.[1]
Bind the original scope and filters to the cursor server-side, reject altered continuations, and expire cursors rather than letting them become permanent state. Also do not treat a list snapshot as proof a selected record is still current. Between list and inspect, another user can change or remove it. Re-read before acting, preserve authorization checks on every call, and keep the final write guarded by the record’s current version.
The habit to keep
give an agent a small map before you give it a file cabinet. Let it choose a stable ID from a bounded list, inspect the one record that earned attention, and make any claim about coverage match the pages it actually read.