# Referência de tools

As ferramentas que valem em todos os marketplaces conectados. O marketplace vem da conta que você indicar.

Quais marketplaces oferecem cada uma está na [matriz de disponibilidade](/referencia/matriz).

As ferramentas se dividem em quatro classes de cobrança:
**grátis** (meta/status — não contam na cota), **leitura**, **agregação**
(fan-out computado no servidor) e **escrita** (auditadas; as arriscadas
exigem confirmação).

Em **Retorno**, `chave?` só aparece em certas condições, `[]` é lista e o
que vem marcado como ML é dado do Mercado Livre repassado sem transformação.

## Agregação (respostas computadas)

### `aggregate_orders`

Agrega pedidos server-side: faturamento (gmv), pedidos, unidades,
ticket médio, tarifas, por período/status/agrupamento. 1 chamada = 1
resposta computada (ex.: 'faturamento pago dos últimos 7 dias').

**Exemplo de pedido ao agente:** “Qual foi meu faturamento de pedidos pagos nos últimos 7 dias, dia a dia?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `date_from` | string | sim |  |
| `date_to` | string | sim |  |
| `date_field` | string | não | `closed` |
| `status` | array/null | não |  |
| `group_by` | array/null | não |  |
| `metrics` | array/null | não |  |
| `top_n` | integer | não | `20` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ range{from, to, field}, status_filter[],
  totals{…métricas pedidas: count, gmv, units, avg_ticket, sale_fee_total, net,
         cancelled_rate},
  currency, _pages_scanned, _truncated?,
  groups[]?{key, …métricas pedidas, share}, group_by? }
 · groups e group_by só aparecem quando group_by é informado (usa a primeira dimensão; groups limitado a top_n)
```

### `claims_open_summary`

Reclamações abertas: total, agrupamentos e as acionáveis com prazo.

**Exemplo de pedido ao agente:** “Resuma minhas reclamações abertas por motivo e por etapa.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `group_by` | array/null | não |  |
| `include_actionable` | boolean | não | `True` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ total_open, by_<dimensão>{<valor>: contagem}, actionable[]?{claim_id, type, stage, mandatory_action, due_date}, soonest_due_date? }
 · uma chave by_<dimensão> por item de group_by (type, stage, reason_id, status; padrão: by_type e by_stage) · actionable e soonest_due_date só com include_actionable=true
```

### `query`

Consulta genérica (DSL) sobre orders, order_items, items, questions,
claims — filtros, group_by (com bucket day/week/month) e agregações
(sum/count/avg/min/max/count_distinct) computadas no servidor.
Use describe_query_schema para o catálogo completo.

**Exemplo de pedido ao agente:** “Agrupe meus pedidos pagos do trimestre por status e some o valor de cada grupo.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `entity` | string | sim |  |
| `select` | array/null | não |  |
| `filter` | object/null | não |  |
| `group_by` | array/null | não |  |
| `aggregate` | array/null | não |  |
| `sort` | array/null | não |  |
| `limit` | integer/null | não |  |
| `budget` | object/null | não |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ entity, rows[]{…}, _meta{upstream_calls, rows_scanned, truncated, returned} }
 · sem aggregate: cada linha tem os campos de select (padrão: todos os campos da entidade) · com aggregate: cada linha tem os campos de group_by + uma chave por agregação (nome em "as", ou <op>_<field>, ou <op>)
```

### `rank_items`

Ranqueia anúncios por gmv/unidades/visitas/conversão no período.

**Exemplo de pedido ao agente:** “Quais são meus melhores anúncios por faturamento no mês, e quais convertem pior?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `date_from` | string | sim |  |
| `date_to` | string | sim |  |
| `by` | string | não | `gmv` |
| `status` | array/null | não |  |
| `limit` | integer | não | `20` |
| `direction` | string | não | `desc` |
| `include` | array/null | não |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ ranked[]{item_id, title, gmv, units, sale_fee, price, available_quantity, health,
           permalink, visits?, conversion?, revenue_per_visit?, _error?, value},
  basis, range{from, to}, _pages_scanned, _truncated? }
 · visits, conversion e revenue_per_visit só quando by é visits, conversion ou revenue_per_visit · _error na linha quando a leitura de visitas daquele anúncio falhou
```

### `reputation_summary`

Reputação enquadrada nos thresholds de cor do site + distância do
rebaixamento + reclamações abertas.

`distance_to_downgrade` é medida sobre a taxa de reclamações (`claims_rate`) até o teto da faixa `green`; a métrica e o limite vêm da enum `reputation_thresholds` do adaptador do marketplace, não da API do marketplace, e podem mudar sem aviso. É uma conta sobre as suas próprias métricas, não uma previsão.

