Listagem, Ordenação e Campos

As tools *_list usam a mesma paginação da API REST: por número de página.

Argumento	Padrão	Máximo
page	1	—
per_page	20	100

{ "name": "dashboards_portal_users_list", "arguments": { "status": "active", "page": 2, "per_page": 50 } }

O resultado traz o envelope de sempre:

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

Quando page > total_pages, data volta vazio — não é erro.

:::note Coleções que não paginam Algumas coleções são listas de configuração pequenas. Essas respondem o conjunto inteiro e não aceitam page — e a tool correspondente também não oferece o argumento. Isso é intencional: uma tool que anunciasse page numa rota que o ignora faria o modelo paginar para sempre uma lista que não anda. :::

Ordenação

Argumento	Valores	Padrão
sort_by	Nome de coluna em snake_case (created_at, name)	varia por recurso
sort_order	asc ou desc, em qualquer caixa	varia por recurso

{ "name": "dashboards_portal_users_list", "arguments": { "sort_by": "created_at", "sort_order": "asc" } }

Duas regras que valem conhecer, porque são diferentes entre si de propósito:

• Uma coluna que o recurso não ordena cai no padrão. Ordenar por um campo inexistente é um pedido que o servidor não consegue atender, mas também não é motivo para derrubar a chamada inteira; dashboards_schemas_get lista os aceitos em sortable_fields.
• Uma direção que não é direção é 400. sort_order: "descending" é erro, não um desc silencioso — devolver a ordem certa por acidente esconderia o bug até o dia em que o acidente mudasse de lado.

Campos (fields)

Toda tool de leitura aceita fields, um array de nomes de coluna. Omitido, volta o recurso inteiro; informado, volta só aquilo:

{ "name": "dashboards_portal_users_list",
  "arguments": { "status": "active", "fields": ["email", "status", "created_at"] } }

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: ["person"] devolve o objeto aninhado inteiro; não há sintaxe person.name.
Só em leitura	Um create responde com um envelope que o chamador não escolheu; projetá-lo esconderia metade do recibo de uma operação que já aconteceu.
Nome desconhecido é 400	Com a lista do que existe. Ignorar devolveria menos campos do que o pedido, parecendo que o recurso não os tem — resposta errada com cara de certa.

fields é a forma mais barata de reduzir o contexto que um agente gasta: a lista de 300 usuários do portal com três colunas cabe onde a mesma lista completa não caberia.

dashboards_schemas_get — o catálogo de campos

fields só serve se você souber o que pedir, e um modelo que precisa adivinhar vai tentar portal_user.mail_address quando o contrato diz email. dashboards_schemas_get responde isso direto:

{ "name": "dashboards_schemas_get", "arguments": {} }
{ "name": "dashboards_schemas_get", "arguments": { "resource": "portal_user" } }

Sem argumento, devolve o catálogo dos recursos. Com resource, devolve todos os campos daquele recurso — nome, tipo, enum, se aceita nulo, descrição — e, separadamente, os sortable_fields.

Ela vem dos mesmos schemas que geram o OpenAPI publicado, então a lista que a tool reporta e a que esta documentação publica não têm como divergir.

Contrato de dados

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

• snake_case em tudo, argumentos e respostas.
• Datas em ISO 8601, processadas em UTC.
• Escritas aceitam idempotency_key — veja Idempotência.