MCP: Ads

Tools in this area, generated from the server code. The descriptions come from that code, in Portuguese. To connect, see the XBASE MCP.

ads_apply_mutationCopy Anchor Link

APLICA na plataforma de anúncios uma mudança que uma pessoa JÁ APROVOU em XBASE → Anúncios → Avisos (status "approved"); não aprova nada. Só funciona com token MCP criado listando esta ferramenta explicitamente (token "todas as ferramentas" não aplica: o backend recusa com 403). Ação real: mexe em campanhas no ar e em dinheiro de verdade, sem desfazer automático. Só use quando o usuário pedir para aplicar aquela mudança específica. Rascunho não aprovado, rejeitado ou já aplicado é recusado, assim como canal sem escrita verificada; se a plataforma recusar, a mudança fica "failed" e a ferramenta devolve erro com o motivo. Pegue o mutationId em ads_list_mutations { status: "approved" }.

ads_assistant_funnelCopy Anchor Link

Cliente reclamando: o furo está no tráfego ou no comercial? Resultado e custo do objetivo principal (Meta) e, no CRM, as conversas vindas dos anúncios da conta: respondidas, ignoradas, engajadas (o lead respondeu depois da 1ª resposta; costPerEngaged) e a mediana da 1ª resposta. Devolve o veredito (comercial | trafego | ambos | engajamento = o lead não volta | ok | sem-meta = falta a meta de custo, com costGoal.suggestedTargetCpl pelo ticket ou pela média | sem-crm | sem-dados) e uma mensagem pronta para mandar ao cliente (só com números medidos). Sem meta cadastrada o veredito nunca é ok: peça a meta ao usuário.

ads_assistant_panoramaCopy Anchor Link

Panorama da conta da Meta com TODO o histórico: investido, campanhas, resultado e custo por objetivo (WhatsApp, formulário, leads e vendas no site, tráfego), melhor público (sexo e idade), melhor região e criativo campeão. Leitura pesada na Meta: chame uma vez por conversa.

ads_assistant_scaleCopy Anchor Link

Plano de escala do vencedor: a campanha ativa com mais resultado dentro da meta (10+ resultados, fora do aprendizado) e os passos (subir 20% agora, repetir a cada 3 dias, abrir público novo, quando parar). O primeiro passo traz mutation { level, targetExternalId, kind, payload } para ads_draft_mutation (accountId = adAccountId, dailyBudget = payload.dailyBudget).

ads_assistant_xrayCopy Anchor Link

Raio-X das campanhas ativas da Meta no período: sugestões de pausar anúncio caro (custo ≥ 2× a campanha), subir ou reduzir verba (pela meta do workspace ou pela média da conta) e o que fica só observando. Cada sugestão traz mutation { level, targetExternalId, kind, payload, reason } e a resposta traz adAccountId. Para aplicar, chame ads_draft_mutation com accountId = adAccountId, level, targetExternalId, kind, dailyBudget = payload.dailyBudget (só em set_daily_budget) e reason; a pessoa aprova em Avisos. adAccountId nulo = conta ainda não sincronizada em Canais (não dá para aplicar).

ads_create_campaignCopy Anchor Link

Cria uma campanha de PESQUISA no Google Ads (hoje o único tipo e canal) numa conta conectada pela API, num envio só: orçamento diário, campanha, locais, idiomas, palavras negativas, um grupo com as palavras-chave e um anúncio responsivo (3 a 15 títulos de até 30 caracteres, 2 a 4 descrições de até 90). A campanha nasce PAUSADA e não gasta; para ligar, rascunhe ads_draft_mutation { kind: "activate", level: "campaign" } e uma pessoa aprova em XBASE → Anúncios → Avisos. O link sai com UTM automática (utm_source=google, campanha, palavra-chave e criativo); finalUrlSuffix substitui o padrão ("" = sem rastreamento). Exige token de quem pode gerenciar integrações. accountId vem de ads_list_accounts (provider google, source api, selected). Locais e idiomas são ids do Google: 2076 = Brasil, 1014 = português.

ads_draft_mutationCopy Anchor Link

