Skip to content

REQ-F-018: Pagination Metadata on List Commands

Tier: Framework-Automatic | Priority: P0

Source: §5 Pagination & Large Output

Addresses: Severity: High / Token Spend: High / Time: High / Context: Critical

Description

The framework MUST automatically inject a pagination object into the response envelope for every command declared as a list command. The pagination object MUST always contain: total (total count if known, or null), returned (count of items in this response), truncated (boolean), has_more (boolean), and next_cursor (opaque string token, or null if no more results). This metadata MUST be present even when the result is a complete set (with truncated: false).

Acceptance Criteria

  • Every list command response includes a pagination key at the top level of the envelope
  • When results are truncated, truncated: true and next_cursor is non-null
  • When results are complete, truncated: false and next_cursor is null
  • Passing next_cursor from response N as --cursor in the next call returns the subsequent page

Schema

Types: response-envelope.md

The pagination object is injected at the top level of the envelope alongside data, meta, error, and warnings:

{
  "pagination": {
    "total":       "<integer or null>",
    "returned":    "<integer>",
    "truncated":   "<boolean>",
    "has_more":    "<boolean>",
    "next_cursor": "<string or null>"
  }
}

Wire Format

List command response with pagination metadata (partial result):

{
  "ok": true,
  "data": [
    { "id": "user-1", "name": "Alice" },
    { "id": "user-2", "name": "Bob" }
  ],
  "pagination": {
    "total": 47,
    "returned": 20,
    "truncated": true,
    "has_more": true,
    "next_cursor": "eyJsYXN0X2lkIjoidXNlci0yMCJ9"
  },
  "error": null,
  "warnings": [],
  "meta": {
    "request_id": "req_04EF",
    "command": "list-users",
    "timestamp": "2024-06-01T12:00:00Z"
  }
}

Complete result (truncated: false):

{
  "pagination": {
    "total": 3,
    "returned": 3,
    "truncated": false,
    "has_more": false,
    "next_cursor": null
  }
}

Example

Framework-Automatic: no command author action needed beyond declaring the command as a list command. The framework injects the pagination object into every response.

$ tool list-users
→ pagination.total: 47, pagination.returned: 20, pagination.truncated: true

$ tool list-users --cursor eyJsYXN0X2lkIjoidXNlci0yMCJ9
→ pagination.total: 47, pagination.returned: 20, pagination.truncated: true

$ tool list-users --cursor eyJsYXN0X2lkIjoidXNlci00MCJ9
→ pagination.total: 47, pagination.returned: 7, pagination.truncated: false, pagination.next_cursor: null
Requirement Tier Relationship
REQ-F-019 F Composes: default limit drives the returned and truncated values in this object
REQ-F-004 F Provides: response envelope that the pagination key extends
REQ-F-021 F Enforces: pagination is framework-volatile; it MUST NOT be placed in data
REQ-C-015 C Provides: list command declaration that triggers automatic pagination injection