Skip to main content
Glama

Run a read-only GAQL query

run_gaql
Read-only

Run custom read-only Google Ads Query Language SELECT queries for questions preset reports don't cover. Fetches up to 500 rows from a customer account.

Instructions

Runs any read-only Google Ads Query Language SELECT for questions the other tools don't cover (campaign_details, conversion_tracking, search_terms_report, ads_report and keywords_report cover the common reads). Returns up to 500 rows. Google rejects queries that break these rules: selecting or segmenting by segments.date needs a finite range in WHERE (segments.date DURING LAST_30_DAYS, or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'); click_view needs a single day (segments.date = 'YYYY-MM-DD'); every field used in WHERE or ORDER BY must also be in SELECT. Maximize clicks is target_spend in the API: campaign.target_spend.cpc_bid_ceiling_micros (there is no campaign.maximize_clicks). Unsure of a field's name or whether it fits this FROM? Look it up first with a query that has no FROM, which reads Google's field catalog instead of the account (any customer_id): SELECT name, category, selectable WHERE name LIKE '%search_term%', or SELECT attribute_resources, metrics, segments WHERE name = 'campaign' for what can be used FROM campaign.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "customer_id": "<customer_id>",
      "query": "<query>"
    },
    "name": "run_gaql"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesA GAQL SELECT statement
customer_idYesGoogle Ads customer ID, with or without dashes (from list_accounts)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.17.0
    • removedInput schema / properties / confirm_switch
      Removed value: -{
      -  "description": "Only after the user has agreed to spend their plan's account switch (a call answered \"Account switch:\"). Leave out otherwise",
      -  "type": "boolean"
      -}
  2. Changed1 schema field changedv0.14.1
    • addedInput schema / properties / confirm_switch
      Added value: +{
      +  "description": "Only after the user has agreed to spend their plan's account switch (a call answered \"Account switch:\"). Leave out otherwise",
      +  "type": "boolean"
      +}
  3. First observedv0.11.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds real value beyond them: a 500-row cap on results, Google-side validation rules that cause rejection (date segment ranges, click_view single-day, WHERE/ORDER BY fields must appear in SELECT), and the target_spend naming quirk for Maximize clicks. What it doesn't cover is pagination/beyond-500 behavior or the response shape, which matters for a query tool.

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

Conciseness4/5

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

Front-loaded with purpose and row limit, and nearly every sentence carries actionable constraint detail. The weakness is form: it is one dense unbroken paragraph mixing syntax rules, API naming quirks, and catalog-lookup instructions, which would be easier to scan as short bullets.

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 freeform query tool with only two parameters and no output schema, the description supplies exactly the missing context: what kinds of queries are valid, which syntax Google rejects, and how to discover unknown fields. Little an agent needs in order to call this correctly is absent.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaning the schema lacks: that the query must be a SELECT, and notably that a FROM-less catalog query accepts 'any customer_id', which clarifies the customer_id parameter's semantics in that mode. It does not restate field-level format details, which the schema already handles.

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?

Opens with a specific verb and resource: 'Runs any read-only Google Ads Query Language SELECT', and immediately scopes it as the catch-all for questions the named report tools don't cover. It names five sibling tools that handle common reads, so an agent can distinguish this escape hatch from the purpose-built reports without opening any schema.

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?

Explicit routing guidance: use this for questions the other tools don't cover, and it lists which siblings cover the common reads. It also supplies a concrete fallback procedure (query with no FROM to read Google's field catalog) for the case where the agent is unsure a field exists, including example queries.

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