**Exemplo de pedido ao agente:** “Estou perto de perder o nível de reputação? Compare com os limites da plataforma.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `include_open_claims` | boolean | não | `True` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ level_id, power_seller_status, transactions<objeto ML>, metrics<objeto ML>, claims_rate,
  distance_to_downgrade, protected, real_level, protection_end_date, open_claims? }
 · open_claims só com include_open_claims=true (null se a leitura falhar)
```

### `visits_rollup`

Rollup de visitas (janela ≤150d; contorna a regra 1-id-por-chamada).

**Exemplo de pedido ao agente:** “Some as visitas dos meus anúncios de janeiro e mostre os que mais atraíram público.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `date_from` | string | sim |  |
| `date_to` | string | sim |  |
| `item_ids` | array/null | não |  |
| `group_by` | string/null | não |  |
| `top_n` | integer | não | `20` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ range{from, to}, total_visits, by_day[]?<lista ML>, by_item[]?{item_id, visits, _error?}, _items_scanned }
 · by_day só com group_by="day" sem item_ids · by_item só quando item_ids é informado (limitado a top_n) · sem nenhum dos dois: só range, total_visits e _items_scanned
```

## Leitura

### `get_claim`

Reclamação composta (post-purchase v1).

**Exemplo de pedido ao agente:** “Mostre os detalhes da reclamação 5200012345.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `claim_id` | integer | sim |  |
| `include` | array/null | não |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ …<objeto ML> (GET /post-purchase/v1/claims/{claim_id}), actions_history?, status_history?, affects_reputation?, messages? }
 · cada chave de include carrega a resposta do ML daquele recurso, ou {_error} se a leitura falhar · include="detail" não acrescenta chave
```

### `get_item`

Busca 1..N anúncios com projeção de campos (multiget em blocos de 20).

**Exemplo de pedido ao agente:** “Me mostre o anúncio MLB3456789012 com preço, estoque e status.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `item_id` | string/null | não |  |
| `item_ids` | array/null | não |  |
| `fields` | array/null | não |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ items[]<objeto ML>, _error? }
 · fields projeta cada anúncio para os campos pedidos (aceita caminho com 1 ponto) · sem item_id/item_ids: { items[] vazio, _error }
```

### `get_order`

Busca um pedido do Mercado Livre (normalizado). view=financial inclui descontos.

**Exemplo de pedido ao agente:** “Mostre os detalhes do pedido 2000012345678 da minha conta principal.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `order_id` | integer | sim |  |
| `view` | string | não | `summary` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ id, status, date_created, date_closed, total_amount, paid_amount, currency_id,
  buyer{id, nickname}, items[]{item_id, title, qty, unit_price, gross_price, sale_fee},
  shipping_id, pack_id, tags, cancel_detail, _missing?, discounts?, payments? }
 · view="financial" acrescenta discounts (<objeto ML> ou null) e payments (<lista ML>) · view="full" devolve o pedido ML completo (GET /orders/{order_id})
```

### `get_question`

Uma pergunta; include_contact usa api_version=4 (dados do comprador).

**Exemplo de pedido ao agente:** “Abra a pergunta 13000045678 e me mostre o anúncio a que ela se refere.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `question_id` | integer | sim |  |
| `include_contact` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (GET /questions/{question_id})
```

### `get_seller_reputation`

Projeção da reputação do vendedor (endpoint /users/id).

**Exemplo de pedido ao agente:** “Como está minha reputação hoje?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ user_id, nickname, seller_reputation<objeto ML> }
```

### `get_shipment`

Envio composto: colapsa até 8 endpoints /shipments/* (busca só o pedido).

**Exemplo de pedido ao agente:** “Qual é o status do envio do pedido 2000012345678?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `shipment_id` | integer | sim |  |
| `include` | array/null | não |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ …<objeto ML> (GET /shipments/{shipment_id}), costs?, sla?, history?, carrier?, lead_time?, items?, delays? }
 · cada chave de include carrega a resposta do ML daquele recurso, ou {_error} se a leitura falhar · delays sem atraso (404): {delayed: false}
```

### `get_stock`

Estoque multi-origem; devolve x_version (necessário para escrita).

