Listagem, filtros e campos

As tools *_list seguem o mesmo contrato e devolvem o mesmo envelope. A paginação é por cursor, não por número de página.

Há exceções: as listagens de catálogo (banking_core_provider_list, banking_financial_provider_list e banking_financial_statement_category_list) não têm argumentos, e as de extrato (banking_financial_statement_transaction_list) e de eventos (banking_data_event_list) não aceitam sort_by.

Argumento	O que faz
filters	Objeto com os filtros que a listagem declara. Veja abaixo.
sort_by	Coluna de ordenação, entre as que a listagem aceita
sort_order	asc ou desc. Padrão asc quando há sort_by
limit	Itens por página. Padrão 25, máximo 100
cursor	O meta.next_cursor da página anterior
fields	Os campos a devolver. Veja abaixo.

{ "name": "banking_charge_bank_billet_list",
  "arguments": {
    "filters": { "status": ["opened", "overdue"], "expire_at": { "lt": "2026-11-01" } },
    "sort_by": "expire_at", "sort_order": "asc", "limit": 50,
    "fields": ["amount", "expire_at", "status"] } }

O resultado traz a página e o cursor da próxima:

{
  "data": [ { "uid": "6f1c…", "amount": 149.9, "expire_at": "2026-10-20", "status": "overdue" } ],
  "meta": { "next_cursor": "eyJfcmFpbHMiOnsi…" }
}

Paginação por cursor

Para a próxima página, mande o meta.next_cursor como cursor, com os mesmos filters, sort_by e sort_order. next_cursor: null é a última página.

• O cursor é opaco e selado. Ele é cifrado e autenticado: não dá para ler, editar nem montar um à mão. É uma posição na listagem, não um número de página para fazer conta.
• O cursor fica preso à consulta que o gerou. Mudar os filtros ou a ordenação e reaproveitar o cursor é recusado com unprocessable. Para mudar a consulta, comece de novo sem cursor.
• Não há total. A listagem não conta os registros: ela busca uma linha a mais do que o limit para saber se existe próxima página. Contar uma fatia filtrada de uma tabela com dezenas de milhões de linhas custaria mais que a página.

Filtros

Cada listagem declara os seus filtros, e o inputSchema da tool descreve cada um com o tipo, os operadores e os valores aceitos. A forma do valor escolhe o operador:

Valor	Significado	Exemplo
Escalar	Igualdade	{ "status": "overdue" }
Array	Um entre vários (in)	{ "status": ["opened", "overdue"] }
Objeto	Operadores explícitos	{ "expire_at": { "gte": "2026-10-01", "lt": "2026-11-01" } }

Os operadores são eq, in, not, gte, lte, gt e lt, e cada filtro aceita só alguns deles. not inclui os registros em que o campo está vazio, porque "diferente de X" os contém.

• Datas vão em YYYY-MM-DD. Numa coluna de data e hora, uma data vale pelo dia inteiro.
• Valores em dinheiro vão em reais (149.90).
• Referências a outro registro vão pelo uid.
• Filtro ou operador que a listagem não declara é recusado, nunca ignorado. Ignorar devolveria mais registros do que o pedido, com cara de resposta certa.

Ordenação

sort_by aceita só as colunas que a listagem declara, e a mensagem de erro lista as aceitas. Sem sort_by, os mais recentes vêm primeiro. sort_order sem sort_by é recusado.

Campos (fields)

As listagens e as tools *_get aceitam fields, um array de nomes de campo. Omitido, volta o registro inteiro; informado, volta só aquilo:

Regra	Por quê
uid sempre volta	Uma resposta sem uid não serve para a chamada seguinte.
Só o nível de cima	Nomear um campo que é objeto devolve o objeto inteiro.
Nome desconhecido é erro	A mensagem lista os campos disponíveis. Ignorar devolveria menos campos que o pedido, parecendo que o registro não os tem.

fields é a forma mais barata de reduzir o contexto que um agente gasta: a lista de 100 boletos com três campos cabe onde a mesma lista completa não caberia.

Contrato de dados

• Só uid. Argumentos que referenciam um registro se chamam <recurso>_uid (ou <recurso>_uids) e aceitam só UUID. As respostas não trazem id numérico: um campo <recurso>_id sai substituído por <recurso>_uid, ou é omitido quando o registro referenciado não tem uid.
• Dinheiro em reais, como número (149.9).
• Datas em YYYY-MM-DD, e data e hora em ISO 8601.