Paginação

Toda tool *_list é paginada por cursor, com o mesmo envelope da API REST.

Parâmetro	Padrão	Máximo
limit	25	100
cursor	—	—

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

limit, cursor e sort só são definidos pelos argumentos nomeados. Um limit acima de 100 é erro de validação, e chaves que a tool não declara (per_page, page, ou um objeto filters que as carregue) são descartadas, nunca repassadas à query.

O resultado da tool carrega:

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

next_cursor é null no fim da coleção; devolva-o como cursor para buscar a próxima página. total é best-effort e é omitido nas listagens quentes, onde contar é caro.

Ordenação

As tools de listagem aceitam sort: chaves separadas por vírgula, prefixo - para descendente.

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

Cada recurso restringe sort aos próprios campos ordenáveis; uma chave desconhecida é erro de validação.

Intervalos de data

Onde uma listagem filtra por tempo, a tool expõe o intervalo como dois argumentos planos — <campo>_gte e <campo>_lte — cada um um timestamp ISO 8601 com offset. Eles são traduzidos para a sintaxe de colchetes da API automaticamente.

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

dica

Um modelo que lê uma página inteira de e-mails gasta contexto com cada linha. Filtre primeiro — por status, inbox_id ou um intervalo de datas — e aumente o limit só quando realmente precisar do volume.