**Exemplo de pedido ao agente:** “Quanto tenho em estoque do anúncio MLB3456789012?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `user_product_id` | string | sim |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ locations[]<lista ML>, x_version }
```

### `get_visits`

Visitas (user ou item). mode=total exige date_from+date_to, janela
≤150 dias; scope=item exige `id` e só aceita unit=day; 1 id por chamada.

**Exemplo de pedido ao agente:** “Quantas visitas o anúncio MLB3456789012 teve nos últimos 30 dias?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `scope` | string | sim |  |
| `id` | string/null | não |  |
| `date_from` | string/null | não |  |
| `date_to` | string/null | não |  |
| `mode` | string | não | `total` |
| `last` | integer/null | não |  |
| `unit` | string | não | `day` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (mode="total": GET /users/{target}/items_visits ou GET /items/visits; mode="timeseries": GET /users/{target}/items_visits/time_window ou GET /items/{target}/visits/time_window)
```

### `list_messages`

Mensagens pós-venda de um pacote/pedido (pack-cêntrico; aceita ambos).

**Exemplo de pedido ao agente:** “Mostre a conversa com o comprador do pedido 2000012345678.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `pack_id` | integer/null | não |  |
| `order_id` | integer/null | não |  |
| `mark_as_read` | boolean | não | `False` |
| `cursor` | string/null | não |  |
| `limit` | integer | não | `50` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ conversation_status<objeto ML>, messages[]<lista ML>, seller_max_message_length, paging }
 · sem pack_id/order_id: { _error }
```

### `list_received_questions`

Perguntas recebidas (pré-venda).

**Exemplo de pedido ao agente:** “Quais perguntas dos compradores estão sem resposta?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `status` | string/null | não |  |
| `item_id` | string/null | não |  |
| `from_user` | integer/null | não |  |
| `sort` | string/null | não |  |
| `cursor` | string/null | não |  |
| `limit` | integer | não | `50` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ questions[]<lista ML>, total, cursor }
```

### `list_warehouses`

Depósitos (stock locations) do vendedor.

**Exemplo de pedido ao agente:** “Em quais depósitos eu tenho estoque cadastrado?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ stores<lista ML> }
```

### `search_claims`

Busca reclamações. Auto-injeta players.user_id+role=respondent quando
não há filtro real (ML devolve 400 em busca só com paginação).
range_from/range_to aceitam AAAA-MM-DD e são ancorados à meia-noite
(-0300), então range_to exclui o dia informado.

**Exemplo de pedido ao agente:** “Liste as reclamações abertas de março, ainda na etapa de reclamação, das mais recentes para as mais antigas.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `status` | string/null | não |  |
| `type` | string/null | não |  |
| `stage` | string/null | não |  |
| `order_id` | integer/null | não |  |
| `pack_id` | integer/null | não |  |
| `resource` | string/null | não |  |
| `resource_id` | integer/null | não |  |
| `reason_id` | string/null | não |  |
| `range_from` | string/null | não |  |
| `range_to` | string/null | não |  |
| `sort` | string/null | não |  |
| `cursor` | string/null | não |  |
| `limit` | integer | não | `30` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ data[]<lista ML>, paging, cursor }
```

### `search_orders`

Busca pedidos do vendedor (/orders/search) com paginação normalizada (cursor).

**Exemplo de pedido ao agente:** “Liste os pedidos pagos de ontem que ainda não foram despachados.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `status` | string/null | não |  |
| `q` | string/null | não |  |
| `item` | string/null | não |  |
| `tags` | array/null | não |  |
| `date_field` | string | não | `created` |
| `date_from` | string/null | não |  |
| `date_to` | string/null | não |  |
| `sort` | string/null | não |  |
| `cursor` | string/null | não |  |
| `limit` | integer | não | `50` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ results[]{id, status, date_created, date_closed, total_amount, paid_amount, currency_id,
            buyer{id, nickname}, items[]{item_id, title, qty, unit_price, gross_price, sale_fee},
            shipping_id, pack_id, tags, cancel_detail, _missing?},
  paging, cursor }
```

### `search_seller_items`

Lista IDs de anúncios do vendedor; muda para scan/scroll_id além de 1000.

**Exemplo de pedido ao agente:** “Quais dos meus anúncios ativos estão com estoque zerado?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `status` | string/null | não |  |
| `listing_type` | string/null | não |  |
| `sku` | string/null | não |  |
| `cursor` | string/null | não |  |
| `limit` | integer | não | `100` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ item_ids[], paging, cursor }
```

## Escrita (auditadas)

### `add_order_note`

Adiciona nota interna a um pedido (visível só para o vendedor).

**Exemplo de pedido ao agente:** “Anote no pedido 2000012345678 que o cliente pediu embalagem para presente.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `order_id` | integer | sim |  |
| `note` | string | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (POST /orders/{order_id}/notes)
```

### `answer_question`

Responde uma pergunta de pré-venda (máx. 2.000 caracteres).

**Exemplo de pedido ao agente:** “Responda a pergunta 13000045678 dizendo que o produto tem garantia de um ano.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `question_id` | integer | sim |  |
| `text` | string | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (POST /answers)
```

