paid_search_overview
How much are we spending on Google Ads and how efficient is it? Total ad cost, average CPC, cost per conversion, and paid conversions for the WHOLE DOMAIN — optionally RANKED by search term / bidded keyword / page / ad group / campaign / campaign type / intent / category (group_by), sliced by search term / bidded keyword / ad group / intent / page / category / country / device / campaign / campaign type, and compared to a prior period. Filters and breakdowns COMBINE, in EITHER direction: intent:'VPS Hosting' + group_by:'page' is the same drill as QWA's paid INTENT tab → "By pages", and keyword:'example-brand' + group_by:'page' answers "for this search term, which landing pages" — the inverse of page:'…' + group_by:'keyword'. Both cross-filter to the SAME intersection, so pick whichever grain the question names first. For a CHEAPEST/LEAST question you must also flip the ranking — sort_by:'cost_per_conversion' + sort_direction:'asc' — because the default desc returns the most EXPENSIVE pages, the exact inverse. Reports whole-domain Google Ads metrics — no segment needed (Google Ads has no per-segment scoping here). This tool does NOT expose Google Ads conversion rate; NEVER derive it as conversions/clicks — use conversions_overview with medium:'google/cpc', metrics:['conversion_rate']. For a complete paid-versus-organic channel comparison including conversions on both sides, use paid_organic_performance_comparison. This is ad SPEND & efficiency from your Google Ads account, NOT paid market share vs competitors (use market_share_overview with medium='google/cpc' for that). For per-segment paid auction coverage use paid_impression_share.
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": {
"date_range": "<date_range>"
},
"name": "paid_search_overview"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Restrict to ONE page. EXACT URL by default — matched literally, so `%`, `_` and a leading `-` in a percent-encoded URL such as "/web%20hosting" are DATA, not wildcards. Resolve it with list_filter_values(page) first. For a URL PATTERN ("top pages under /vps-hosting") pass page_match:"pattern" and supply your own % wildcards, e.g. "%/vps-hosting%" (QWA page_segment semantics). Unlike intent/category, page MAY be combined with group_by:"page" in either mode. | |
| top_n | No | How many rows to return when group_by is set (site total ignores this). | |
| device | No | Filter by device, e.g. "MOBILE" or "DESKTOP" | |
| intent | No | Restrict to ONE search intent, e.g. "VPS Hosting" — mirrors QWA's paid INTENT drill. Combine with group_by:"page" for that intent's landing pages by cost / cost per conversion. Resolve the exact value with list_filter_values(intent) first. Rejected together with group_by:"intent". | |
| country | No | Filter by country, e.g. "usa" | |
| keyword | No | Restrict to ONE search term — the query that actually triggered the ad, e.g. "example-brand". Combine with group_by:"page" for that term's landing pages, or with group_by:"campaign_name" for the campaigns buying it. Matched EXACTLY: `%`, `_` and a leading `-` are DATA, not wildcards. Resolve the exact value with list_filter_values(query) or a group_by:"keyword" read first. For a FAMILY of terms use group_by:"keyword" and read the rows — there is no pattern mode. Rejected together with group_by:"keyword". | |
| metrics | No | Which paid metrics to return; defaults to cost, cpc, cost_per_conversion, conversions. Also: clicks, impressions, ctr. | |
| segment | No | Not needed — paid_search_overview is whole-domain (Google Ads has no per-segment scoping here). Ignored if passed; a soft note is returned for a non-default segment. | |
| sort_by | No | Which metric ranks the group_by rows. Defaults to the FIRST entry in metrics; must itself be present in metrics. | |
| campaign | No | Filter by campaign name (Google Ads campaign) | |
| category | No | Restrict to ONE content category, e.g. "Hosting" — mirrors QWA's paid CATEGORY tab, which sits beside INTENT and offers the same page drill. Resolve the exact value with list_filter_values(category) first: this match is case-SENSITIVE, so a hand-typed category with different casing can under-report. Rejected together with group_by:"category". | |
| group_by | No | Rank the metrics BY this attribute (top-N) instead of returning a single whole-domain total. `keyword` = the actual search term that triggered the ad; `campaign_keyword` = the bidded keyword you targeted in the campaign; also page, ad group, campaign, campaign type, intent or category. | |
| filter_op | No | How to match the campaign filter value (default exact match) | eq |
| date_range | Yes | Explicit date range, e.g. "2026-05-01 to 2026-05-31". Both endpoints are INCLUSIVE — the END day is covered (a 7-day range = 7 days). Quattr weeks run Sunday–Saturday; for "last week" use the most recent complete Sun–Sat span. | |
| page_match | No | How `page` is matched. "exact" (default) treats the value as a literal URL — the right choice for a value resolved via list_filter_values, and the only one that cannot silently over-match a percent-encoded URL. "pattern" opts into wildcard matching, where `%` stands for any run of characters and `_` for exactly one, for prefix/substring reads like "%/vps-hosting%". Ignored when `page` is omitted. | exact |
| granularity | No | Return a whole-domain TIME SERIES bucketed by day / week / month / quarter instead of a single total — e.g. "weekly ad spend over the last 13 weeks". Mutually exclusive with group_by and comparison_range. | |
| adgroup_name | No | Restrict to ONE Google Ads ad group, e.g. "Brand — Exact". Matched EXACTLY. There is no pre-listed value set for it: enumerate with group_by:"adgroup_name" and pass a value from those rows (a ranked top-N, so a small ad group may not appear). Combine with group_by:"keyword" or "page" to break that ad group down. Rejected together with group_by:"adgroup_name". | |
| campaign_type | No | Filter by campaign type, e.g. "SEARCH" or "SHOPPING" | |
| sort_direction | No | Ranking direction for group_by rows. Default "desc" (biggest first) answers "where does the spend go". Use "asc" for EFFICIENCY questions — the CHEAPEST cost per conversion, the lowest CPC — where desc returns the exact inverse of what was asked. Ascending a cost ratio automatically EXCLUDES rows whose denominator is zero (no conversions / no clicks), because their 0/null ratio would otherwise crowd every genuinely converting row out of the top-N; the response discloses the exclusion. | desc |
| date_range_mode | No | REQUIRED when granularity is set. Use "calendar" for YTD or another explicit calendar period: keep the requested start and return only complete buckets inside it. Use "rolling" for "last N days/weeks/months/quarters": preserve N complete buckets by shifting the full window backward when needed. | |
| campaign_keyword | No | Restrict to ONE BIDDED keyword — the term you targeted in the campaign, which is not necessarily the search term that matched it (that is `keyword`). Matched EXACTLY. There is no pre-listed value set for it: enumerate with group_by:"campaign_keyword" and pass a value from those rows (a ranked top-N, so a long-tail bid may not appear). Combine with group_by:"keyword" to see which real search terms a bidded keyword captured. Rejected together with group_by:"campaign_keyword". | |
| comparison_range | No | Explicit comparison range for period-over-period, e.g. "2026-04-01 to 2026-04-30" |