Skip to main content

Pagination

Every *_list tool is cursor-paginated, with the same envelope as the REST API.

ParameterDefaultMax
limit25100
cursor——
{ "name": "emails_list", "arguments": { "limit": 50, "status": "processed" } }

limit, cursor and sort are set only through their named arguments. A limit over 100 is a validation error, and keys a tool does not declare (per_page, page, or a filters object carrying them) are dropped, never forwarded to the query.

The tool result carries:

{
  "data": [ /* ... */ ],
  "meta": {
    "next_cursor": "eyJ...",
    "total": 142
  }
}

next_cursor is null at the end of the collection; pass it back as cursor to fetch the next page. total is best-effort and is omitted on the hot listings, where counting is expensive.

Sorting​

List tools accept sort: comma-separated keys, - prefix for descending.

{ "name": "agent_runs_list", "arguments": { "sort": "-created_at", "limit": 10 } }

Each resource restricts sort to its own sortable fields; an unknown key is a validation error.

Date ranges​

Where a listing filters by time, the tool exposes the range as two flat arguments — <field>_gte and <field>_lte — each an ISO 8601 timestamp with offset. They are translated to the API's bracket syntax for you.

{ "name": "emails_list",
  "arguments": { "received_at_gte": "2026-09-01T00:00:00Z", "received_at_lte": "2026-09-07T23:59:59Z" } }
tip

A model reading a full page of e-mails spends context on every row. Filter first — by status, inbox_id or a date range — and raise limit only when you actually need the volume.