Tracking: collection tools discard continuation or hide incomplete results #485

Scope

Track the collection-pagination contract work across packages. Several tools return one backend page while discarding the only continuation token or any indication that more items exist. Intentional one-page behavior is valid when the caller can understand completeness and use the supported continuation contract.

This tracking issue groups the recurring symptom. Each package retains its own request/result shape, compatibility decisions, and validation. Package tasks may be implemented in separate PRs or split into linked issues when the response-contract decision warrants it.

Package work checklist

• Database: oci-database-mcp-server: 63 page-oriented tools discard continuation tokens #481 — 63 page-accepting handlers discard header tokens.
• Limits: oci-limits-mcp-server: pagination ignores limit and discards the resume token #439 — explicit-page paths discard the following token; existing limit semantics are per page.
• Logging: search_logs accepts page but returns SearchResponse without opc-next-page. Real FastMCP/SDK response reproduction confirmed loss.
• Object Storage: list_buckets, list_objects, list_object_versions. Objects drop next_start_with; versions hardcode request limit=25 and lose the header token. Public tool reproductions confirmed both losses.
• Monitoring: list_alarms and list_metric_definitions expose first-page results with no continuation path.
• Usage: get_summarized_usage returns first-page summary items only.
• Cloud Guard: list_problems has a bounded default request and loses continuation/completeness. Define its bounded collection contract explicitly.
• Support: list_incident_resource_types accepts page but discards the response token. list_incidents already handles the normal total-cap traversal; do not include it in the cap-overrun issue.
• DBTools: list_autonomous_databases, list_all_databases, list_dbtools_connection_tool, list_all_connections, object_storage_list_buckets, object_storage_list_objects; six inventory paths omit later pages/continuation.
• MySQL: list_all_compartments, object_storage_list_buckets, object_storage_list_objects; name lookup is separately tracked in Name resolution examines only the first OCI page in DBTools, IoT, and MySQL #479.
• IoT: _map_many loses metadata for six registered list interfaces without a page-envelope alternative: instances, domain groups, domains, work-request errors, logs, and requests. Preserve the documented legacy-array compatibility decision. Adapters/models/relationships already have *_page alternatives; they are not additional defects solely for returning one page.
• Recovery: list_restore and list_backups with aggregate_pages=False stop after one response and return items only. Restore page branch can return [] after local filtering while more pages remain; backup page branch likewise loses continuation. Derived-scope enumeration is separately tracked in oci-recovery-mcp-server: database inventories and latest-backup summaries omit later pages #480.
• Cloud result completeness: oci-cloud-mcp-server: capped summaries and collection envelopes hide incomplete results #478 — default summary and full collection modes suppress known truncation.

Contract and regression criteria

• Define whether each tool aggregates, returns one page, or intentionally returns a bounded sample.
• Distinguish complete, capped, and partial/error outcomes; return supported continuation where promised.
• Inspect actual backend item/token adapters: raw list, .items, .results, and Object Storage .objects with next_start_with → start. Mapping .data alone can discard required metadata.
• Preserve filters, ordering, and query scope. Do not reuse one backend cursor across unrelated fan-out queries.
• A cap cutting inside a backend page must not advertise a following-page token that skips the unreturned remainder.
• Test normal/empty continuation through real production conversion and MCP response serialization.
• Treat default/result-schema changes as package-specific compatibility work; this issue does not require a universal envelope or new shared helper.

Related work

• OCI collection tools can exceed total result limits across eight MCP servers #476: total-cap overruns, a distinct issue.
• oci-cloud-mcp-server: pagination dispatch rejects valid scalar and collection responses #477: pagination selection/native shape errors.
• Name resolution examines only the first OCI page in DBTools, IoT, and MySQL #479: incomplete name-resolution candidate sets.
• oci-recovery-mcp-server: database inventories and latest-backup summaries omit later pages #480: derived inventory and latest-backup calculations.

Verification scope

The source audit covered 34 MCP components. Token-loss reproductions executed actual function bodies for the Database family and representative remaining paths; public MCP calls additionally verified Logging search and Object Storage response loss. Some IoT interfaces share a source-verified helper and were not all independently replayed. These records are evidence for the listed scope, not whole-repository compliance certification.

Evidence and limits

Source examined at 3a7cfd9623ec97ad7c365b9b77f28e459aefca8c; OCI SDK 2.185.1. The audit executed production pagination logic with mocked service boundaries and synthetic responses. Broad logic checks used AST-extracted function bodies with client/conversion plumbing mocked; selected cases also exercised actual FastMCP calls and real SDK response models. No live-backend correctness or full-repository coverage claim is made. Source links below pin the examined revision.

Conditional follow-ups

• Follow-up: guard collection pagination against repeated or cyclic continuation tokens #482: repeated/cyclic token defenses, based on synthetic upstream responses.
• oci-pricing-mcp-server: relative pagination links are resolved against the host root #483: relative Pricing next-link resolution, without verified live link-format occurrence.
• Follow-up: establish ordering and completeness for bounded IoT recent/latest samples #484: ordering/completeness of bounded IoT recent/latest samples, requiring a backend guarantee.