google-ads-mcp

Overview Schema Source Related Servers Score Discussions Admin

google_ads_query

Read-only

Executes GAQL queries against Google Ads customer accounts to retrieve campaign, ad group, keyword, and performance data.

Instructions

Run a GAQL (Google Ads Query Language) query against a specific customer account.

GAQL is SQL-like: SELECT ... FROM <single_resource> WHERE ... ORDER BY ... LIMIT .... No JOINs; attribute fields from related resources by selecting them directly. Common resources: campaign, ad_group, keyword_view, search_term_view, shopping_performance_view, customer, customer_client, conversion_action, change_event, change_status, recommendation, asset, asset_group.

Use google_ads_describe_resource first if unsure of field names on a new resource; saves a FIELD_NOT_FOUND roundtrip.

Args: customer_id: 10-digit customer_id (no hyphens) for the account to query. gaql: the full GAQL query string (must start with SELECT; no semicolons). max_rows: if set, stop streaming after this many rows. Defaults to unbounded (the 64 MB response cap still applies). convert_micros: if True (default), also emit _units alongside any _micros field (divided by 1,000,000). E.g. cost_micros = 12345678 → cost_units = 12.345678.

Example queries:

SELECT campaign.id, campaign.name, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50

SELECT ad_group.name, ad_group_criterion.keyword.text, metrics.impressions, metrics.clicks FROM keyword_view WHERE segments.date DURING LAST_30_DAYS

SELECT segments.product_item_id, metrics.conversions_value FROM shopping_performance_view WHERE segments.date DURING LAST_30_DAYS

Gotchas (surface to user where relevant):

metrics.cost_micros: 1 unit = $0.000001. Divide by 1M for currency.
LAST_30_DAYS = 30 days ending YESTERDAY (today excluded).
Last 72h data is partial; conversions retroactively re-attribute.
Zero-metric rows are excluded when segmenting by date.
Response cap is 64 MB per call; split by date range for huge reports.
GAQL IN (...) clause is capped at 20,000 items.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`gaql`	Yes
`max_rows`	No
`customer_id`	Yes
`convert_micros`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 9, 2026

TDQS

A4.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description aligns with that. It goes deeper by disclosing important behavioral traits: unbounded streaming until a 64 MB cap, the convert_micros transformation behavior, zero-metric row exclusion, LAST_30_DAYS meaning today excluded, and the 72-hour data partiality. This adds meaningful value beyond the annotations; however, it doesn't explicitly state the return format or error behavior beyond the mention of FIELD_NOT_FOUND saving a roundtrip.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: the GAQL overview, common resources, usage tip, parameter docs, examples, and gotchas all serve a purpose. It is front-loaded with the core purpose and syntax, followed by actionable examples and edge cases. The structure makes it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex query tool with 4 parameters and zero schema coverage, the description is remarkably complete. It covers syntax, common resources, examples, conversions, streaming limits, response caps, date semantics, and typical pitfalls. The output schema is present, so the return shape doesn't need to be described in prose. Nothing essential is missing for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it succeeds. Each parameter is explained with type, defaults, and behavioral consequences: customer_id format (10-digit, no hyphens), gaql syntax requirements, max_rows streaming stop behavior, and convert_micros with a concrete example. This exceeds what the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Run a GAQL (Google Ads Query Language) query against a specific customer account." It clearly distinguishes from siblings like google_ads_list_accessible_customers or google_ads_describe_resource, which are about listing accounts or exploring schemas rather than executing queries. The GAQL grammar explanation and examples remove ambiguity about what the tool executes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to use google_ads_describe_resource first if unsure of field names, which routes the agent to the correct alternative. It also provides concrete example queries, common resources, and structural rules (SELECT start, no semicolons, no JOINs), giving clear guidance on when and how to use this tool versus siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server