Listado y paginación

Las tools de listado usan la misma paginación de la API REST: por número de página. Los argumentos son los mismos parámetros de la query string de la API, en snake_case, en el mismo objeto plano que el resto de los argumentos.

Argumento	Valores	Por defecto
page	entero, desde 1	1
per_page	entero, máximo 100	20
sort_by	nombre del campo en snake_case (due_date, created_at)	varía por recurso
sort_order	asc o desc	varía por recurso
include	relaciones a traer junto (por ejemplo, person)	ninguna

{ "name": "dunning_charges_list",
  "arguments": { "status": "overdue", "page": 2, "per_page": 50,
                 "sort_by": "due_date", "sort_order": "asc", "include": "person" } }

El resultado trae el envoltorio de siempre:

{
  "data": [ /* ... */ ],
  "meta": { "total": 142, "page": 2, "per_page": 50, "total_pages": 3 }
}

Cuando page > total_pages, data vuelve vacío — no es un error.

Un sort_by que no está en la lista del endpoint cae al orden por defecto: ordenar por un campo que el recurso no ordena es un pedido que el servidor no puede atender, pero no es motivo para tumbar la llamada.

:::note Colecciones que no paginan Algunas colecciones pequeñas y limitadas por naturaleza — importaciones, jobs de exportación, endpoints de webhook, campañas de negociación — devuelven el conjunto entero en data, sin meta, igual que en la API REST. Ve Paginación y filtros de la API. :::

Filtros

No hay un argumento genérico de filtros ni de proyección de campos: cada tool de listado acepta los filtros nombrados de su endpoint, como argumentos más del mismo objeto. Algunos ejemplos de dunning_charges_list:

Argumento	Ejemplo	Significado
status	"pending,overdue"	Uno o más status, separados por coma
due_date_from / due_date_to	"2026-07-01"	Rango de vencimiento, en YYYY-MM-DD
person_id	"…"	Solo los cobros de un deudor
search	"Silva"	Búsqueda por texto

Cada tool anuncia sus argumentos en el JSON Schema que devuelve tools/list; son los parámetros del endpoint correspondiente, documentados en la referencia de la API — el catálogo de Tools dice qué endpoint refleja cada tool. Las lecturas son estrictas: un argumento que la tool no conoce es VALIDATION_ERROR, y el error nombra la clave — así un filtro con el nombre equivocado no vuelve, en silencio, la lista entera.

Contrato de datos

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

• snake_case en todo, argumentos y respuestas.
• El dinero es float en BRL (reales), en ambos sentidos — nunca centavos. original_amount: 1500.5 es R$ 1.500,50.
• Fechas en ISO 8601, en UTC; los filtros de fecha usan YYYY-MM-DD.
• Las escrituras aceptan idempotency_key — ve Idempotencia.

Gastando menos

Un agente paga contexto por cada fila que trae. Filtra antes de paginar: dunning_charges_list con status: "overdue" y due_date_to cuesta una solicitud; recorrer todos los cobros para filtrar en el modelo cuesta decenas — y gasta el límite de solicitudes.