Listing and pagination

The *_list tools use the same pagination as the REST API: by page number.

Argument	Default	Notes
page	1	Starts at 1.
per_page	20	At most 100.
sort_by	varies per resource	A field name in snake_case (due_date, created_at).
sort_order	varies per resource	asc or desc.
include	—	Relations to embed, comma-separated (for example, person).

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

The result carries the usual envelope:

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

When page > total_pages, data comes back empty — that is not an error.

:::tip Sorting by a field the resource does not sort by A sort_by outside the endpoint's list falls back to the default order instead of failing the call. Without an explicit sort_by, do not assume a stable order. :::

:::note Collections that do not paginate A few collections are small and bounded by nature — the latest imports, the asynchronous export jobs, webhook endpoints, negotiation campaigns. They answer with the whole set in data, without meta, and page/per_page do not apply. The tool's description says so. See Pagination and filters in the API documentation. :::

Filters

There is no generic filters argument and no fields projection: each list tool takes its own named filters, the same ones its endpoint accepts in the query string, as plain arguments next to page and sort_by. Some common ones:

Argument	Example	Meaning
status	"pending,overdue"	One status, or several separated by commas
due_date_from / due_date_to	"2026-07-01"	Due-date range, YYYY-MM-DD
person_id	"…"	Only the records of one debtor
search	"Silva"	Text search

The exact list is in each tool's JSON Schema (tools/list) and in the Tools catalogue. Read tools are strict: an argument the tool does not know is a VALIDATION_ERROR that names it — never a filter silently ignored, which would return the wrong rows looking like the right ones.

{ "name": "dunning_charges_list",
  "arguments": { "status": "pending,overdue", "due_date_to": "2026-09-30", "per_page": 100 } }

Data contract

What holds for the v1 API holds here, because it is the same code:

• snake_case everywhere, arguments and responses.
• Money is a float in BRL (reais), in both directions — never cents. amount: 1500.0 is R$ 1,500.00.
• Dates are YYYY-MM-DD in filters and ISO 8601 in responses.
• Writes accept idempotency_key — see Idempotency.