### `delete_question` · **destrutiva**

Exclui uma pergunta. SEMPRE exige confirm=true.

**Exemplo de pedido ao agente:** “Exclua a pergunta 13000045678, ela é ofensiva.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `question_id` | integer | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ deleted, message }
```

### `print_shipping_labels`

Obtém etiquetas de envio OFICIAIS do ML (o template nunca é alterado).
Máx. 50 envios por chamada, conforme o teto publicado.

**Exemplo de pedido ao agente:** “Gere as etiquetas dos envios prontos para despachar hoje.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `shipment_ids` | array | sim |  |
| `format` | string | não | `pdf` |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ format, content_base64, shipment_ids[] }
```

### `resolve_claim` · **destrutiva**

Resolve uma reclamação pela rota publicada da ação. A ação é validada
contra players[].available_actions[] do claim: reclamação sem ação
disponível é RECUSADA. SEMPRE exige confirm=true (alto risco).

payload por ação — allow_partial_refund: {"percentage": N} (um dos
valores de /claims/{id}/partial-refund/available-offers; 100% não é
permitido aqui, use 'refund'); send_potential_shipping:
{"handling_date": "AAAA-MM-DD"}; add_shipping_evidence: {"type",
"shipping_method", ...campos condicionais}; return_review: omitido =
devolução aprovada, lista [{"reason","message","attachments"?}] =
reprovada. refund/allow_return/open_dispute não levam body.

**Exemplo de pedido ao agente:** “Reembolse integralmente a reclamação 5200012345.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `claim_id` | integer | sim |  |
| `action` | string | sim |  |
| `payload` | object/array/null | não |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ claim_id, action, result<resposta ML> }
```

### `send_claim_message`

Envia mensagem na reclamação (para o reclamante ou mediador). Valida
send_message_to_<destinatário> em players[].available_actions[]; em
mediação (stage=dispute) só o canal do mediador é permitido.

**Exemplo de pedido ao agente:** “Responda ao comprador da reclamação 5200012345 pedindo uma foto do defeito.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `claim_id` | integer | sim |  |
| `to` | string | sim |  |
| `text` | string | sim |  |
| `attachment_ids` | array/null | não |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (POST /post-purchase/v1/claims/{claim_id}/actions/send-message)
```

### `send_message`

Envia UMA mensagem pós-venda no pacote/pedido. Regras ML: só conversas
iniciadas pelo comprador, janela de 48h úteis, pedido não cancelado.
PROIBIDO uso automático/template/repetitivo (bloqueado pelo ML e
arrisca a conta do vendedor) — apenas os motivos oficiais.

**Exemplo de pedido ao agente:** “Responda o comprador do pedido 2000012345678, que perguntou do prazo: o envio sai amanhã.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `text` | string | sim |  |
| `pack_id` | integer/null | não |  |
| `order_id` | integer/null | não |  |
| `attachment_ids` | array/null | não |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (POST /messages/packs/{pack_id}/sellers/{seller_id})
```

### `split_shipment` · **destrutiva**

Divide um envio em pacotes. SEMPRE exige confirm=true.

**Exemplo de pedido ao agente:** “Divida o envio 45000067890 em dois pacotes, os itens são frágeis.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `shipment_id` | integer | sim |  |
| `reason` | string | sim |  |
| `packs` | array | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (POST /shipments/{shipment_id}/split)
```

### `update_item` · **destrutiva**

Atualiza um anúncio (preço, estoque, status). Guardas: rejeita variação
de preço >±50%, estoque negativo; deleted encadeia closed→delete.

**Exemplo de pedido ao agente:** “Reduza em dez por cento o preço do anúncio MLB3456789012.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `item_id` | string | sim |  |
| `price` | number/null | não |  |
| `available_quantity` | integer/null | não |  |
| `status` | string/null | não |  |
| `deleted` | boolean | não | `False` |
| `other_fields` | object/null | não |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ update?<objeto ML>, deleted?<objeto ML> }
 · update: resposta do PUT /items/{item_id} quando há campo a alterar · deleted: resposta do PUT final quando deleted=true
```

### `update_order_note`

Atualiza uma nota interna de pedido.

**Exemplo de pedido ao agente:** “Corrija a nota do pedido 2000012345678: o cliente retira na loja.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `order_id` | integer | sim |  |
| `note_id` | string | sim |  |
| `note` | string | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (PUT /orders/{order_id}/notes/{note_id})
```

### `update_stock` · **destrutiva**

