GAQL via MCP: como o ads_query responde qualquer pergunta sobre sua conta do Google Ads

Num servidor MCP de Google Ads, existe uma tool que vale por vinte: ads_query. Ela recebe uma consulta em GAQL e devolve o resultado cru. É o coringa — qualquer relatório que a API do Google Ads sabe produzir, ela produz, sem precisar de uma tool específica.

Entender isso muda como você usa o MCP. As tools dedicadas (ads_get_campaigns, ads_account_summary) são atalhos convenientes para as perguntas mais comuns. O ads_query é a saída para todo o resto.

O que é GAQL

GAQL é a Google Ads Query Language. Parece SQL, mas não é. A sintaxe básica:

SELECT campaign.name, metrics.cost_micros, metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC
LIMIT 20

As diferenças em relação a SQL importam na prática:

• Não existe JOIN. Cada recurso (campaign, ad_group, keyword_view, search_term_view) já traz os campos dos níveis acima implicitamente. Você consulta keyword_view e tem acesso a campaign.name ali dentro.
• Não existe agregação explícita. Sem SUM, COUNT ou GROUP BY. A agregação é definida pelos campos que você seleciona — se você não pedir segments.date, o resultado já vem somado no período.
• Não existe subquery. Precisa cruzar duas coisas? São duas queries e o cruzamento é seu.

Micros: a pegadinha universal

Todo valor monetário na API vem em micros. metrics.cost_micros = 45230000 significa R$ 45,23. É dividir por um milhão. Se você já viu relatório dizendo que o cliente gastou 45 milhões, é isso.

Uma tool dedicada como ads_account_summary normalmente já converte para você. O ads_query não converte, porque devolve o resultado cru da API. Ao pedir análise para o modelo a partir de query livre, deixe explícito que os valores estão em micros — senão a leitura sai errada por seis casas decimais.

As queries que eu mais uso

Termos de busca que gastaram sem converter

SELECT search_term_view.search_term, campaign.name,
       metrics.cost_micros, metrics.clicks, metrics.conversions
FROM search_term_view
WHERE segments.date DURING LAST_30_DAYS
  AND metrics.conversions = 0
  AND metrics.cost_micros > 5000000
ORDER BY metrics.cost_micros DESC

Essa é a query de maior retorno imediato em qualquer conta. Filtra termos com zero conversão e mais de R$ 5 gastos. O output vira lista de negativas direto.

Quality score por keyword

SELECT ad_group_criterion.keyword.text,
       ad_group_criterion.quality_info.quality_score,
       ad_group_criterion.quality_info.creative_quality_score,
       ad_group_criterion.quality_info.post_click_quality_score,
       ad_group_criterion.quality_info.search_predicted_ctr,
       metrics.cost_micros
FROM keyword_view
WHERE segments.date DURING LAST_30_DAYS
  AND ad_group_criterion.quality_info.quality_score <= 5
ORDER BY metrics.cost_micros DESC

O valor aqui não é o score em si, é a decomposição. Os três subcomponentes dizem onde está o problema: anúncio irrelevante, landing page ruim ou CTR abaixo do esperado. Cada um pede uma ação diferente.

Desempenho por dia da semana e hora

SELECT segments.day_of_week, segments.hour,
       metrics.cost_micros, metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.id = 1234567890

Base para ajuste de programação de anúncios. Nenhuma tool dedicada costuma cobrir isso.

Ad strength dos RSAs

SELECT ad_group.name, ad_group_ad.ad.id,
       ad_group_ad.ad_strength,
       metrics.impressions, metrics.ctr
FROM ad_group_ad
WHERE ad_group_ad.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS

Todo anúncio com strength POOR ou AVERAGE é oportunidade de alcance perdido.

Auditoria de segmentação geográfica

SELECT campaign.name, campaign_criterion.location.geo_target_constant,
       campaign_criterion.negative
FROM campaign_criterion
WHERE campaign_criterion.type = 'LOCATION'

Roda isso em conta herdada e prepare-se para achar campanha segmentando Brasil inteiro quando o cliente atende uma cidade.

Por que isso funciona tão bem com IA

Aqui está o pulo do gato. Escrever GAQL na mão exige decorar nomes de recursos, campos e regras de compatibilidade — quais campos podem aparecer juntos, quais segmentos quebram a agregação. É chato e a documentação é extensa.

Um modelo de linguagem escreve GAQL razoavelmente bem, porque a documentação da API é pública e estruturada. Então o fluxo real é: você pergunta em português, o modelo traduz para GAQL, chama ads_query, recebe o resultado cru e interpreta.

Você deixa de precisar saber GAQL para ter o benefício de GAQL. É o mesmo ganho que descrevo no guia geral de Google Ads MCP: a IA não substitui seu julgamento, ela remove a barreira de sintaxe entre a pergunta e o dado.

Onde o modelo erra em GAQL

Vale saber para conferir:

Combinação inválida de campos. A API tem regras sobre quais campos podem coexistir numa query. O modelo às vezes junta coisas incompatíveis e a API rejeita. O erro vem claro, é só pedir para corrigir.

Nome de campo desatualizado. A API muda de versão e renomeia campos. Modelo treinado em documentação antiga usa o nome velho. Sintoma: erro de campo inexistente.

Segmento que estoura o resultado. Pedir segments.date sem LIMIT num período de 90 dias com muitas campanhas devolve milhares de linhas. Sempre limite.

Esquecer os micros na leitura. Já mencionei, mas é o erro mais frequente na interpretação, não na query.

Confundir conversions com all_conversions. São métricas diferentes. A primeira conta só as ações marcadas como conversão primária; a segunda conta tudo. Relatório que mistura as duas gera discussão desnecessária com cliente.

Quando usar tool dedicada em vez de query

Nem sempre ads_query é a melhor escolha. Tools dedicadas costumam tratar conversão de micros, aplicar defaults sensatos e retornar num formato mais limpo para o modelo interpretar.

Regra prática: se existe tool específica para o que você quer, use ela. Recorra ao ads_query quando a pergunta for fora do comum — cruzamento de segmentos, campos de configuração, auditoria estrutural, métricas que ninguém pede toda semana.

Um aviso sobre volume

Query livre em conta grande devolve muito dado, e todo esse dado entra no contexto do modelo. Isso custa tokens e, pior, degrada a qualidade da análise — modelo com dez mil linhas na frente perde o fio.

Filtre na query, não na leitura. WHERE agressivo, ORDER BY pelo que importa, LIMIT sempre. Se você precisa dos dados completos para arquivo, o caminho é jogar direto numa planilha via Sheets, não passar tudo pelo modelo.

No próximo artigo eu abro a segmentação geográfica — o ajuste mais barato e mais ignorado de conta de Google Ads.