Listagem, Filtros e Campos

As tools *_list usam a mesma paginação da API REST: por cursor.

Argumento	Padrão	Máximo
limit	25	100 (10000 nas tools *_ids)
cursor	—	—

{ "name": "finance_payables_list", "arguments": { "limit": 50 } }

O resultado traz o envelope de sempre:

{
  "data": [ /* ... */ ],
  "meta": { "next_cursor": "eyJpZCI6Mn0" }
}

Para a próxima página, mande o meta.next_cursor como cursor, com os mesmos filtros. next_cursor: null significa que esta é a última página. Veja Listagem e paginação na API.

Filtros

filters é um objeto com exatamente os filtros que a listagem aceita — o inputSchema da tool os enumera, com os operadores de cada um. Um filtro ou operador fora da lista é recusado antes de chegar ao endpoint. Paginação, ordenação e colunas (limit, cursor, sort_by, sort_order, fields — e page, per_page e sort, de outras APIs) são argumentos nomeados: dentro de filters são recusados com VALIDATION_ERROR, que nomeia as chaves, e nunca sobrescrevem o argumento.

Forma	Significa	Vira
"status": "pending"	igual a	?status=pending
"status": ["pending", "paid"]	está em	?status[in]=pending,paid
"due_date": { "gte": "2026-11-01", "lt": "2026-12-01" }	operadores	?due_date[gte]=…&due_date[lt]=…

{ "name": "finance_payables_list",
  "arguments": {
    "filters": { "company_id": "…", "status": "pending", "due_date": { "lte": "2026-11-30" } },
    "sort_by": "due_date", "sort_order": "asc"
  } }

A gramática completa está em Filtros e ordenação.

Ordenação

Argumento	Valores	Padrão
sort_by	Uma das colunas que a listagem ordena (o inputSchema lista)	varia por recurso
sort_order	asc ou desc	asc

Campos (fields)

As tools de leitura de registro aceitam fields, um array de nomes de coluna. Omitido, volta o registro inteiro; informado, volta só aquilo:

{ "name": "finance_payables_list",
  "arguments": { "filters": { "status": "pending" }, "fields": ["description", "amount", "due_date"] } }

Regra	Por quê
id sempre volta	Uma projeção que você não consegue seguir não serve para nada, e derrubar o id em silêncio quebraria a chamada seguinte, não esta.
Só o nível de cima	fields: ["reconciliation"] devolve o objeto inteiro; não há sintaxe reconciliation.kind.
Só em leitura de registro	Escritas devolvem o registro inteiro; totais, *_ids e download não oferecem o argumento.
Nome desconhecido é erro	400 com details.unknown e details.available. Ignorar devolveria menos campos que o pedido, com cara de que o registro não os tem.

É o mesmo ?fields= da API. E é a forma mais barata de reduzir o contexto que um agente gasta.

finance_schemas_get — o catálogo de campos

fields só serve se você souber o que pedir. finance_schemas_get responde com os schemas do contrato publicado:

{ "name": "finance_schemas_get", "arguments": {} }
{ "name": "finance_schemas_get", "arguments": { "schema": "PayableV1" } }

Sem argumento, devolve o catálogo; com schema, os campos daquele schema — nome, tipo, enum, se aceita nulo e descrição. É o mesmo OpenAPI que gera a Referência da API.

Contrato de dados

O que vale para a API vale aqui, porque é o mesmo código:

• snake_case em tudo, argumentos e respostas.
• Dinheiro é número em BRL, com até 2 casas: 1500.5 é R$ 1.500,50. Títulos e lançamentos são sempre positivos — a direção vem do tipo, não do sinal.
• Datas em ISO 8601.
• Escritas aceitam idempotency_key — veja Idempotência.