Paginación

Toda tool *_list está paginada por cursor, con el mismo envelope que la API REST.

Parámetro	Predeterminado	Máximo
limit	25	100
cursor	—	—

{ "name": "emails_list", "arguments": { "limit": 50, "status": "processed" } }

limit, cursor y sort solo se definen por sus argumentos nombrados. Un limit mayor que 100 es un error de validación, y las claves que la tool no declara (per_page, page, o un objeto filters que las lleve) se descartan, nunca se reenvían a la query.

El resultado de la tool lleva:

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

next_cursor es null al final de la colección; devuélvelo como cursor para traer la siguiente página. total es best-effort y se omite en los listados calientes, donde contar es caro.

Ordenación

Las tools de listado aceptan sort: claves separadas por coma, prefijo - para descendente.

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

Cada recurso restringe sort a sus propios campos ordenables; una clave desconocida es un error de validación.

Rangos de fecha

Donde un listado filtra por tiempo, la tool expone el rango como dos argumentos planos — <campo>_gte y <campo>_lte — cada uno un timestamp ISO 8601 con offset. Se traducen a la sintaxis de corchetes de la API automáticamente.

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

tip

Un modelo que lee una página entera de correos gasta contexto en cada fila. Filtra primero — por status, inbox_id o un rango de fechas — y sube el limit solo cuando de verdad necesites el volumen.