Listado, Orden y Campos

Las tools *_list usan la misma paginación de la API REST: por número de página.

Argumento	Predeterminado	Máximo
page	1	—
per_page	20	100

{ "name": "billing_invoices_list", "arguments": { "status": "open", "page": 2, "per_page": 50 } }

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.

:::note Colecciones que no paginan Algunas colecciones son conjuntos hijos limitados por construcción (los ítems de un plan, los intentos de una NF-e) o listas de configuración pequeñas. Esas responden el conjunto entero y no aceptan page — y la tool correspondiente tampoco ofrece el argumento. Es intencional: una tool que anunciara page en una ruta que lo ignora haría que el modelo paginara para siempre una lista que no avanza. :::

Orden

Argumento	Valores	Predeterminado
sort_by	Nombre de columna en snake_case (due_date, created_at)	varía por recurso
sort_order	asc o desc, en cualquier caja	varía por recurso

{ "name": "billing_invoices_list", "arguments": { "sort_by": "due_date", "sort_order": "asc" } }

Dos reglas que vale conocer, distintas entre sí a propósito:

• Una columna que el recurso no ordena cae al predeterminado. Ordenar por un campo inexistente es un pedido que el servidor no puede atender, pero tampoco es motivo para tumbar la llamada entera; billing_schemas_get lista los aceptados en sortable_fields.
• Una dirección que no es dirección es 400. sort_order: "descending" es error, no un desc silencioso — devolver el orden correcto por accidente escondería el bug hasta el día en que el accidente cambiara de lado.

Campos (fields)

Toda tool de lectura acepta fields, un array de nombres de columna. Omitido, vuelve el recurso entero; informado, vuelve solo eso:

{ "name": "billing_invoices_list",
  "arguments": { "status": "open", "fields": ["number", "total", "due_date"] } }

Regla	Por qué
id siempre vuelve	Una proyección que no puedes seguir no sirve de nada, y quitar el id en silencio rompería la llamada siguiente, no esta.
Solo el nivel de arriba	fields: ["billing_account"] devuelve el objeto anidado entero; no hay sintaxis billing_account.name.
Solo en lectura	Un create responde con un envoltorio que el llamador no eligió; proyectarlo escondería la mitad del recibo de una operación que ya ocurrió.
Un nombre desconocido es 400	Con la lista de lo que existe. Ignorarlo devolvería menos campos de los pedidos y parecería que el recurso no los tiene — respuesta equivocada con cara de correcta.

fields es la forma más barata de reducir el contexto que gasta un agente: la lista de 300 facturas con tres columnas cabe donde la misma lista completa no cabría.

billing_schemas_get — el catálogo de campos

fields solo sirve si sabes qué pedir, y un modelo que tiene que adivinar intentará invoice.amount cuando el contrato dice total. billing_schemas_get responde eso directamente:

{ "name": "billing_schemas_get", "arguments": {} }
{ "name": "billing_schemas_get", "arguments": { "resource": "invoice" } }

Sin argumento devuelve el catálogo de recursos. Con resource, devuelve todos los campos de ese recurso — nombre, tipo, enum, si acepta nulo, descripción — y, por separado, sus sortable_fields.

Viene de los mismos esquemas que generan el OpenAPI publicado, así que la lista que reporta la tool y la que publica esta documentación no pueden divergir.

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, en ambos sentidos, sin sufijo de unidad. amount: 100 es R$ 100,00; los campos de precios aceptan hasta 4 decimales.
• Fechas en ISO 8601, procesadas en UTC.
• Las escrituras aceptan idempotency_key — ve Idempotencia.