# Referência de ferramentas — Mercado Livre

O que só existe no Mercado Livre. O resto está em [Referência de tools](/referencia).

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)

### `ml_ads_performance`

Performance de Product Ads (api-version 2, ROAS-first; deriva
ACoS=(1/ROAS)×100). Janela dura de 90 dias para trás; dados do dia
atualizados às 10:00 GMT-3. level='ad' consulta Ad Groups, que
substituíram as métricas por anúncio (removidas em 30/05/2026).

**Exemplo de pedido ao agente:** “Como foi o desempenho dos meus anúncios patrocinados na última semana?”

| Parâmetro | Tipo | Obrigatório | Padrão |
|---|---|---|---|
| `date_from` | string | sim |  |
| `date_to` | string | sim |  |
| `level` | string | não | `account` |
| `advertiser_id` | string/null | não |  |
| `site_id` | string/null | não |  |
| `status` | string/null | não |  |
| `metrics` | array/null | não |  |
| `aggregation_type` | string | não | `campaign` |
| `sort_by` | string/null | não |  |
| `limit` | integer | não | `50` |
| `campaign_ids` | array/null | não |  |
| `account` | string/null | não |  |

**Disponível em:** Mercado Livre

**Retorno**

```text
{ level, advertiser_id, site_id, range{from, to},
  summary{…metrics_summary do ML, acos?},
  rows[]<lista ML>, paging, _note? }
 · acos só quando o ML devolve roas (ou total_roas): (1/ROAS)×100 · level="account" devolve rows vazio (só os totais em summary) · anunciante sem campanhas: summary{} vazio, rows[] vazio, paging null e _note
```

## Meta (grátis)

### `ml_app_limits`

Limites do app ML (max_requests_per_hour, escopos). Gratuito.

Sem conta: é dado do aplicativo, não de um vendedor.

**Exemplo de pedido ao agente:** “Qual é o teto de chamadas por hora do aplicativo e quais escopos ele tem?”

**Disponível em:** Mercado Livre

**Retorno**

```text
{ max_requests_per_hour, scopes, source, complete, message? }
 · source="app_owner" lê o aplicativo com a conta dona; source="config" devolve só o teto local (scopes null, complete false, message explica)
```

### `ml_claim_reasons`

Motivos de reclamação (todos ou um específico). Gratuito.

**Exemplo de pedido ao agente:** “Quais motivos de reclamação o Mercado Livre aceita?”

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

**Disponível em:** Mercado Livre

**Retorno**

```text
{ reasons<resposta ML> }
```

### `ml_shipment_statuses`

Catálogo de status de envio (cacheável). Gratuito.

**Exemplo de pedido ao agente:** “Quais status de envio o Mercado Livre pode devolver?”

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

**Disponível em:** Mercado Livre

**Retorno**

```text
{ statuses<resposta ML> }
```

### `ml_sites`

Sites do ML (site_id ↔ moeda). Gratuito.

**Exemplo de pedido ao agente:** “Quais sites do Mercado Livre existem e qual a moeda de cada um?”

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

**Disponível em:** Mercado Livre

**Retorno**

```text
{ sites[]{id, name, default_currency_id} }
```


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