Amazon Ads Reports Troubleshooting — Titanos MCP

Quando usar

Use quando precisar puxar relatórios de Amazon Ads via Titanos MCP e encontrar erros, timeouts, ou precisar escolher entre ferramentas de relatório, formatos de data e parâmetros de escopo.

Resumo rápido (MCP 1.42.2 — testado 2026-07-06)

✅ Funciona

⚠️ Limitações conhecidas (não bugs)

Regras de data

Formato correto

{
  "start_date": "2026-06-01",
  "end_date": "2026-06-30"
}

Também aceita days (ex: days: 7):

{
  "days": 7
}

Cálculo de janela

from datetime import date, timedelta
end = date(2026, 7, 5)
start = end - timedelta(days=7)
# start_date = "2026-06-28"
# end_date = "2026-07-05"

Lag de dados

Amazon Ads tem lag de 2-3 dias. Se hoje é 5 de julho, o último dia com dados completos é 2 ou 3 de julho.

Para relatórios de "últimos 7 dias", use:

end_date = hoje - 3 dias
start_date = end_date - 7 dias

Escolha de ferramenta por necessidade

ask_ads_report_analyst — armadilhas

✅ Funciona

{
  "question": "Total spend, sales14d, ACOS, impressions, clicks for last 7 days"
}

❌ Falha

{
  "connection_id": "<ads_connection_uuid>",
  "profile_id": 123456789012345,
  "question": "Total spend, sales14d, ACOS, impressions, clicks for last 7 days"
}

O ask_ads_report_analyst usa o profile default da organização quando não recebe scope explícito. Passar connection_id + profile_id causa VALIDATION_ERROR (400).

Se precisar de scope específico e o default não servir, use get_ads_performance com datas explícitas.

Reports assíncronos

Os reports de performance, search terms, placement e advertised product são assíncronos. A chamada retorna imediatamente com status: "PENDING" e um report_id. O processamento acontece em background na Amazon (~45-120s).

Não é necessário polling — o resultado é retornado na mesma chamada quando pronto. Se retornar PENDING, aguarde e tente novamente.

Estratégia anti-timeout

1. Use ask_ads_report_analyst (sem scope) para análises rápidas — é mais rápido.
2. Para dados determinísticos, use start_date/end_date ou days.
3. Use janelas curtas (7 dias) em vez de 30+ dias quando possível.
4. Se um relatório timeout, reduza a janela para 3 dias e tente novamente.

Modelo de resposta para usuário

Janela: <start_date> a <end_date> (lag de 2-3 dias)
Conta: <account_name> (profile_id: <pid>)

Spend: R$ X
Sales: R$ Y
ACOS: Z%
ROAS: N.Nx
Impressões: N
Cliques: N
CTR: X%
CPC: R$ X

Fonte: <tool usado> (<tempo>s)