Skip to main content
Glama
logly

mureo

by logly
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Hybrid

google_ads_search_terms_report

List real user search queries that triggered your ads, including impressions, clicks, cost, conversions, and CTR. Filter by campaign or ad group to review raw query logs for any reporting period.

Instructions

List actual user search queries that triggered ads in the account over a reporting window. Returns one row per search term shaped as {search_term, metrics}, where the metrics object contains impressions, clicks, cost_micros, cost (currency-formatted), conversions, and ctr. The rows are filterable by campaign_id and/or ad_group_id but those IDs are NOT echoed back in the output — scope your query before calling. Read-only. Use this for raw query logs when you need to eyeball the terms yourself. For rule-based add/exclude candidates use google_ads_search_terms_review; for intent-class distribution use google_ads_search_terms_analyze; for campaign-level aggregates without query breakdown use google_ads_performance_report.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
periodNoReporting window for the metrics. Default 'LAST_30_DAYS'. Use a shorter window (LAST_7_DAYS / LAST_14_DAYS) when diagnosing recent changes; use LAST_90_DAYS for trend baselines. Also accepts an explicit range in GAQL spelling — "BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'", both endpoints inclusive, in the account's time zone — for a window no trailing constant can reach (e.g. a single past calendar month). One asymmetry to know about: every constant except LAST_90_DAYS is resolved by Google Ads in the account's reporting time zone, whereas LAST_90_DAYS has no API constant and is expanded by mureo into the 90 days ending yesterday **on the server's date**, so its edges can differ by a day when the server and the account are in different zones. Pass an explicit range when the exact boundary matters.
ad_group_idNoRestrict results to a single ad group by numeric ID. Omit to include all ad groups under the campaign filter (or the entire account if campaign_id is also omitted).
campaign_idNoRestrict results to a single campaign by numeric ID. Omit to include all campaigns.
customer_idNoGoogle Ads customer ID as a 10-digit string without dashes (e.g. '1234567890'). Optional — falls back to GOOGLE_ADS_CUSTOMER_ID / GOOGLE_ADS_LOGIN_CUSTOMER_ID from the configured credentials when omitted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.17.1
    • addedInput schema / properties / period / anyOf
      Added value: +[
+  {
+    "enum": [
+      "TODAY",
+      "YESTERDAY",
+      "THIS_WEEK_SUN_TODAY",
+      "THIS_WEEK_MON_TODAY",
+      "LAST_BUSINESS_WEEK",
+      "LAST_WEEK_SUN_SAT",
+      "LAST_WEEK_MON_SUN",
+      "LAST_7_DAYS",
+      "LAST_14_DAYS",
+      "LAST_30_DAYS",
+      "LAST_90_DAYS",
+      "THIS_MONTH",
+      "LAST_MONTH"
+    ],
+    "type": "string"
+  },
+  {
+    "pattern": "\\ABETWEEN '([0-9]{4}-[0-9]{2}-[0-9]{2})' AND '([0-9]{4}-[0-9]{2}-[0-9]{2})'\\Z",
+    "type": "string"
+  }
+]
    • changedInput schema / properties / period / description
      Previous value: -"Reporting window for the metrics. Default 'LAST_30_DAYS'. Use a shorter window (LAST_7_DAYS / LAST_14_DAYS) when diagnosing recent changes; use LAST_90_DAYS for trend baselines."New value: +"Reporting window for the metrics. Default 'LAST_30_DAYS'. Use a shorter window (LAST_7_DAYS / LAST_14_DAYS) when diagnosing recent changes; use LAST_90_DAYS for trend baselines. Also accepts an explicit range in GAQL spelling — \"BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'\", both endpoints inclusive, in the account's time zone — for a window no trailing constant can reach (e.g. a single past calendar month). One asymmetry to know about: every constant except LAST_90_DAYS is resolved by Google Ads in the account's reporting time zone, whereas LAST_90_DAYS has no API constant and is expanded by mureo into the 90 days ending yesterday **on the server's date**, so its edges can differ by a day when the server and the account are in different zones. Pass an explicit range when the exact boundary matters."
    • removedInput schema / properties / period / enum
      Removed value: -[
-  "TODAY",
-  "YESTERDAY",
-  "LAST_7_DAYS",
-  "LAST_14_DAYS",
-  "LAST_30_DAYS",
-  "LAST_90_DAYS",
-  "THIS_MONTH",
-  "LAST_MONTH"
-]
  2. Changed1 schema field changedv0.10.37
    • addedInput schema / additionalProperties
      Added value: +false
  3. Addedv0.10.11
  4. Removedv0.10.9
  5. Addedv0.9.12
  6. Removedv0.9.6
  7. Addedv0.9.2
  8. Removedv0.9.1
  9. Addedv1.0.5

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden, and it delivers: it explicitly declares "Read-only," specifies the return shape {search_term, metrics} with the exact metric list, and discloses the non-obvious behavioral gotcha that campaign_id/ad_group_id filters are "NOT echoed back in the output — scope your query before calling." The only gap is silence on row limits/pagination or ordering, which matters for a raw-query-log 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?

The description is dense but every sentence earns its place: purpose, output shape, filtering gotcha, read-only declaration, usage context, alternative routing. Key information is front-loaded (purpose and output shape come first), though the long alternatives sentence at the end makes it slightly heavier than strictly necessary.

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

Completeness4/5

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

Given there is no output schema and no annotations, the description correctly explains the return shape and metric composition, the filtering behavior, and the read-only safety profile. The schema covers the period semantics in depth. The remaining gap — pagination or item-count limits for a report that can span 90 days of raw queries — is the only thing an agent might still be unsure about.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3 and the schema itself is rich — the period parameter explains constants vs explicit BETWEEN ranges, timezone semantics, and the LAST_90_DAYS asymmetry. The description adds marginal semantic value by noting campaign_id/ad_group_id are filters rather than output fields, but it does not need to compensate for any schema gap.

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?

States a specific verb and resource: "List actual user search queries that triggered ads in the account over a reporting window." It goes beyond a generic report label by defining the unit of output (one row per search term) and the output shape. It explicitly distinguishes itself from the three sibling tools it is not (search_terms_review, search_terms_analyze, performance_report).

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?

Provides explicit when-to-use guidance: "Use this for raw query logs when you need to eyeball the terms yourself." It then names the exact alternatives and the conditions selecting them — rule-based add/exclude candidates (search_terms_review), intent-class distribution (search_terms_analyze), campaign-level aggregates (performance_report). Nothing is left for the agent to infer.

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

Install Server

Other Tools