Cria um RASCUNHO de mudança numa campanha, conjunto (adgroup) ou anúncio. NÃO muda nada na plataforma: uma pessoa revisa e aprova em XBASE → Anúncios → Avisos. Só canal com escrita liberada (hoje Meta e Google/YouTube; no Google: pausar/ativar campanha, grupo e anúncio, orçamento e nome da campanha, nome do grupo) e conta conectada pela API: nos outros o backend recusa — entregue a recomendação em texto. Tipos: pause, activate, set_daily_budget (dailyBudget na moeda da conta, ex.: 150.5; só campaign/adgroup), rename (name), delete (só Meta; exclui campanha, conjunto ou anúncio na plataforma, irreversível — a pessoa confirma ao aplicar), set_targeting (targeting { devices?, os?, geo?, ageMin?, ageMax? } — só o que muda; geo substitui todos os locais e usa as keys de ads_search_locations) e set_schedule (schedule { mode: "always" } ou { mode: "windows", windows: [{ days: [1,2,3,4,5], start: "08:00", end: "18:00" }] }, 0 = domingo, hora cheia, até 7 janelas; no fuso da conta) — esses dois só com level=adgroup; leia antes ads_get_entity_settings. Regras de valor (Meta; leia antes ads_list_value_rules): set_value_rules (level=adgroup, valueRuleSetId ou null para tirar), save_value_rule_set (level=account, targetExternalId = id do conjunto de regras ou "new", valueRuleSet { name, rules } — substitui o conjunto inteiro) e delete_value_rule_set (level=account; recusado se algum conjunto ainda usa). Anúncio novo do Estúdio (só Meta): create_ad (level=adgroup, targetExternalId = id do conjunto, ad { name, studioProductionId, primaryText, headline?, destination { type: "whatsapp", prefilledMessage? } ou { type: "website", url, callToAction, urlTags? }, enhancements?, status? }) — sobe o Reels (9:16 com som) ou a imagem única da produção pronta e cria o anúncio no conjunto, pausado por padrão; destino WhatsApp só em conjunto de conversas no WhatsApp. Só Google Ads (leia antes ads_get_campaign_details): add_keywords (level=adgroup, targetExternalId = id do grupo, keywords [{ text ≤80, matchType broad|phrase|exact }], até 50), update_keyword (level=adgroup, criterionId + action pause|enable|remove), add_negative_keywords (level=campaign, keywords; termos de ads_get_search_terms que gastam sem converter), remove_negative_keyword (level=campaign, criterionId), update_ad (level=ad, anúncio responsivo: headlines 3–15 de até 30, descriptions 2–4 de até 90, finalUrl https; ao menos um — o que vier substitui tudo) e set_url_suffix (level=campaign, finalUrlSuffix chave=valor&… com ValueTrack; "" = sem rastreamento). Limite de orçamento (padrão ±50% do orçamento atual por mudança; o workspace pode mudar, até 100%) é checado já no rascunho e de novo ao aplicar. reason é obrigatório (mín. 10 caracteres): escreva o porquê com os números que justificam. accountId e targetExternalId vêm de ads_list_entities (externalId), das linhas de ads_get_performance com groupBy campaign/adgroup/ad (externalId) ou do campaign de ads_get_insights (externalId, nunca key); se veio de uma auditoria, informe auditRunId. Não cria campanha.

ads_get_auditCopy Anchor Link

Abre uma auditoria já feita, no mesmo resumo de ads_run_audit. full=true devolve o pacote completo do claude-ads (grande: só quando precisar das evidências ou de todos os achados).

ads_get_breakdownCopy Anchor Link

ads_get_campaign_detailsCopy Anchor Link

Detalhes de UMA campanha do Google Ads, lidos ao vivo: campaign (status, channelType, biddingStrategy, dailyBudget, finalUrlSuffix, networks, locations e languages), adGroups, keywords (criterionId, text, matchType, status, qualityScore e métricas impressions/clicks/cost/conversions do período), negatives (de campanha e de grupo) e ads (anúncio responsivo: headlines, descriptions, finalUrls, approvalStatus). Use antes de rascunhar add_keywords, update_keyword, add_negative_keywords, remove_negative_keyword, update_ad ou set_url_suffix. Só Google (outro canal = erro). Período (só para as métricas das palavras-chave): since/until YYYY-MM-DD; sem eles, 30 dias no fuso da conta.

ads_get_entity_settingsCopy Anchor Link

Segmentação e horário ATUAIS de um conjunto de anúncios (lidos ao vivo na plataforma; hoje só Meta): devices (mobile/desktop), os (all/ios/android), geo (countries, regions e cities com key, nome e raio em km; otherTypes = outros tipos de local que somem se geo for trocado), ageMin/ageMax, budgetType (daily | lifetime), schedule { source: native | rules | none, windows } no fuso da conta (timezone) e capabilities (o que o canal aceita mudar). Use antes de rascunhar set_targeting ou set_schedule. Com orçamento diário a XBASE faz o horário com regras automáticas (source rules); com vitalício, programação nativa.

