Referência de ferramentas — Mercado Livre

O que só existe no Mercado Livre. O resto está em Referência de tools.

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

{ 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

{ 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

{ 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

{ 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

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

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

Isso ajudou?

Matriz de disponibilidade Consulta genérica (query)