Atualiza estoque multi-origem (busca x-version e envia PUT com lock otimista).

**Exemplo de pedido ao agente:** “Ajuste o estoque do anúncio MLB3456789012 para 40 unidades no depósito principal.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `user_product_id` | string | sim |  |
| `locations` | array | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (PUT /user-products/{user_product_id}/stock/type/seller_warehouse)
```

### `upload_message_attachment`

Sobe um anexo de mensagem (≤25MB; JPG/PNG/PDF/TXT).

**Exemplo de pedido ao agente:** “Anexe a nota fiscal em PDF à conversa do pedido 2000012345678.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `file_base64` | string | sim |  |
| `filename` | string | sim |  |
| `confirm` | boolean | não | `False` |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
resposta do Mercado Livre sem transformação (POST /messages/attachments)
```

## Meta (grátis)

### `connection_status`

Contas conectadas: apelido, estado, tools bloqueadas. Gratuito.

Sem argumentos lista todas as contas que você alcança — inclusive
nenhuma. Com `account` (ou `connector_id`) devolve o detalhe de uma conta.

**Exemplo de pedido ao agente:** “Minhas contas estão conectadas e autorizadas a escrever?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `account` | string/null | não |  |
| `q` | string/null | não |  |
| `client` | string/null | não |  |
| `marketplace` | string/null | não |  |
| `status` | string/null | não |  |
| `can` | string/null | não |  |
| `limit` | integer | não | `25` |
| `cursor` | string/null | não |  |

**Disponível em:** plataforma (não depende de marketplace)

**Retorno**

```text
{ status, connector_id, seller_id, site_id, token_expires_at, read_only, require_confirm, plan }
 · status = "ok" | "reconnect_required"
```

### `describe_query_schema`

Catálogo do DSL `query`: entidades, campos, operadores, regras de
budget. Com `entity` filtra uma entidade; com `marketplace` (ex.: ml)
acrescenta enums e campos nativos. Gratuito.

**Exemplo de pedido ao agente:** “Que campos e filtros posso usar na consulta livre de pedidos?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `entity` | string/null | não |  |
| `marketplace` | string/null | não |  |

**Disponível em:** plataforma (não depende de marketplace)

**Retorno**

```text
{ query, entities{orders[], order_items[], items[], questions[], claims[]}, filter, aggregate, group_by, budget, rules[], native?{enums{<nome>[]}, fields{…}} }
 · entity informado: entities traz só essa entidade · marketplace informado: native acrescenta enums e campos do marketplace
```

### `describe_statuses`

Status normalizados: valores canônicos e os nativos de cada marketplace.
Sem chamada ao marketplace. Gratuito.

**Exemplo de pedido ao agente:** “Quais status canônicos existem para pedidos e quais valores nativos do marketplace correspondem a cada um?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `entity` | string/null | não |  |
| `marketplace` | string/null | não |  |

**Disponível em:** plataforma (não depende de marketplace)

**Retorno**

```text
{ entities{<entidade>{canonical[], native{<marketplace>{<canônico>: [<nativos>]}}}} }
```

### `open_support_ticket`

Abre um chamado de suporte do mcplace sem sair do chat. Use quando o
usuário pedir, ou OFEREÇA quando houver erro repetido de ferramenta,
falha de permissão/auth sem solução, ou limitação do conector.
Sempre pergunte ao usuário antes de abrir. Gratuito (não conta na cota).

**Exemplo de pedido ao agente:** “Abra um chamado de suporte: minha conta parou de sincronizar ontem à noite.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `subject` | string | sim |  |
| `body` | string | sim |  |
| `severity` | string/null | não |  |
| `category` | string | não | `question` |
| `context` | object/null | não |  |

**Disponível em:** plataforma (não depende de marketplace)

**Retorno**

```text
{ ticket_id, status, deduped, message }
```

### `suggest_improvement`

Registra uma sugestão de melhoria do mcplace (ex.: 'essa ação ainda
não existe no conector'). Pergunte ao usuário antes. Gratuito.

**Exemplo de pedido ao agente:** “Sugira ao time do mcplace um filtro de pedidos por transportadora.”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `text` | string | sim |  |
| `area` | string/null | não |  |

**Disponível em:** plataforma (não depende de marketplace)

**Retorno**

```text
{ ticket_id, deduped, message }
```

### `whoami`

Conta conectada: id, nickname, site, tags (inclui multiwarehouse), status.

**Exemplo de pedido ao agente:** “Qual conta e qual vendedor é esta conexão?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ id, nickname, site_id, tags, status, connector_id }
```


página gerada por `mcplace_server.docgen` · não edite à mão