ads_get_insightsCopy Anchor Link

"O que mudou" nos anúncios: destaques do período comparado com o anterior de mesmo tamanho (padrão 7d = últimos 7 dias incluindo hoje × os 7 dias antes). Cada destaque traz id da regra, severity (critical | warning | info | positive), title, detail com os números e, quando é de uma campanha, campaign { externalId, accountId, name, provider }. Regras fixas e determinísticas sobre os dados sincronizados e os leads do CRM: campanha que trazia leads parou, gasto sem lead, verba mudou de lugar, CTR caiu, clique mais caro, gasto acima do orçamento, anúncios ativos sem entrega, leads subiram/caíram e melhor anúncio em leads; até 8, do mais grave. Só lê: nunca muda nada na conta. Use como PONTO DE PARTIDA da análise: confirme com ads_get_performance { period, compare: true } e desça campanha → conjunto → anúncio antes de concluir; nenhum destaque não quer dizer que está tudo bem. Sugira rascunho (ads_draft_mutation com campaign.externalId e campaign.accountId; key é id interno) só em canal com escrita liberada (hoje Meta); nos outros, entregue o passo a passo. Período: period OU since/until.

ads_get_performanceCopy Anchor Link

Desempenho dos anúncios: investimento (spend), impressões, cliques, CTR, CPC, conversões da plataforma (conversions, cpa; conversionValue e roas quando há valor) e leads do CRM da XBASE (leads, cpl; engagedConversations = o contato respondeu depois da 1ª resposta do workspace, costPerEngaged; qualified e sales quando o funil está configurado), agrupado por canal (padrão), conta, campanha, conjunto (adgroup), anúncio (ad) ou dia. Período: period (today | yesterday | 7d | 14d | 30d | 90d, fuso de Brasília; 7d = últimos 7 dias INCLUINDO hoje) OU since/until (os dois juntos = erro); sem nenhum, 30 dias terminando ontem. compare=true (padrão false; use sempre que for comparar): cada linha ganha previous (o mesmo recorte no período anterior de mesmo tamanho; null = não existia ou não gastou) e a resposta previousTotals; campanha que parou de gastar aparece zerada. LEADS x CONVERSÕES: leads são conversas do CRM atribuídas a um anúncio e PODEM ser somadas entre canais (resposta: leads { total, qualified, sales, cpl, unmatched }); conversions são contadas por cada plataforma (janela e evento próprios): NUNCA some entre canais (use conversionsByProvider) e compare só dentro da mesma plataforma. Quando o objetivo é conversa, julgue por leads e cpl. Valores na moeda de cada conta (totals por moeda; não some moedas). DRILL-DOWN: groupBy campaign → groupBy adgroup + campaignId (externalId da campanha) → groupBy ad + adgroupId. Linhas de campanha/conjunto/anúncio trazem externalId (id na plataforma = targetExternalId de ads_draft_mutation), accountId, status, dailyBudget e effectiveDailyBudget (campanha sem orçamento próprio = soma dos conjuntos ativos) e activeAdgroups (campanha; 0 = não entrega). FRESCOR: sync de hora em hora; dataAsOf = último sync da conta mais desatualizada do recorte; hoje é parcial e conversões da plataforma chegam com atraso. truncated=true: havia mais linhas que o limite (os totais continuam completos) — filtre por canal/conta/campanha ou encurte o período.

ads_get_playbookCopy Anchor Link

Manual do gestor de tráfego (conhecimento do claude-ads + regras da XBASE). LEIA ANTES de analisar ou propor mudanças. Sem argumentos: a skill da XBASE (fluxo playbook → desempenho → auditoria → rascunho → aprovação humana) + o índice de skills e referências. Com provider: a skill do canal (ads-<canal>) e o checklist de auditoria dele (<canal>-audit) — specs de criativo não vêm junto (abra kind "reference", name "<canal>-creative-specs" quando existir no índice). Com kind + name: um documento do índice. Documentos acima de 40 mil caracteres vêm cortados.

ads_get_search_termsCopy Anchor Link

Termos de pesquisa de uma campanha do Google Ads no período, lidos ao vivo: o que as pessoas digitaram e mostrou o anúncio (term, adGroupExternalId, status ADDED | EXCLUDED | ADDED_EXCLUDED | NONE, impressions, clicks, cost, conversions), por cliques, até 500 linhas. Termo com gasto e sem conversão vira candidato a add_negative_keywords; termo que converte e não é palavra-chave (NONE) vira candidato a add_keywords. Só Google. since/until YYYY-MM-DD (sem eles, 30 dias no fuso da conta).

