Listado, Filtros y Campos

Las tools *_list usan la misma paginación que la API REST: por cursor.

Argumento	Predeterminado	Máximo
limit	25	100 (10000 en las tools *_ids)
cursor	—	—

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

El resultado trae el envoltorio de siempre:

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

Para la página siguiente, envía el meta.next_cursor como cursor, con los mismos filtros. next_cursor: null significa que esta es la última página. Ver Listado y paginación en la API.

Filtros

filters es un objeto con exactamente los filtros que acepta el listado — el inputSchema de la tool los enumera, con los operadores de cada uno. Un filtro u operador fuera de la lista se rechaza antes de llegar al endpoint. Paginación, orden y columnas (limit, cursor, sort_by, sort_order, fields — y page, per_page y sort, de otras APIs) son argumentos nombrados: dentro de filters se rechazan con VALIDATION_ERROR, que nombra las claves, y nunca sobrescriben el argumento.

Forma	Significa	Se convierte en
"status": "pending"	igual a	?status=pending
"status": ["pending", "paid"]	está en	?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"
  } }

La gramática completa está en Filtros y ordenación.

Ordenación

Argumento	Valores	Predeterminado
sort_by	Una de las columnas por las que ordena el listado (el inputSchema las lista)	varía por recurso
sort_order	asc o desc	asc

Campos (fields)

Las tools de lectura de registros aceptan fields, un array de nombres de columna. Omitido, vuelve el registro entero; informado, vuelve solo eso:

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

Regla	Por qué
id siempre vuelve	Una proyección que no puedes seguir no sirve, y quitar el id en silencio rompería la llamada siguiente, no esta.
Solo el primer nivel	fields: ["reconciliation"] devuelve el objeto entero; no existe la sintaxis reconciliation.kind.
Solo en lectura de registros	Las escrituras devuelven el registro entero; totales, *_ids y descarga no ofrecen el argumento.
Un nombre desconocido es error	400 con details.unknown y details.available. Ignorarlo devolvería menos campos que los pedidos, como si el registro no los tuviera.

Es el mismo ?fields= de la API. Y es la forma más barata de reducir el contexto que gasta un agente.

finance_schemas_get — el catálogo de campos

fields solo sirve si sabes qué pedir. finance_schemas_get responde con los schemas del contrato publicado:

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

Sin argumento, devuelve el catálogo; con schema, los campos de ese schema — nombre, tipo, enum, si acepta nulo y descripción. Es el mismo OpenAPI que genera la Referencia de la API.

Contrato de datos

Lo que vale para la API vale aquí, porque es el mismo código:

• snake_case en todo, argumentos y respuestas.
• El dinero es un número en BRL, con hasta 2 decimales: 1500.5 es R$ 1.500,50. Títulos y movimientos son siempre positivos — la dirección viene del tipo, no del signo.
• Fechas en ISO 8601.
• Las escrituras aceptan idempotency_key — ver Idempotencia.