ads_list_accountsCopy Anchor Link

Lista as contas de anúncios do workspace (via API ou CSV importado): id interno (é o accountId das outras ferramentas), canal, origem (api | csv), id na plataforma, nome, moeda, fuso, se entra no sync e o resultado do último sync. Conta CSV que repete uma conta conectada pela API fica fora do desempenho e da auditoria. Contas da Meta pela API trazem funding (lido ao vivo): saldo pré-pago, limite de gasto, gasto médio de 3 dias e daysLeft (status low = acaba em menos de 3 dias; empty = parou).

ads_list_channelsCopy Anchor Link

Lista os 12 canais de anúncios (meta, google, youtube, tiktok, linkedin, microsoft, apple, amazon, reddit, pinterest, snapchat, x) e o estado de cada um no workspace: available (integração existe), configured (app da plataforma configurado na XBASE) e missingEnv, a conexão (status, último erro), as capacidades (read/write/csvImport; só write "live-write-verified" aceita rascunhos de mudança — hoje Meta e Google/YouTube) e accounts { api, csv, selected }. Comece por aqui para saber quais canais têm dados. Conectar um canal ou importar CSV é feito por uma pessoa em XBASE → Anúncios → Canais.

ads_list_entitiesCopy Anchor Link

Lista campanhas, conjuntos (adgroup) e anúncios com status, orçamento diário (na moeda da conta), objetivo e métricas dos últimos 30 dias. Use para achar o accountId e o externalId (id na plataforma = targetExternalId de ads_draft_mutation) antes de rascunhar. Filtros: canal, conta, nível, status e trecho do nome. includeDestination=true (só level=ad, só Meta: use provider "meta") lê o criativo ao vivo e devolve destination { link, cta, whatsappNumber, prefilledText } de cada anúncio (link wa.me com o texto pré-preenchido); anúncio de conta por CSV ou de canal sem essa leitura volta com destination null.

ads_list_mutationsCopy Anchor Link

Fila e histórico de mudanças em anúncios do workspace (mais recentes primeiro; padrão 20, limit até 100): rascunhos aguardando aprovação, aprovadas, rejeitadas, aplicadas e com falha, com alvo (targetExternalId, targetName), payload, estado anterior (before), motivo (cortado em 300 caracteres), quem criou, quando foi aprovada/aplicada e o erro da plataforma (failed). Confira aqui antes de criar um rascunho repetido.

ads_list_value_rulesCopy Anchor Link

Regras de valor de uma conta da Meta, lidas ao vivo: sets (conjuntos de regras: id, name, rules com adjustSign INCREASE/DECREASE, adjustValue em %, criteria { type, values, valueTypes }) e adsets (cada conjunto de anúncios com valueRuleSetId aplicado, bidStrategy, optimizationGoal, eligible = a Meta aceita regra de valor nele, e placements { automatic, platforms, positions }). Use antes de rascunhar set_value_rules, save_value_rule_set ou delete_value_rule_set. Para priorizar o Instagram quando a Meta não deixa escolher o posicionamento: regra DECREASE 90 em PLACEMENT fora do Instagram.

ads_run_auditCopy Anchor Link

Roda uma auditoria das contas de anúncios (scoring do claude-ads) e devolve um RESUMO com o auditId: saúde do portfólio (0–100), cobertura de evidência, nota (normal | provisional | insufficient_evidence), unscored (o que ficou fora do score e por quê), saúde por conta e canal (origem api/csv, moeda) e os achados reprovados mais graves com accountId, recomendação e suggestedMutation. Nota provisional ou insufficient_evidence = pouca evidência: diga isso ao usuário em vez de afirmar. suggestedMutation é candidata, não regra: confira atraso de conversão, evento de otimização e janela de atribuição antes de rascunhar. Janela máxima: 90 dias (padrão: 30 dias até ontem). Leia antes o playbook do canal (ads_get_playbook). Pode levar alguns segundos.

ads_search_locationsCopy Anchor Link

Busca locais para a segmentação (hoje Meta): cidade (city), estado (region) ou país (country). Devolve key, name, region e countryCode só do tipo pedido (a plataforma mistura bairros na busca de cidade). Use a key e o name em ads_draft_mutation kind=set_targeting (targeting.geo.cities/regions; país vai pelo código ISO em countries). O estado de São Paulo aparece como "São Paulo (state)". Padrão: locais do Brasil.