Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(google-ads): realign skills with new MCP server surface, relax prescription

Tong5875e1cf7692
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 9090ebfb..43109d38 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "The official Google Ads + SEO plugin from AdsAgent. SEO and Google Ads skills for Claude Code.",
- "version": "0.12.1"
+ "version": "0.13.0"
},
"plugins": [
{
"name": "toprank",
"source": "./",
"description": "The official Google Ads + SEO plugin from AdsAgent. SEO analysis, Google Ads management, keyword research, content optimization, schema markup, and meta tags optimization.",
- "version": "0.12.1",
+ "version": "0.13.0",
"author": {
"name": "AdsAgent",
"url": "https://adsagent.org"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 920f0edf..5d03727a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "toprank",
- "version": "0.12.1",
+ "version": "0.13.0",
"description": "The official Google Ads + SEO plugin from AdsAgent. SEO analysis, Google Ads management, keyword research, content optimization, and schema markup tools powered by Google Search Console and Google Ads APIs.",
"author": {
"name": "AdsAgent",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 251958ac..ef91c23b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.13.0] — 2026-04-24
+
+### Changed
+- **Realigned google-ads skills with the new MCP server surface.** The AdsAgent MCP server consolidated read-only tools behind `runScript` (a JS sandbox exposing `ads.gaql()` and `ads.gaqlParallel()`), retired the per-surface helpers (`listCampaigns`, `getKeywords`, `getSearchTermReport`, `getCampaignPerformance`, `getImpressionShare`, `runGaqlQuery`, `getAccountInfo`, `getCampaignSettings`, `listAds`, `listAdGroups`, etc.), and removed the bespoke `audit()` tool. Skills referenced those tools by name in workflow tables, reference docs, and SKILL bodies — guidance that no longer applied.
+- **Relaxed the prescriptive style.** Skills now provide frameworks, scoring rubrics, benchmarks, business-context schemas, and operational discipline — not step-by-step "call X then Y" choreography. Tool routing is delegated to the server's own MCP instructions, which already tell the agent to fan out reads through `runScript` + `gaqlParallel` and route mutations through dedicated write tools. The agent does the heavy lifting; the skill supplies the judgment.
+- **`ads/SKILL.md`** — dropped the "Available Tools" enumeration and the prescriptive "Performance Summary / Waste Audit / …" workflow playbooks. Kept operating principles, the reference-routing table, the account-baseline contract, change-tracking discipline, and conditional handoffs.
+- **`ads-audit/SKILL.md`** — replaced the now-removed `audit(accountId, days=30)` payload contract with a description of the GAQL surfaces a complete audit needs (customer, campaign, ad_group, keyword_view, search_term_view, conversion_action, ad_group_ad, campaign_criterion for geo, change_event). The agent assembles the dataset via one `runScript` + `gaqlParallel` call, optionally seeded by the server's `adsagent://playbooks/audit-account` MCP resource. Kept the 7-dimension scoring rubric, business-context and persona schemas + filesystem contract, encoded heuristics, and the impression-share interpretation matrix.
+- **`ads-copy/SKILL.md`** and **`ads-landing/SKILL.md`** — replaced helper-tool sequences ("call `listAds`, then `getKeywords`, then …") with GAQL surface descriptions the agent can fan out in one `runScript` call.
+- **`shared/preamble.md`** — Step 5 now describes the read/write split (runScript for reads, dedicated tools for mutations) and points at the server's playbook resources, instead of pushing `runGaqlQuery` against a 50-row limit.
+- **`ads/references/session-checks.md`**, **`ads-audit/references/persona-discovery.md`**, **`ads-audit/references/business-context.md`**, **`ads-audit/references/account-health-scoring.md`** — scrubbed dead tool names; persona discovery and the audit website-resolution step now reference GAQL surfaces directly.
+
+### Removed
+- **`ads/references/workflow-playbooks.md`** — the server now ships `adsagent://playbooks/audit-account` and `adsagent://playbooks/explain-regression` as MCP resources covering the same ground; maintaining a parallel skill-side copy guarantees drift.
+- **`shared/gaql-cookbook.md`** — built around `runGaqlQuery`'s 50-row limit, which no longer applies. The server's own MCP instructions already teach the `gaqlParallel` fan-out pattern with worked examples.
+
+---
+
## [0.12.1] — 2026-04-22
### Changed
diff --git a/VERSION b/VERSION
index 34a83616..54d1a4f2 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.12.1
+0.13.0
diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.md
index 411468c1..52b92b44 100644
--- a/google-ads/ads-audit/SKILL.md
+++ b/google-ads/ads-audit/SKILL.md
@@ -6,102 +6,69 @@ argument-hint: "<account name or 'audit my ads'>"
# Google Ads Audit
-Diagnose account health and persist business context for downstream skills (`/ads`, `/ads-copy`, `/ads-landing`). Diagnose only — never mutate the account from this skill. The user runs `/ads` to execute fixes.
+Diagnose account health and persist business context for downstream skills (`/ads`, `/ads-copy`, `/ads-landing`). **Read-only** — never mutates the account. The user runs `/ads` to execute fixes you recommend.
## Setup
-Follow `../shared/preamble.md` for MCP detection, token, and account selection.
+Follow `../shared/preamble.md` — MCP detection, API key, account selection.
## Filesystem contract (MUST persist)
| Artifact | Path | When |
|---|---|---|
-| Business context | `{data_dir}/business-context.json` | First full audit, or refresh if `audit_date` > 90 days old. Skip on scoped audits if file is fresh. |
+| Business context | `{data_dir}/business-context.json` | First full audit, or refresh when `audit_date` is >90 days old. Skip on scoped audits if file is fresh. |
| Personas | `{data_dir}/personas/{accountId}.json` | Every full audit. |
-These files are the handoff to every other ads skill. If they're missing, downstream skills break — write them even if the report itself is short.
+These are the handoff to every other ads skill — write them even if the report itself is short. Otherwise `/ads-copy` and `/ads-landing` operate without business context and produce generic output.
**business-context.json schema:** `business_name, industry, website, services[], locations[], target_audience, brand_voice{tone, words_to_use[], words_to_avoid[]}, differentiators[], competitors[], seasonality{peak_months[], slow_months[], seasonal_hooks[]}, keyword_landscape{high_intent_terms[], competitive_terms[], long_tail_opportunities[]}, social_proof[], offers_or_promotions[], landing_pages{}, notes, audit_date, account_id`.
-**personas JSON schema:** `{account_id, saved_at, personas: [{name, demographics, primary_goal, pain_points[], search_terms[], decision_trigger, value}]}`. See `references/persona-discovery.md` for derivation rules.
+**personas JSON schema:** `{account_id, saved_at, personas: [{name, demographics, primary_goal, pain_points[], search_terms[], decision_trigger, value}]}`. See `references/persona-discovery.md`.
-## Policy freshness check (run before audit)
+## Policy freshness check (run first)
Read `../shared/policy-registry.json`. For each entry where `last_verified + stale_after_days < today`:
-- **High-volatility:** WebSearch the `area` for recent Google Ads changes; compare to `assumption`. If drift, banner the report and suggest registry update.
-- **Moderate-volatility:** Add a one-line "may warrant a check" note in the report.
-- **Stable:** Skip.
-
-If nothing is stale, no output.
-
-## Data pull
-
-Call `audit(accountId, days=30)` (max 90, capped by impression-share data limit). One call returns the full payload:
-
-```
-{
- account: { name, currency, timezone, autoTagging, trackingTemplate },
- summary: { totalSpend, totalConversions, totalConversionValue, totalClicks,
- totalImpressions, cpa, ctr, conversionRate, roas, activeCampaigns },
- pulse: { wasteRate, wasteUsd, demandCaptured, cpa },
- campaigns: [{ id, name, type, status, spend, conversions, cpa, ctr,
- impressionShare, budgetLostIS, rankLostIS,
- isMatrix, // "healthy" | "capital_problem" | "relevance_problem" | "structural_problem"
- biddingStrategy, targetCpa, searchPartners, displayNetwork,
- weightedQS, lowQSSpendPct, negativeKeywordCount,
- adGroups[], topAds[], topKeywords[], deviceBreakdown{} }],
- findings: { wastedKeywords[], wastedSearchTerms[], brandLeakage{},
- miningOpportunities[], budgetConstrainedWinners[], negativeConflicts[],
- hasAudienceSegments, conversionActions, matchTypeDistribution,
- assetCoverage, landingPages },
- errors?: []
-}
-```
-
-If `audit` errors out, surface and stop — don't fall back to helper tools.
-
-**Geo data is not in the audit payload.** If structure scoring needs it (multi-location accounts), run in parallel with scoring:
-
-```
-SELECT campaign.id, campaign.name, campaign_criterion.type,
- campaign_criterion.negative, campaign_criterion.location.geo_target_constant,
- campaign_criterion.proximity.radius, campaign_criterion.proximity.radius_units
-FROM campaign_criterion
-WHERE campaign.id IN (<in-scope ids>)
- AND campaign_criterion.type IN ('LOCATION', 'PROXIMITY')
-```
-`radius_units`: 0=meters, 1=km, 2=miles.
-
-**Skip scoring if** `summary.activeCampaigns == 0` or `summary.totalSpend == 0` — go straight to business context.
-
-## Scope handling
+- **High-volatility** → WebSearch the `area` for recent Google Ads changes; compare to `assumption`. If drift, banner the report and suggest registry update.
+- **Moderate-volatility** → one-line "may warrant a check" note.
+- **Stable** → skip silently.
-If the user narrows the audit ("focus on grooming", "campaign X", "just check waste"):
-- Match campaign names by case-insensitive substring. If no match, list available campaigns and ask.
-- Filter `campaigns[]` and `findings.*` arrays in memory before scoring — no extra API calls.
-- `summary.*` and `pulse.*` stay account-wide; note "Scoped to: X" in the report.
-- Conversion tracking is account-level regardless of scope.
-- Skip Phase 3 (business context refresh) on scoped audits if `business-context.json` is fresh.
+## Phase 1 — Pull the audit dataset
+
+Use a single `runScript` call with `ads.gaqlParallel` to fan out the queries an audit needs. The server's `adsagent://playbooks/audit-account` resource has a battle-tested baseline; extend it with what this rubric needs that isn't already there.
+
+A complete audit needs at minimum:
+
+- **Account / customer-level metrics** (`customer` resource) — totalSpend, conversions, conv-value, clicks, impressions for the audit window.
+- **Campaign-level performance** (`campaign`) — id, name, status, advertising_channel_type, bidding_strategy_type, network settings, search/top/abs-top impression share, budget-lost-IS, rank-lost-IS, status-rich metrics. Cap window at 90 days (impression-share data limit).
+- **Ad-group performance** (`ad_group`) — to attach top-line metrics under each campaign.
+- **Keyword performance with QS** (`keyword_view`) — text, match type, status, quality score (and components if needed), cost, clicks, conversions. Surfaces zombie keywords (0 impressions 30d), low-QS-with-spend, zero-converters.
+- **Search terms** (`search_term_view`) — for waste detection (clicks > 10, conv = 0) and brand-leakage detection (brand terms triggered by non-brand campaigns).
+- **Negative keywords** (`campaign_criterion` where `type='KEYWORD'` and `negative=TRUE`) — for negative-conflict detection and coverage.
+- **Conversion actions** (`conversion_action`) — count, status, primary-vs-secondary, counting type. STOP-condition input.
+- **Ad assets** (`ad_group_ad`) — RSA headlines/descriptions for asset-coverage scoring and topAds extraction.
+- **Geo targeting** (`campaign_criterion` where `type IN ('LOCATION','PROXIMITY')`) — for multi-location structure scoring. `radius_units`: 0=meters, 1=km, 2=miles.
+- **Recent change events** (`change_event`, max 30 days) — to flag recent edits that might explain regressions.
+
+Compute aggregates **in the script**, return summarized JSON. Don't return all rows — rank, slice, summarize. The agent narrates the result, the script does the math.
-## Audit field → dimension map
+`getRecommendations` is a useful cross-check for Google's own recommendation surface — call it as a separate tool after the runScript pass if you want to compare your findings to Google's.
-Use pre-computed fields before re-deriving anything:
+If a critical query errors out (auth, schema), surface the error and stop — don't fall back to a degraded audit.
-| Dimension | Primary fields |
-|-----------|---------------|
-| Conversion tracking | `account.autoTagging`, `findings.conversionActions`, `summary.totalConversions` |
-| Campaign structure | `campaigns[].name` (brand split), `campaigns[].adGroups[]`, `findings.matchTypeDistribution`, `campaigns[].negativeKeywordCount` |
-| Keyword health | `campaigns[].weightedQS`, `campaigns[].lowQSSpendPct`, `findings.wastedKeywords`, `pulse.wasteRate` |
-| Search term quality | `findings.wastedSearchTerms`, `findings.miningOpportunities`, `findings.brandLeakage`, `findings.negativeConflicts` |
-| Ad copy | `campaigns[].topAds[]`, `findings.assetCoverage` |
-| Impression share | `campaigns[].impressionShare`, `budgetLostIS`, `rankLostIS`, `isMatrix` (already classified) |
-| Spend efficiency | `pulse.wasteRate`, `pulse.wasteUsd`, `summary.cpa`, `campaigns[].cpa`, `findings.budgetConstrainedWinners` |
+**Skip scoring entirely if** `totalSpend == 0` or `activeCampaigns == 0`. Go straight to business context.
-Trust `isMatrix` and `pulse.*` as authoritative. Don't recompute.
+## Phase 2 — Scope handling
-## Scoring
+If the user narrows the audit ("focus on grooming", "campaign X", "just check waste"):
+
+- Match campaign names by case-insensitive substring. If no match, list available campaigns and ask.
+- Filter the in-memory dataset before scoring — no extra API calls.
+- Account-level dimensions (conversion tracking) stay account-wide. Note "Scoped to: X" in the report.
+- Skip Phase 4 (business context refresh) on scoped audits if `business-context.json` is fresh.
-Score each of the 7 dimensions 0–5 using `references/account-health-scoring.md`. Overall = round(sum × 100/35).
+## Phase 3 — Score
+
+Score each of the 7 dimensions 0–5 using `references/account-health-scoring.md`. Overall = `round(sum × 100 / 35)`.
| Score | Label | Meaning |
|---|---|---|
@@ -112,60 +79,60 @@ Score each of the 7 dimensions 0–5 using `references/account-health-scoring.md
| 4 | Good | Well-managed, minor opportunities |
| 5 | Excellent | Best-practice |
-Scope-aware: campaign-level dimensions reflect in-scope data only; account-level dimensions (conversion tracking) score account-wide with notes on scope impact.
-
-## Encoded heuristics (these aren't obvious — apply them)
+Scope-aware: campaign-level dimensions reflect in-scope data; account-level dimensions (conversion tracking) score account-wide with a note on scope impact.
-- **Weighted QS by spend, not by keyword count.** A QS-3 keyword burning $2k/mo matters infinitely more than a QS-3 keyword burning $5/mo.
-- **Brand leakage premium:** when brand campaigns are paused, brand traffic leaks to non-brand at 5–10× higher CPA. Always flag `findings.brandLeakage.detected`.
-- **Waste formula:** `pulse.wasteUsd` already = keyword waste (clicks > 10, conv = 0) + search-term waste. Report it directly; don't recompute.
-- **Display + Search mixed in one campaign:** structurally broken — Display traffic dilutes Search metrics and burns budget on unintended placements. Flag any campaign with `displayNetwork === true`.
-- **Zombie keywords:** 0 impressions for 30+ days clutter the account; recommend pause.
-- **Match type counting=Every vs One:** lead-gen should use One; e-commerce should use Every. Duplicates inflate conversion counts.
-- **STOP condition:** if conversion tracking scores 0–1, recommend pausing spend until tracking is fixed. Everything else is downstream of measurement.
+### Encoded heuristics — apply these, they aren't obvious
-## Impression Share Interpretation Matrix
+- **Weighted QS by spend, not by keyword count.** A QS-3 keyword burning $2,000/mo matters infinitely more than ten QS-3 keywords burning $5/mo combined.
+- **Brand-leakage premium.** When brand campaigns are paused or starved, brand traffic leaks to non-brand at 5–10× higher CPA. Always check whether brand terms appear in non-brand campaigns' search-term reports.
+- **Waste formula.** Keyword waste = clicks > 10 AND conversions = 0 AND cost > 0. Search-term waste = same, applied to actual queries. Sum them — that's the recoverable spend.
+- **Display + Search mixed in one campaign** is structurally broken — Display dilutes Search metrics and burns budget on unintended placements. Flag any campaign where `network_settings.target_content_network = TRUE` for a SEARCH channel campaign.
+- **Zombie keywords** (0 impressions for 30+ days) clutter reporting and confuse Google's ML — recommend pause.
+- **Counting type matters.** Lead-gen should use `ONE` per click; e-commerce should use `EVERY`. Wrong setting silently inflates or deflates conversions.
+- **STOP condition.** If conversion tracking scores 0–1, recommend pausing spend until tracking is fixed. Everything downstream of measurement is unreliable.
-`isMatrix` already encodes the diagnosis per campaign, but use this when explaining root cause:
+### Impression Share Interpretation Matrix
| | Rank-Lost < 30% | Rank-Lost 30–50% | Rank-Lost > 50% |
|---|---|---|---|
-| **Budget-Lost < 20%** | Healthy | QS/Bid problem | Quality crisis |
+| **Budget-Lost < 20%** | Healthy | QS / bid problem | Quality crisis |
| **Budget-Lost 20–40%** | Budget problem | Mixed (fix quality first) | Structural — too-competitive keywords |
-| **Budget-Lost > 40%** | Severe budget gap (highest-ROI fix if CPA is good) | Fix rank, then add budget | Fundamental misalignment — pause and restructure |
+| **Budget-Lost > 40%** | Severe budget gap (highest-ROI fix if CPA is good) | Fix rank first, then add budget | Fundamental misalignment — pause and restructure |
-## Business context
+## Phase 4 — Business context
-After scoring, derive what you can from the audit payload:
+Derive what you can from the data already pulled:
| Field | Source |
|---|---|
-| `business_name` | `account.name` |
-| `services` | campaign + ad group names, top keywords |
-| `locations` | `campaigns[].geoTargetType` + supplemental geo GAQL |
-| `brand_voice` | `campaigns[].topAds[]` headlines/descriptions |
-| `keyword_landscape.high_intent_terms` | converting keywords in `topKeywords` |
-| `keyword_landscape.competitive_terms` | keywords in campaigns where `isMatrix !== "healthy"` and `rankLostIS > 0.3` |
-| `keyword_landscape.long_tail_opportunities` | `findings.miningOpportunities` |
-| `website` | apex domain from ad final URLs |
+| `business_name` | Account name (from `customer.descriptive_name`) |
+| `services` | Campaign + ad-group names, top converting keywords |
+| `locations` | `campaign_criterion` LOCATION + PROXIMITY |
+| `brand_voice` | Top-performing RSA headlines / descriptions |
+| `keyword_landscape.high_intent_terms` | Converting keywords with strong CVR |
+| `keyword_landscape.competitive_terms` | Keywords in campaigns with high rank-lost-IS |
+| `keyword_landscape.long_tail_opportunities` | Converting search terms not yet promoted to keywords |
+| `website` | Apex domain from ad final URLs |
Then crawl the website (homepage + about + services + top 3 ad landing pages, parallel `WebFetch`) and merge into the schema. See `references/business-context.md` for the full crawl procedure.
-Always ask the user (rarely on websites): differentiators, competitors, seasonality. Ask everything else only if missing.
+Always ask the user (it's faster than guessing): differentiators, competitors, seasonality. Ask for everything else only if the data + crawl can't answer it.
+
+## Phase 5 — Personas
-## Personas
+Discover 2–3 personas from search terms, top keywords, ad-group themes, landing pages, geo, and device split — all from the dataset already in memory. Persist to `{data_dir}/personas/{accountId}.json`. Each persona must be grounded in **5+ actual search terms**; if not, drop it. See `references/persona-discovery.md`.
-Discover 2–3 personas from search terms, top keywords, ad group themes, landing pages, geo, and device split — all from the audit payload. Persist to `{data_dir}/personas/{accountId}.json`. Each persona must be grounded in 5+ actual search terms; if not, drop it. See `references/persona-discovery.md`.
+## Phase 6 — Report
-## Report
+Lead with the verdict, then the top 3 actions (with dollar impact when possible), then the scorecard, then evidence for dimensions scoring 0–2 only. Cite specific campaigns, keywords, and dollar amounts. Cap at ~80 lines.
-Lead with verdict, then top 3 actions, then scorecard, then evidence for dimensions scoring 0–2 only. Cite specific campaigns, keywords, and dollar amounts. Keep it under ~80 lines — the model is responsible for not duplicating findings across sections.
+End with a single closing line after the handoff to `/ads`:
-End the report with a single closing line (after the handoff to `/ads`): *"Your audit history is saved to your AdsAgent account — view it at https://adsagent.org."* One line, no extra framing.
+> *Your audit history is saved to your AdsAgent account — view it at https://adsagent.org.*
## Guardrails
-1. **Read-only skill.** Diagnose; don't mutate. All fixes go through `/ads`. End the report with one handoff to `/ads` (or `/ads-copy`, `/ads-landing`) tied to the #1 action item.
-2. **STOP condition:** if conversion tracking scores 0–1, recommend pausing spend until fixed before recommending anything else.
-3. **Always persist** `business-context.json` and `personas/{accountId}.json` even if the report is short — downstream skills depend on them.
-4. **Name names:** every finding references specific campaigns/keywords/search terms with dollar amounts. "Some keywords are underperforming" is not a finding.
+1. **Read-only skill.** Diagnose; don't mutate. Every fix routes through `/ads` (or `/ads-copy`, `/ads-landing`). End the report with one handoff tied to the #1 action.
+2. **STOP condition** — if conversion tracking scores 0–1, recommend pausing spend until it's fixed before recommending anything else. Everything downstream is meaningless without measurement.
+3. **Always persist** `business-context.json` and `personas/{accountId}.json` even if the report itself is short — downstream skills depend on them.
+4. **Name names.** Every finding cites specific campaigns, keywords, search terms, and dollar amounts. "Some keywords are underperforming" is not a finding.
diff --git a/google-ads/ads-audit/references/account-health-scoring.md b/google-ads/ads-audit/references/account-health-scoring.md
index 7beabffb..e1e302cd 100644
--- a/google-ads/ads-audit/references/account-health-scoring.md
+++ b/google-ads/ads-audit/references/account-health-scoring.md
@@ -129,7 +129,7 @@ In the RSA + Smart Bidding era, creative variety is how Google's ML finds the ri
## Impression Share
-**Data limit:** `getImpressionShare` supports max 90 days (not 365 like other tools). For GAQL impression share queries, the same 90-day practical limit applies. Do not use `LAST_365_DAYS` for impression share data.
+**Data limit:** Impression-share metrics (`metrics.search_impression_share`, `metrics.search_top_impression_share`, `metrics.search_absolute_top_impression_share`, `metrics.search_budget_lost_impression_share`, `metrics.search_rank_lost_impression_share`) only return up to 90 days of history in GAQL. Do not use `LAST_365_DAYS` for any query that selects them.
*Diagnosed across two layers:*
- **Lost IS (Rank)** = Layer 2 relevance problem. The auction is telling you your Ad Rank is low. Fix with better ads, tighter themes, better landing pages — not more money.
diff --git a/google-ads/ads-audit/references/business-context.md b/google-ads/ads-audit/references/business-context.md
index 61166d53..7b147001 100644
--- a/google-ads/ads-audit/references/business-context.md
+++ b/google-ads/ads-audit/references/business-context.md
@@ -7,7 +7,7 @@ This reference covers the website crawl procedure and business context JSON sche
### Step 1: Resolve the website URL
Find the website URL from Phase 1 data, in priority order:
-1. Ad final URLs from `listAds` — extract the root domain (e.g., `https://example.com`). Normalize to the apex domain (strip `www.` and subdomain prefixes) before frequency-counting across all ads. Use the most common domain.
+1. Ad final URLs already pulled in Phase 1 (the `ad_group_ad` rows from the audit dataset) — extract the root domain (e.g., `https://example.com`). Normalize to the apex domain (strip `www.` and subdomain prefixes) before frequency-counting across all ads. Use the most common domain.
2. If no URL found in ad data, ask the user: "What's your website URL?"
### Step 2: Crawl the website
diff --git a/google-ads/ads-audit/references/persona-discovery.md b/google-ads/ads-audit/references/persona-discovery.md
index 4921f07b..38084860 100644
--- a/google-ads/ads-audit/references/persona-discovery.md
+++ b/google-ads/ads-audit/references/persona-discovery.md
@@ -4,15 +4,15 @@ Discover 2-3 customer personas from the ad data. This runs in parallel with busi
## Data Sources for Persona Construction
-| Source | What it reveals | How to access |
+| Source | What it reveals | Where it lives in the audit dataset |
|--------|----------------|---------------|
-| Search terms | What customers actually search for — their language, pain points, urgency | `getSearchTermReport` from Phase 1 |
-| Converting keywords | What they buy — the terms that lead to conversions reveal purchase intent | `getKeywords` filtered to converting |
-| Ad group themes | How the business segments its services — each theme may serve a different persona | Ad group data from Phase 1 |
-| Landing page URLs | Where they land — different pages suggest different customer journeys | `listAds` final URLs from Phase 1 |
-| Geographic data | Where they are — metro vs rural, specific cities | `getCampaignSettings` location targets |
-| Device split | How they search — mobile-heavy suggests on-the-go/urgent need | Infer from ad performance patterns |
-| Time-of-day patterns | When they search — business hours vs evenings vs weekends | `getCampaignPerformance` daily data |
+| Search terms | What customers actually search for — their language, pain points, urgency | `search_term_view` rows |
+| Converting keywords | What they buy — terms that lead to conversions reveal purchase intent | `keyword_view` rows filtered to `metrics.conversions > 0` |
+| Ad-group themes | How the business segments services — each theme may serve a different persona | `ad_group.name` distribution |
+| Landing page URLs | Where they land — different pages suggest different customer journeys | `ad_group_ad.ad.final_urls` |
+| Geographic data | Where they are — metro vs rural, specific cities | `campaign_criterion` LOCATION + PROXIMITY rows |
+| Device split | How they search — mobile-heavy suggests on-the-go / urgent need | Segment any `metrics.*` query by `segments.device` |
+| Time-of-day patterns | When they search — business hours vs. evenings vs. weekends | Segment by `segments.day_of_week` and `segments.hour` |
## Persona Template
diff --git a/google-ads/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.md
index 90abeef2..7f7141c5 100644
--- a/google-ads/ads-copy/SKILL.md
+++ b/google-ads/ads-copy/SKILL.md
@@ -127,158 +127,67 @@ Based on the competitive landscape, choose the strongest angle:
| Unique service offering | The specific feature itself | "Same-Day Emergency Visits" |
| Crowded market, no clear advantage | Speed, convenience, or customer experience | "Book Online — Arrive in 1hr" |
-## Workflow
+## What to pull before writing
-### 1. Understand the brief
+Copy should be grounded in what converts, not guesses. One `runScript` call with `ads.gaqlParallel` covers everything you need for almost any copy job — fan out the surfaces below in parallel:
-Detect or ask:
-- What product/service is this ad for?
-- Target audience or segment?
-- Which campaign/ad group? (pull with `listCampaigns` → `listAdGroups`)
-- Landing page URL?
-- Any geographic targeting?
+- **Existing ads** (`ad_group_ad`) — current headlines, descriptions, ad-strength, per-ad clicks / CTR / conversions. The baseline to beat.
+- **Keywords with quality info** (`keyword_view`) — what's already converting and which QS components are hurting.
+- **Search terms** (`search_term_view`) — the actual phrases real customers are typing. The single best source of language for headlines.
+- **Campaign-level CTR / CVR** (`campaign`) — the benchmark each variant has to beat.
-Cross-reference against the business context — if the user says "write copy for boarding" and context has boarding details, you already know the angles.
+For brand-wide rewrites, correlate everything in one fan-out. For a single ad group, add `WHERE ad_group.id = …` to each query — the marginal cost is zero. If the user has a database with lead / conversion outcome data, mine it: customer language > marketing language.
-### 2. Research what's working
+Layer on the seasonality and keyword-landscape context from `business-context.json`. Peak months call for urgency, slow months for evergreen value props. Highly competitive heads need sharper differentiation; long-tail tails need closer intent match.
-Pull data before writing — copy should be grounded in what converts, not guesses.
+## RSA mechanics
-**Current ad performance (use GAQL for multi-campaign research, see `../shared/gaql-cookbook.md`):**
+Google RSA: up to **15 headlines (30 chars max)** and **4 descriptions (90 chars max)**. A single character over = rejected. Always count.
-If the user specified a single campaign/ad group, use helper tools directly. If researching across campaigns (common for brand-wide copy refresh), use GAQL:
-- GAQL "Ad copy" query → existing headlines/descriptions and their metrics across all campaigns
-- GAQL "Keywords with QS" query → active keywords and what's converting
-- GAQL "Search terms" query → actual user queries (reveals real language and intent)
-- GAQL "Impression share" query → CTR/conversion benchmarks to beat
+The headline formula table (27 formulas across 8 categories) and description formula table (5 formulas) live in `references/rsa-best-practices.md` — that file is the source of truth for what to actually write.
-For single-campaign work, the per-campaign helpers are simpler:
-- `listAds(campaignId)` — existing headlines/descriptions
-- `getKeywords(campaignId)` — active keywords
-- `getSearchTermReport(campaignId)` — actual user queries
-- `getCampaignPerformance(campaignId)` — CTR benchmarks
+**Pinning strategy:**
-**Use seasonality context.** If business context shows peak months, factor that into copy urgency. During slow months, lean on evergreen value props. During peaks, lean on scarcity and timeliness.
-
-**Use keyword landscape context.** For competitive terms (high CPC, many bidders), copy must differentiate harder — lead with what's unique, not what everyone says. For long-tail terms, match the specific intent closely.
-
-**If the user has a database with lead/conversion data**, query it to find which keywords and messaging actually convert. The language paying customers use is the language your ads should mirror.
-
-### 3. Generate RSA components
-
-Google RSA: up to **15 headlines** (30 chars max) and **4 descriptions** (90 chars max). Google's AI mixes and matches them.
-
-**Always count characters. Flag any that exceed limits. A single character over = rejected by Google.**
-
-#### Headline & Description Formulas
-
-See `references/rsa-best-practices.md` — Headline Formula Table (27 formulas across 8 categories) and Description Formula Table (5 formulas). Use those as the source of truth for all copy generation.
-
-**Headline selection rules:**
-- Generate 3-4 headlines per category for a total of 12-15
- Pin 1 Service+Location headline to Position 1 (highest relevance impact)
-- Pin 1 CTA headline to Position 3 (Google shows H3 less often — make it count when shown)
-- Leave Position 2 unpinned to let Google test Value Prop, Trust, and Differentiator headlines
-- Never pin more than 3 headlines total — over-pinning reduces Google's optimization ability
-
-**Description selection rules:**
-- Always generate 4 descriptions (the RSA maximum)
-- D1 should be the strongest all-around description (core value + location) — it shows most often
-- D2 should emphasize the primary differentiator
-- D3 should lead with trust/social proof
-- D4 should be seasonal or offer-based (swap this out when promotions change)
-- Every description must end with a CTA verb: Call, Book, Get, Schedule, Request, Visit, Contact
-- Character count is STRICT: 90 chars max. Measure before finalizing. It's better to be 85 chars and punchy than 90 chars and cramped
-
-### 4. Present variants
-
-Show 2-3 variants, each with a distinct messaging angle. Name the angle so it's clear what's being tested.
+- Pin 1 CTA headline to Position 3 (Google shows H3 less often — make it count)
+- Leave Position 2 unpinned for Google to test value-prop, trust, and differentiator headlines
+- Never pin more than 3 total — over-pinning kneecaps Google's optimization
-```
-VARIANT A: "[Angle Name — e.g., Trust & Experience]"
- Target persona: [persona name from {data_dir}/personas/]
- H1 [Pin 1]: [Service] in [Location] (XX chars)
- H2: [Value prop headline] (XX chars)
- H3: [Trust headline] (XX chars)
- H4: [CTA headline] (XX chars)
- ... (up to 15 headlines)
- D1: [Core value + location — max 90 chars] (XX chars)
- D2: [Differentiator + CTA — max 90 chars] (XX chars)
- D3: [Trust + proof — max 90 chars] (XX chars)
- D4: [Urgency/offer — max 90 chars] (XX chars)
+**Description ordering:**
-VARIANT B: "[Different Angle — e.g., Price & Value]"
- Target persona: [persona name]
- H1 [Pin 1]: ...
- ...
-```
+- D1 = strongest all-around (core value + location). Shows most often.
+- D2 = primary differentiator
+- D3 = trust / social proof
+- D4 = seasonal or offer-based (the slot you swap out when promotions change)
+- Every description ends with a CTA verb: Call, Book, Get, Schedule, Request, Visit, Contact
+- Punchy at 85 chars beats cramped at 90
-Always show character counts. Always show pin positions. Always name the target persona.
+## A/B testing
-**Variant differentiation rules:**
-- Each variant must test a meaningfully different angle — not minor word swaps
-- Good test: "Trust & Expertise" vs "Speed & Convenience" vs "Price & Value"
-- Bad test: "Call Today" vs "Call Now" vs "Call Us" (not different enough to learn from)
-- If the account has multiple personas, create one variant per persona
+When the user wants to test, deploy variants as separate ads in the same ad group (paused, then enabled together). Each variant must test a **meaningfully different angle** — not word swaps. "Trust & Expertise" vs. "Speed & Convenience" vs. "Price & Value" is a real test; "Call Today" vs. "Call Now" is noise. If the account has multiple personas, create one variant per persona.
-### 5. Deploy
+**Statistical significance thresholds (apply when calling winners):**
-After user approves a variant, push it live:
+- <100 clicks per variant → too early to call. Wait.
+- 100–200 clicks per variant, <20% relative CTR/CVR difference → functionally equivalent; pick on conversion rate or run a bolder test
+- ≥20% relative CTR or CVR delta → real winner
+- Either variant with 2× the other's conversion rate → call it immediately, don't wait
-- **New ad:** `createAd` — create the RSA in the target ad group (created paused)
-- **Update existing:** `updateAdAssets` — replace headlines/descriptions on a live ad
-- **Enable when ready:** `enableAd`
+**Result interpretation matrix:**
-Always confirm before any write operation. Note the `changeId` returned — user can undo within 7 days (if the entity hasn't been modified since) via `undoChange`.
-
-(Call tools under the MCP prefix detected by the shared preamble — do not hardcode `mcp__adsagent__`.)
-
-### 6. A/B test (if running one)
-
-1. **Identify the variable** — messaging angle, CTA style, emotional vs. practical
-2. **Deploy both variants** as separate ads in the same ad group (both paused, enable together)
-3. **Minimum run:** 2 weeks or 100 clicks per variant, whichever comes first
-4. **Success metric:** CTR for awareness campaigns, conversion rate for bottom-funnel
-
-**Statistical significance rules:**
-- Do not call a winner with <100 clicks per variant — the data isn't reliable
-- A "winner" needs at least 20% relative CTR or conversion rate difference to be meaningful
-- If the difference is <20% after 200+ clicks each, the variants are functionally equivalent — pick the one with better conversion rate, or run a bolder test
-- If one variant has 2x+ the conversion rate, call it immediately — don't wait for click minimums
-
-### 7. Check results
-
-After the test period, pull results:
-
-```
-listAds → compare metrics for each variant
-```
+| CTR | Conv rate | Diagnosis | Action |
+|-----|-----------|-----------|--------|
+| A higher | A higher | Clear winner | Pause B. Iterate on A's angle with fresh headlines |
+| A higher | B higher | A pulls clicks, B converts | Keep B; test A's headlines on B's landing page — message-match may need work. Offer `/ads-landing` |
+| Similar | Similar | No meaningful difference | Variants too similar — change the core angle, not the wording |
+| Both low | Both low | Neither works | Problem isn't A vs B — keyword intent, landing page, or offer is broken. Suggest `/ads-audit` |
-| Variant | Impressions | Clicks | CTR | Conversions | Conv Rate | CPA | Winner? |
-|---------|------------|--------|-----|-------------|-----------|-----|---------|
-| A | | | | | | | |
-| B | | | | | | | |
+After a winner is called: pause the loser, then create a new variant to test against the winner. Never stop testing.
-**Interpretation matrix:**
+## Operating principles
-| CTR | Conv Rate | Diagnosis | Action |
-|-----|-----------|-----------|--------|
-| A higher | A higher | Clear winner | Pause B. Iterate on A's angle with fresh headlines |
-| A higher | B higher | A attracts more clicks but B converts better | Keep B as primary. Test A's headlines on B's landing page — the click-through message may need landing page alignment. Offer `/ads-landing` |
-| Similar | Similar | No meaningful difference | Need a bolder test — the variants were too similar. Change the core messaging angle, not just word choice |
-| Both low | Both low | Neither variant works | The problem isn't A vs B — it's the overall approach. Check: keyword intent match, landing page quality, offer strength. May need `/ads-audit` to diagnose |
-
-After deciding a winner: pause the loser with `pauseAd`, keep the winner running. Then create a new variant to test against the winner — continuous improvement, never stop testing.
-
-## Rules
-
-1. **Business context first.** Read `{data_dir}/business-context.json` before doing anything. If it doesn't exist, build it.
-2. **Research before writing.** Always pull current performance data. Don't write copy in a vacuum.
-3. **Character limits are hard.** Count every headline (<=30) and description (<=90). No exceptions. When in doubt, count again.
-4. **Never deploy without confirmation.** Show the exact copy, get a yes, then create/update.
-5. **Note changeIds.** Every write returns one. Tell the user they can undo within 7 days (if the entity hasn't been modified since).
-6. **Ground copy in conversion data.** If conversion data is available, use the language that converts. Customer language > marketing language.
-7. **Seasonal awareness.** Check the business context for peak/slow months. Adjust urgency and messaging accordingly.
-8. **Defer to /ads for account management.** This skill writes copy and deploys ads. For bid/budget/keyword work, use `/ads`.
-9. **Personas over guesses.** If personas exist, every headline should trace back to a persona's language or triggers. If they don't exist, recommend `/ads-audit` to build them.
-10. **Differentiate, don't imitate.** Read the competitors field and write copy that stands apart. Generic copy that could belong to any competitor is a waste of an ad slot.
+1. **Business context is non-negotiable.** Read `{data_dir}/business-context.json` and `{data_dir}/personas/{accountId}.json` first. If they don't exist or are stale, recommend `/ads-audit` before writing anything generic.
+2. **Confirm before deploying.** Show the exact copy, character counts per asset, and pin positions. Get a yes, then push.
+3. **Every write returns a `changeId`.** Tell the user it's undoable within 7 days via `undoChange` (assuming the entity hasn't been modified since).
+4. **Differentiate, don't imitate.** Read the `competitors` field. Generic copy that could belong to any competitor is a wasted ad slot.
+5. **Defer to `/ads` for account management.** This skill writes copy and deploys RSAs; bid / budget / keyword work belongs in `/ads`.
diff --git a/google-ads/ads-landing/SKILL.md b/google-ads/ads-landing/SKILL.md
index 0d560281..c27254a9 100644
--- a/google-ads/ads-landing/SKILL.md
+++ b/google-ads/ads-landing/SKILL.md
@@ -12,45 +12,34 @@ Read and follow `../shared/preamble.md` — it handles MCP detection, token, and
Google Ads campaigns fail on the landing page more often than in the auction. A great RSA that sends traffic to a slow, unfocused, or mismatched page burns budget twice — once on the click, once on the lost conversion. This skill scores landing pages on **5 weighted dimensions** and emits concrete fixes.
-## When to run this
+Only score pages that actually run ad traffic. Don't score random marketing pages. Run this on direct request, on auto-handoff from `/ads-audit` (high-CTR / low-CVR ad groups), when QS diagnosis flags "Landing Page Experience: Below Average", or as a preflight before `/ads-copy` writes new copy for a page nobody's validated.
-| Trigger | Source |
-|---------|--------|
-| User explicitly asks for a landing page audit | Direct invocation |
-| `/ads-audit` Layer 4 finds ad groups with CTR > account avg AND CVR < 50% of account avg | Auto-handoff |
-| Quality Score diagnosis flags "Landing Page Experience: Below Average" on high-spend keywords | `/ads` routes here |
-| `/ads-copy` is about to write copy for a page the user hasn't validated | Preflight check |
+## Reference
-Only score pages that actually run ad traffic. Don't score random marketing pages.
-
-## Reference Documents
-
-- `references/scoring-rubric.md` — The 5-dimension weighted rubric, thresholds, and evidence fields (read this before running any score)
-- `../ads-audit/references/business-context.md` — Uses `{data_dir}/business-context.json` for brand voice and differentiators to check message match
-- `../ads/references/quality-score-framework.md` — Read only if the user's goal is QS improvement specifically
+- `references/scoring-rubric.md` — the 5-dimension weighted rubric, thresholds, and evidence fields. Read before scoring.
+- `../ads/references/quality-score-framework.md` — only when the user's explicit goal is QS improvement.
## Phase 1: Resolve the target pages
Figure out which URLs to score. In priority order:
-1. **User supplied a URL** — score that one page, skip discovery.
-2. **User supplied an ad group or campaign name** — pull `listAds` for that ad group and extract unique final URLs. Normalize (strip tracking params, preserve path + query that affects routing).
-3. **Auto-handoff from `/ads-audit`** — the handoff passes the specific ad groups flagged in Layer 4. Pull their final URLs.
-4. **No arguments** — pull `listAds` for the whole account, rank final URLs by spend (last 30 days), and propose the top 3 to score. Ask the user to confirm.
+1. **User supplied a URL** — score that page, skip discovery.
+2. **User supplied an ad group or campaign name** — `runScript` a GAQL query against `ad_group_ad` filtered to that ad group; extract unique `final_urls`. Normalize (strip tracking params, preserve path + query that affects routing).
+3. **Auto-handoff from `/ads-audit`** — the handoff passes the specific ad groups flagged. Pull their final URLs the same way.
+4. **No arguments** — `runScript` an `ad_group_ad` query across the account ranking final URLs by last-30-day spend, propose the top 3, ask the user to confirm.
-**De-duplicate aggressively.** Many ads point to the same final URL — score each unique URL once, then map back to all the ad groups that use it.
+**De-duplicate aggressively.** Many ads point to the same final URL — score each unique URL once, then map back to every ad group that uses it.
## Phase 2: Gather signal (parallel)
-Run all of these in a single tool-use turn:
+Do all of these in a single tool-use turn:
-1. **WebFetch the landing page** — capture visible headline, subheadline, primary CTA text, form fields, trust signals, body copy tone. Also capture the full HTML so we can spot script bloat and above-the-fold content.
-2. **PageSpeed Insights API call** — use `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={url}&strategy=mobile&category=performance&category=accessibility&category=best-practices&category=seo` via WebFetch. No API key needed for single-URL queries. Extract LCP, CLS, INP, TTI, performance score, and the top 3 opportunities (`lighthouseResult.audits`).
-3. **Pull the referring ad copy** — from the ad group(s) that send traffic here, get headlines and descriptions via `listAds`. This is the message-match baseline.
-4. **Read `{data_dir}/business-context.json`** — for brand voice, differentiators, offers, target audience. If it's missing, point the user to `/ads-audit` first. Don't guess the business.
-5. **Pull conversion data** for the ad group(s) — `listAds` + search term report for the ad groups pointing here. Used to calculate CVR and to ground dollar-impact estimates.
+1. **WebFetch the landing page** — capture visible headline, subheadline, primary CTA text, form fields, trust signals, body copy tone. Capture the full HTML so we can spot script bloat and above-the-fold content.
+2. **PageSpeed Insights API call** — `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={url}&strategy=mobile&category=performance&category=accessibility&category=best-practices&category=seo` via WebFetch. No API key needed for single-URL queries. Extract LCP, CLS, INP, TTI, performance score, and the top 3 opportunities from `lighthouseResult.audits`.
+3. **Pull the referring ad copy and the ad group's conversion metrics** — one `runScript` call with `ads.gaqlParallel` against `ad_group_ad` (for headline/description text — the message-match baseline) and `ad_group` or `keyword_view` (for clicks, conversions, CVR — used to ground the dollar-impact estimate). One call covers both.
+4. **Read `{data_dir}/business-context.json`** — for brand voice, differentiators, offers, target audience. If missing, point the user to `/ads-audit` first. Don't guess the business.
-If any single call fails, continue — note the gap in the report rather than blocking. PageSpeed Insights can rate-limit; if it does, fall back to manual timing annotation ("PSI unavailable — could not score Page Speed") and deflate the final grade's confidence rather than skipping the dimension.
+If any single call fails, continue — note the gap in the report rather than blocking. PageSpeed Insights can rate-limit; if it does, fall back to a manual timing annotation ("PSI unavailable — could not score Page Speed") and deflate the final report's confidence rather than skipping the dimension.
## Phase 3: Score the page
diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.md
index 86bc861c..666260ff 100644
--- a/google-ads/ads/SKILL.md
+++ b/google-ads/ads/SKILL.md
@@ -2,7 +2,6 @@
name: ads
description: Manage Google Ads — performance, keywords, bids, budgets, negatives, campaigns, ads, search terms, QS, location targeting, bulk operations. Use for any mention of Google Ads, CPA, ROAS, ad spend, or campaign settings.
argument-hint: "<campaign name, keyword, or 'show performance'>"
-version: 3.2.0
triggers:
- google ads
- campaigns
@@ -29,117 +28,56 @@ triggers:
- change impact
---
+# Google Ads — Operate, Diagnose, Optimize
+
+This skill is the analytical brain layered on top of the AdsAgent MCP server. The MCP server tells the agent _how_ to call tools (read-only questions go through `runScript` + `ads.gaqlParallel`; mutations go through dedicated write tools). This skill tells the agent _what to think about_ — the benchmarks, scoring rubrics, decision trees, and operational discipline that turn raw GAQL data into informed action.
+
+You are an expert paid-search practitioner. Trust your judgment on tool sequencing — the references below give you the frameworks, you decide how to apply them.
+
## Setup
-Read and follow `../shared/preamble.md` — it handles MCP detection, token, and account selection. If config is already cached, this is instant.
-
-## Interaction Modes
-
-This skill handles two very different request types. Recognizing which one you're in avoids unnecessary work.
-
-**Direct action (fast path):**
-> User: "pause the keyword 'dog grooming' in the Seattle campaign"
-> 1. Confirm: "I'll pause 'dog grooming' in Pet Daycare - Seattle. Go ahead?"
-> 2. On approval: call `pauseKeyword`, log per `references/change-tracking.md`
-> 3. Done. No session checks, no performance analysis.
-
-**Change impact review:**
-> User: "check my changes" / "did my changes work?" / "review my changes"
-> 1. Read `references/session-checks.md` and run the change review checks
-> 2. If no pending changes: tell the user no recent changes are logged
-> 3. If changes exist but review window hasn't passed: show maturation message (see `references/session-checks.md`)
-> 4. If ready for review: pull before/after metrics, compute deltas, show results
-
-**Analysis request:**
-> User: "how are my ads doing?"
-> 1. Read `references/session-checks.md` and run those checks (pending reviews, anomalies)
-> 2. Pull data following the Performance Summary playbook in `references/workflow-playbooks.md`
-> 3. Read `references/analysis-heuristics.md` for thresholds
-> 4. Deliver report using the template in `references/workflow-playbooks.md`
-
-## Rules
-
-1. **Confirm before writing.** Show what you plan to change, the current value, and the new value. Users need to see the impact before approving — a blind "done" erodes trust.
-2. **Start with reads.** When the user asks about ads, begin with `getAccountInfo` and `listCampaigns` to orient yourself.
-3. **Show numbers clearly.** Format cost as dollars, CTR as percentages, include date ranges. Vague metrics are useless.
-4. **Recommend before acting.** When you spot waste, present the finding and wait for approval.
-5. **Guardrails are server-side.** Bid changes >25% and budget changes >50% will be rejected by the API.
-6. **Log every write** per `references/change-tracking.md`.
-7. **moveKeywords defaults to PHRASE match** and does NOT inherit from the source keyword. Always specify matchType explicitly — otherwise exact match keywords silently become phrase match.
-
-## Reference Routing
-
-For simple operations (pause, rename, single bid change), you typically don't need reference files. For analysis, pick the right one:
-
-| Situation | Read |
-|-----------|------|
-| Performance analysis, keyword evaluation, waste calculation | `references/analysis-heuristics.md` (start here — routes to deeper files) |
-| Step-by-step playbooks, report template | `references/workflow-playbooks.md` |
-| QS diagnostics, component-level fixes | `references/quality-score-framework.md` |
-| Bid strategy selection, migration, Smart Bidding | `references/bid-strategy-decision-tree.md` |
-| Industry CPA/CTR/CPC benchmarks, seasonal adjustments | `references/industry-benchmarks.md` |
-| Search term scoring, n-gram analysis, negative strategy | `references/search-term-analysis-guide.md` |
-| Campaign/ad group structure, naming, restructuring | `references/campaign-structure-guide.md` |
-| GAQL query patterns, adaptive fetching by account size | `../shared/gaql-cookbook.md` |
-
-## Available Tools
-
-### Read (safe, no side effects)
-- **getAccountInfo** — Account name, currency, timezone, test status
-- **listCampaigns** — All campaigns with impressions, clicks, cost, conversions
-- **getCampaignPerformance** — Daily metrics over a date range
-- **getKeywords** — Top keywords with quality scores
-- **getSearchTermReport** — Actual search queries triggering ads
-- **runGaqlQuery** — Custom read-only GAQL SELECT query (max 50 rows; see `../shared/gaql-cookbook.md`)
-- **getChanges** — Recent AdsAgent changes with `changeId`s for undo
-- **listConnectedAccounts** — All connected Google Ads accounts
-- **getTrackingTemplate** — Current tracking template at any level
-- **listAdGroups** — Ad groups in a campaign with metrics
-- **listAds** — Ads in a campaign/ad group with copy, URLs, status, metrics
-- **getImpressionShare** — Search/top/abs-top IS and budget/rank-lost IS (max 90 days)
-- **getConversionActions** — Conversion actions and settings
-- **getAccountSettings** — Auto-tagging, tracking template, conversion tracking IDs
-- **getCampaignSettings** — Bidding, network, locations, schedule
-- **getNegativeKeywords** — Negative keywords for a campaign (check before adding to avoid duplicates)
-- **getRecommendations** — Google optimization recommendations
-- **getKeywordIdeas** — Keyword research suggestions based on seed keywords or URL
-- **getPmaxAssetGroups** — Performance Max asset groups with metrics
-- **getPmaxAssets** — Assets within a PMax asset group
-- **searchGeoTargets** — Find geo target constant IDs for location targeting
-
-### Write (mutates the account — confirm with user first)
-All write tools return a `changeId` for undo within 7 days.
-
-- **pauseKeyword / enableKeyword** — Stop or re-enable a keyword
-- **addKeyword** — Add a new keyword to an ad group
-- **updateBid** — Change CPC bid (manual/enhanced CPC only, max 25% change)
-- **addNegativeKeyword** — Block irrelevant terms at campaign level (BROAD, PHRASE, or EXACT; default: PHRASE)
-- **removeNegativeKeyword** — Remove a negative keyword
-- **updateCampaignBudget** — Change daily budget (max 50% change, min $1/day)
-- **updateCampaignBidding** — Change bid strategy (e.g., switch to Target CPA, Maximize Conversions). This is how you implement recommendations from `references/bid-strategy-decision-tree.md`
-- **updateCampaignGoals** — Change campaign conversion goals
-- **createCampaign** — Create a full paused search campaign. Headlines (3-15, max 30 chars), descriptions (2-4, max 90 chars), finalUrl required. Default: MAXIMIZE_CONVERSIONS
-- **pauseCampaign / enableCampaign** — Pause or re-enable a campaign
-- **removeCampaign** — PERMANENTLY delete (cannot undo — prefer pauseCampaign)
-- **setTrackingTemplate** — Set/clear tracking template
-- **createAdGroup** — Create a new ad group
-- **createAd** — Create RSA. Headlines (3-15, max 30 chars), descriptions (2-4, max 90 chars), finalUrl required
-- **pauseAd / enableAd** — Pause or re-enable an ad
-- **removeAd** — Permanently delete an ad
-- **updateAdFinalUrl** — Change an ad's landing page URL
-- **updateAdAssets** — Replace RSA headlines/descriptions (complete replacement — provide every asset)
-- **bulkUpdateBids** — Update up to 50 keyword bids (each capped at 25% change)
-- **bulkPauseKeywords** — Pause up to 100 keywords (partial success possible — report what succeeded and what failed)
-- **bulkAddKeywords** — Add up to 100 keywords to an ad group (partial success possible)
-- **moveKeywords** — Move keywords between ad groups in same campaign. Max 100. See Rule 7 about match type.
-- **renameCampaign / renameAdGroup** — Rename a campaign or ad group
-- **updateCampaignSettings** — Update network and/or location targeting (geo target constant IDs, e.g. '2840' for US). Supports negative locations.
-- **pausePmaxAssetGroup / enablePmaxAssetGroup** — Pause or enable a Performance Max asset group
-- **undoChange** — Reverse a previous write by `changeId`
-
-## Account Baseline
-
-Maintain `{data_dir}/account-baseline.json` for anomaly detection. Update at the END of any session where you pulled campaign data — no extra API calls needed.
+Read and follow `../shared/preamble.md` — handles MCP detection, API key, and account selection. Once cached, this is instant.
+
+## Operating principles
+
+1. **Confirm before writing.** Show the current value, the proposed new value, and the expected impact in dollars when you can compute it. Blind "done." erodes trust.
+2. **Reads correlate, writes commit.** For any analysis question, prefer one `runScript` call that fans out the GAQL queries you need (the server's `adsagent://playbooks/audit-account` and `adsagent://playbooks/explain-regression` resources are good starting points). Mutations always go through dedicated write tools — never wrap a write in `runScript`.
+3. **Show numbers in dollars and percentages.** Format cost as USD, CTR as percent, always cite the date range. Vague metrics are not findings.
+4. **Recommend, then act.** When you spot waste or opportunity, present the finding with evidence and wait for approval before mutating.
+5. **Server-side guardrails are not optional.** The API rejects bid changes >25% and budget changes >50%. Don't try to bypass them; split the change across days if the user wants a bigger move.
+6. **Log every write** per `references/change-tracking.md`. The `changeId` returned by every write tool is the user's undo handle for 7 days.
+7. **`moveKeywords` defaults to PHRASE match** and does not inherit from the source. Always pass `matchType` explicitly — exact-match keywords silently downgrade otherwise.
+
+## Reference framework — when to read what
+
+Pick the lens that matches the user's question. Don't pre-load all of these; load on demand.
+
+| The user wants to… | Read |
+|---|---|
+| Understand or rank performance, find waste, evaluate keywords | `references/analysis-heuristics.md` (entry point — links onward) |
+| Diagnose Quality Score at the component level | `references/quality-score-framework.md` |
+| Pick or migrate a bid strategy (manual → tCPA, etc.) | `references/bid-strategy-decision-tree.md` |
+| Compare metrics to industry CPA/CTR/CPC norms or apply seasonal lens | `references/industry-benchmarks.md` |
+| Score search terms, plan negatives, do n-gram analysis | `references/search-term-analysis-guide.md` |
+| Restructure campaigns, fix ad-group bloat, name things sensibly | `references/campaign-structure-guide.md` |
+| Review previously-made changes for impact | `references/session-checks.md` + `references/change-tracking.md` |
+
+For business context (services, brand voice, personas, unit economics), read `{data_dir}/business-context.json` and `{data_dir}/personas/{accountId}.json`. If they're missing or stale (>90 days), suggest `/ads-audit`.
+
+## Tool surface
+
+The MCP server's `tools/list` is the source of truth for what's available — do not maintain a parallel list here. The server's instructions route the agent to:
+
+- **Reads / analytics / dashboards** → `runScript` with `ads.gaql()` and `ads.gaqlParallel()`. One call, multiple GAQL queries in parallel, correlate in-script. Cast a wide net on the first call.
+- **Schema discovery** → `getResourceMetadata`, `listQueryableResources` (call before writing GAQL against an unfamiliar resource).
+- **Specialized non-GAQL reads** → `searchGeoTargets`, `getKeywordIdeas`, `getRecommendations`, `getChanges`, `reviewChangeImpact`.
+- **Mutations** → dedicated write tools (`pauseKeyword`, `updateBid`, `createCampaign`, `bulkAddKeywords`, etc.). Each returns a `changeId` for `undoChange` within 7 days.
+
+If you're unsure whether a write tool exists for what the user asked, check `tools/list`. New capabilities (bidding strategies, callout assets, negative keyword lists, conversion uploads, guardrails) ship there before they ship here.
+
+## Account baseline
+
+Maintain `{data_dir}/account-baseline.json` for anomaly detection across sessions. Update at the **end** of any session where you pulled rolling-window campaign metrics — the data is already in your context, no extra API call.
```json
{
@@ -156,14 +94,16 @@ Maintain `{data_dir}/account-baseline.json` for anomaly detection. Update at the
}
```
-Update formula: `rolling30d = (0.7 x previous_rolling30d) + (0.3 x recent_7d x (30/7))`. The `(30/7)` factor projects 7-day values to 30-day equivalents. New campaigns: initialize rolling30d from recent7d directly. Cap at 50 campaigns (spend > $0 in last 30 days only).
+Update formula: `rolling30d = (0.7 × previous_rolling30d) + (0.3 × recent7d × (30/7))`. The `(30/7)` factor projects the 7-day numbers to a 30-day equivalent. New campaigns: initialize `rolling30d` from `recent7d` directly. Cap at 50 campaigns (spend > $0 in last 30 days only) so the file stays small.
+
+When the baseline is older than 24h, `references/session-checks.md` describes the anomaly comparison to run.
-## Conditional Handoffs
+## Conditional handoffs
-After analysis, proactively offer relevant skills:
+After analysis, proactively offer the right next skill:
-- **Ad copy problems** (CTR issues in 2+ ad groups): suggest `/ads-copy`
-- **Missing business context** (no `business-context.json` or >90 days old): suggest `/ads-audit` first
-- **Keyword gaps** (3+ converting search terms not yet keywords): offer to add them
-- **Landing page misalignment** (CTR above industry benchmark but conversion rate below on multiple ad groups): suggest `/ads-landing`
-- **Competitive intelligence** (impression share declining or new competitor patterns): suggest `/ads-compete`
+- **Ad copy issues** (CTR below benchmark in 2+ ad groups) → `/ads-copy`
+- **No business context, or context >90 days old** → `/ads-audit` first
+- **Converting search terms not yet keywords** (3+) → offer to add them with `bulkAddKeywords`
+- **High CTR, low CVR on multiple ad groups** → `/ads-landing` (the page is the bottleneck, not the ad)
+- **Impression share declining or new competitor patterns** → `/ads-compete` if available, otherwise note auction-insights are now visible via GAQL `auction_insight_*` resources
diff --git a/google-ads/ads/references/session-checks.md b/google-ads/ads/references/session-checks.md
index 5d428a45..fe497f61 100644
--- a/google-ads/ads/references/session-checks.md
+++ b/google-ads/ads/references/session-checks.md
@@ -17,7 +17,7 @@ Do NOT pull metrics or attempt to assess impact early — small sample sizes lea
**If unreviewed changes exist AND `reviewAfter` has passed:**
-1. Pull current metrics for affected campaigns using `listCampaigns` and `getCampaignPerformance` (7-day window). Use the `beforeSnapshot` from the change log as baseline — only fall back to `getCampaignPerformance` for the pre-change period if `beforeSnapshot.metrics` is null. Do this in parallel with the user's actual request. Save the `listCampaigns` result for reuse in anomaly detection.
+1. Pull current metrics for the affected campaigns over the last 7 days via a single `runScript` GAQL query against `campaign` filtered to those IDs. Use the `beforeSnapshot` from the change log as the baseline — only query the pre-change period directly if `beforeSnapshot.metrics` is null. Do this in parallel with the user's actual request, and reuse the resulting rows for the anomaly check below.
2. Compute deltas: percentage change for spend, conversions, CPA, CTR.
diff --git a/google-ads/ads/references/workflow-playbooks.md b/google-ads/ads/references/workflow-playbooks.md
deleted file mode 100644
index dfa32488..00000000
--- a/google-ads/ads/references/workflow-playbooks.md
+++ /dev/null
@@ -1,254 +0,0 @@
-# Workflow Playbooks
-
-Step-by-step guides for common Google Ads management tasks. Each playbook specifies exactly which tools to call, in what order, and how to analyze the results.
-
-## Table of Contents
-- [Performance Summary](#performance-summary)
-- [Waste Audit](#waste-audit)
-- [Bid Optimization](#bid-optimization)
-- [Growth Optimization](#growth-optimization)
-- [QS Diagnostic](#qs-diagnostic)
-- [Account Restructure](#account-restructure)
-
----
-
-## Performance Summary
-
-Triggered by: "how are my ads doing?", "show performance", "ads report"
-
-**Step 1: Pull data (parallel — 4 calls total)**
-- `getAccountInfo` — business name, currency
-- `listCampaigns` — all campaigns with spend, clicks, conversions
-- `runGaqlQuery` — impression share for all campaigns
-- `runGaqlQuery` — daily performance (use LAST_7_DAYS for 2+ campaigns to stay under 50-row limit)
-
-**Step 2: Analyze**
-- Calculate account-level CPA, CTR, conversion rate
-- Compare each campaign's CPA to account average — flag any >150% of avg
-- Check impression share using the diagnostic matrix in `analysis-heuristics.md`
-- Identify the best performer (lowest CPA, highest conversion volume) and worst performer
-- Compare metrics to industry benchmarks from `industry-benchmarks.md`
-
-**Step 3: Deliver using the Report Template below**
-
----
-
-## Waste Audit
-
-Triggered by: "find wasted spend", "where am I wasting money", "waste audit"
-
-**Step 1: Pull data (2 phases)**
-
-*Phase 1 (parallel — 4 calls):*
-- `listCampaigns` → all campaigns + identify top 3 by spend
-- `runGaqlQuery` → zero-conversion high-spend keywords
-- `runGaqlQuery` → search terms ordered by spend
-- `runGaqlQuery` → negative keywords
-
-*Phase 2 (parallel, depends on Phase 1):*
-- `getCampaignSettings` for top 3 campaigns → check if Display Network is enabled
-
-If the zero-conversion query returns 50 rows (hit the limit), there's significant waste — supplement with `getKeywords` for the top 2-3 campaigns by spend.
-
-**Step 2: Analyze**
-- Apply the Wasted Spend Calculation from `analysis-heuristics.md`
-- For each non-converting keyword: first classify (Tier 1/2/3), then check QS, spend, days active, and statistical significance
-- For each irrelevant search term: score relevance using `search-term-analysis-guide.md`
-- Check for Display Network bleed and negative keyword gaps
-
-**Step 3: Present waste breakdown with specific actions**
-For each waste source, show the keyword/term, its spend, clicks, and why it's wasteful, the recommended action, and expected savings.
-
-**Step 4: Offer to execute**
-"I found $X in wasted spend. Want me to pause the non-converting keywords and add the negative keywords? I'll show you each change before making it."
-
----
-
-## Bid Optimization
-
-Triggered by: "optimize bids", "adjust bids", "bid strategy"
-
-**Step 1: Pull data (2 phases)**
-
-*Phase 1 (parallel):*
-- `listCampaigns` → size the account
-- GAQL keywords with QS query → all keywords with CPA, CPC, conversions, QS
-- GAQL impression share query → where bid increases would capture more traffic
-
-*Phase 2 (depends on Phase 1):*
-- `getCampaignSettings` for target campaigns → confirm bid strategy (manual/enhanced CPC only)
-
-**Step 2: Analyze using keyword performance heuristics from `analysis-heuristics.md`**
-- First, classify all keywords into Tier 1/2/3
-- Segment by performance:
- - **Scale** (CPA < 50% avg): increase bid 15-25%
- - **Maintain** (CPA 50-100% avg): no change
- - **Reduce** (CPA 100-150% avg): decrease bid 10-15%, add negatives
- - **Pause** (CPA > 200% avg or spend >2x CPA with 0 conversions): Tier 2/3 only. For Tier 1, run Core Keyword Diagnostic
-- Cross-reference with impression share: only increase bids where rank-lost IS > 20%
-- Check bid strategy compatibility: if using Target CPA or Maximize Conversions, recommend bid strategy adjustment instead (see `bid-strategy-decision-tree.md`)
-
-**Step 3: Present bid change plan as a table**
-
-| Keyword | Current Bid | New Bid | CPA | Conv | Rationale |
-|---------|-------------|---------|-----|------|-----------|
-| ... | $2.50 | $3.00 | $18 | 12 | CPA 40% below avg, rank-lost IS 35% |
-
-**Step 4: Execute with `bulkUpdateBids` after user approval**
-
----
-
-## Growth Optimization
-
-Triggered by: "scale winning keywords", "grow conversions", "what's working"
-
-**Step 1: Pull data (2 phases)**
-
-*Phase 1 (parallel):*
-- `listCampaigns` → identify top campaigns
-- GAQL keywords with QS → find keywords with conversions > 2, CPA < avg, QS > 6
-- GAQL converting search terms → search terms with conversions
-- GAQL impression share → how much more traffic is available
-
-*Phase 2 (depends on Phase 1):*
-- `getCampaignSettings` for target campaigns → check budget headroom
-
-**Step 2: Identify scaling opportunities**
-- **Bid increases**: Keywords with CPA < 50% avg AND rank-lost IS > 20%
-- **Match type expansion**: Keywords converting on exact match → test phrase match
-- **Search term mining**: Converting search terms not yet keywords → add as phrase match
-- **Budget reallocation**: Move budget from worst to best-performing campaign
-
-**Step 3: Present scaling plan with projected impact**
-For each action, estimate the impact — additional impression share, estimated conversions, projected CPA.
-
----
-
-## QS Diagnostic
-
-Triggered by: "fix quality scores", "low quality score", "QS problems"
-
-**Step 1: Pull data (parallel)**
-- `listCampaigns` → size the account
-- GAQL keywords with QS → all keywords with QS
-- GAQL ad groups → ad group structure
-- GAQL ad copy → RSA headlines/descriptions per ad group
-- GAQL search terms → search term relevance
-
-**Step 2: Diagnose using `quality-score-framework.md`**
-- Group keywords by QS: count in each 1-4, 5-6, 7-8, 9-10 bucket
-- For QS 1-4 keywords, check which subcomponent is "Below Average":
- - Expected CTR below avg → ad copy issue. Need `/ads-copy`
- - Ad Relevance below avg → keyword in wrong ad group. Need restructure
- - Landing Page below avg → page doesn't match intent
-- Check ad group sizes: >25 keywords likely has QS problems from mixed intent
-
-**Step 3: Present action plan prioritized by spend**
-Fix high-spend, low-QS keywords first. A QS improvement from 4 to 6 can reduce CPC by ~15-25%.
-
----
-
-## Account Restructure
-
-Triggered by: "restructure campaigns", "reorganize account", "campaign structure"
-
-**Step 1: Pull data (2 phases)**
-
-*Phase 1 (parallel):*
-- `listCampaigns` → all campaigns
-- GAQL ad groups → ad group structure
-- GAQL keywords with QS → keyword themes per ad group
-- GAQL negative keywords → current coverage
-
-*Phase 2 (depends on Phase 1):*
-- `getCampaignSettings` for top campaigns → targeting and bid strategies
-
-**Step 2: Diagnose structural issues using `campaign-structure-guide.md`**
-Common problems:
-- **Mega ad groups** (>30 keywords): mixed intent kills QS. Split by keyword theme
-- **Single campaign, multiple services**: can't control budget per service. Split into service-based campaigns
-- **No geographic structure** for multi-location businesses: create location-specific campaigns
-- **Brand and non-brand mixed**: brand keywords inflate metrics. Separate them
-
-**Step 3: Present restructure plan**
-Show proposed structure as a tree:
-```
-Account
-├── [Brand] Brand Campaign ($X/day)
-│ └── Brand Terms (exact match)
-├── [Service A] [Location] ($X/day)
-│ ├── AG: Core Terms (5-10 keywords)
-│ └── AG: Long-tail (5-10 keywords)
-├── [Service B] [Location] ($X/day)
-│ └── ...
-```
-
-**Step 4: Execute incrementally**
-Use `createCampaign`, `createAdGroup`, `moveKeywords`, `bulkAddKeywords`. Always create new structure FIRST (paused), then move keywords, then enable new and pause old. No gap in ad serving.
-
----
-
-## Report Template
-
-Use this structure for every performance summary:
-
-```
-# Google Ads Performance: [Account Name]
-**Account:** [ID] | **Period:** [date range] | **Date:** [today]
-
-## Key Metrics
-| Metric | Value | vs Prior Period | vs Industry Avg |
-|--------|-------|-----------------|-----------------|
-| Spend | $X,XXX | +X% / -X% | — |
-| Clicks | X,XXX | +X% / -X% | — |
-| Conversions | XX | +X% / -X% | — |
-| CPA | $XX.XX | +X% / -X% | $XX (industry) |
-| CTR | X.XX% | +X.X pp | X.XX% (industry) |
-| Conv Rate | X.XX% | +X.X pp | X.XX% (industry) |
-| Search Impression Share | XX% | +X pp / -X pp | — |
-
-## Campaign Breakdown
-| Campaign | Spend | Conv | CPA | CTR | Imp Share | Status |
-|----------|-------|------|-----|-----|-----------|--------|
-| [name] | $X,XXX | XX | $XX | X.X% | XX% | [Healthy/Needs Work/Critical] |
-
-## Wasted Spend (30 days)
-**Total:** $X,XXX (XX% of spend) — Annualized: ~$XX,XXX
-- Non-converting keywords: $XXX across N keywords
-- Irrelevant search terms: ~$XXX across N terms
-- Display bleed: $XXX (if applicable)
-
-## Top Issues (ranked by dollar impact)
-1. **[Specific issue]** — $XXX impact — [Root cause]
-2. **[Specific issue]** — $XXX impact — [Root cause]
-3. **[Specific issue]** — $XXX impact — [Root cause]
-
-## Recommended Actions
-| # | Action | Expected Impact | Effort | Skill |
-|---|--------|-----------------|--------|-------|
-| 1 | [Specific action] | Save $XXX/month or gain X conversions | Low/Med/High | /ads |
-| 2 | [Specific action] | ... | ... | ... |
-| 3 | [Specific action] | ... | ... | ... |
-
-## What's Working (keep doing this)
-- [Specific positive finding with numbers]
-- [Specific positive finding with numbers]
-```
-
-**Rules for the report:**
-- Every issue must have a dollar amount or conversion count attached
-- Every action must reference a specific campaign, keyword, or ad group by name
-- "vs Industry Avg" column uses benchmarks from `industry-benchmarks.md` — leave blank if industry is unknown
-- "vs Prior Period" compares current 30 days to previous 30 days. Use `getCampaignPerformance` with a 60-day range and split
-
-### Freshness Notes for High-Volatility Recommendations
-
-When making recommendations in these areas, prefix with a freshness disclaimer sourced from `../../shared/policy-registry.json`:
-- Bid strategy recommendations (`bid-strategy-behavior`)
-- Match type behavior advice (`match-type-behavior`)
-- Experiment/testing guidance (`experiment-testing`)
-- PMax configuration advice (`pmax-configuration`)
-
-Format: _"Based on Google Ads behavior as of [last_verified date from registry]. Verify current behavior if this recommendation is critical to your strategy."_
-
-Only add this for the high-volatility areas listed above.
diff --git a/google-ads/shared/gaql-cookbook.md b/google-ads/shared/gaql-cookbook.md
deleted file mode 100644
index a1375367..00000000
--- a/google-ads/shared/gaql-cookbook.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# GAQL Cookbook — Adaptive Data Fetching
-
-GAQL (Google Ads Query Language) lets you pull data across ALL campaigns in a single `runGaqlQuery` call. This cookbook provides an **adaptive algorithm** that adjusts strategy based on account size — from 2-campaign local businesses to 50-campaign enterprise accounts.
-
-## The core challenge
-
-`runGaqlQuery` returns max **50 rows** per call. This creates a tension:
-- **Small accounts** (2-5 campaigns, <50 keywords): Everything fits in 50 rows. GAQL is perfect.
-- **Medium accounts** (5-15 campaigns, 50-200 keywords): Top 50 by spend covers ~80% of value. Supplement for the rest.
-- **Large accounts** (15+ campaigns, 200+ keywords): 50 rows is only the tip. Need a smarter approach.
-
-## Adaptive data fetching algorithm
-
-**The strategy: Use `listCampaigns` as a sizing probe, then choose the right fetching approach.**
-
-### Step 1: Size the account
-
-Always start with `listCampaigns`. This returns all campaigns (default limit: 100) with lifetime metrics and requires no campaign IDs — it's the simplest way to understand what you're working with.
-
-From the result, count **enabled campaigns with spend > $0 in the data**. This is your `active_campaign_count`.
-
-### Step 2: Choose strategy based on account size
-
-```
-IF active_campaign_count <= 3:
- → STRATEGY A: "Small account — GAQL-only"
-
-ELSE IF active_campaign_count <= 10:
- → STRATEGY B: "Medium account — GAQL + targeted supplements"
-
-ELSE:
- → STRATEGY C: "Large account — tiered approach"
-```
-
-### Strategy A: Small account (1-3 campaigns)
-
-Most queries fit in 50 rows. Use GAQL for everything in parallel:
-
-1. Run all 7 standard GAQL queries (see Query Patterns below) in parallel
-2. **Exception: Daily campaign performance** returns `campaigns × days` rows. For 2-3 campaigns with LAST_30_DAYS, that's 60-90 rows (over the 50-row limit). Use `LAST_7_DAYS` for 2+ campaigns, or `LAST_30_DAYS` only for single-campaign accounts.
-3. Done. No supplements needed.
-
-**Total API calls: ~8** (1 listCampaigns + 7 GAQL queries)
-
-### Strategy B: Medium account (4-10 campaigns)
-
-GAQL gets the top entities. Supplement only where the 50-row limit matters (keywords and search terms have the most rows).
-
-1. Run all 7 standard GAQL queries in parallel
-2. Check if keyword or search term queries returned exactly 50 rows (hit the limit)
-3. If yes: identify the top 2-3 campaigns by spend from `listCampaigns`, then run `getKeywords` and `getSearchTermReport` for ONLY those campaigns to get deeper coverage
-
-**Total API calls: ~8-14** (8 base + up to 6 supplements)
-
-### Strategy C: Large account (10+ campaigns)
-
-50 rows won't cover the breadth. Use a **tiered approach**:
-
-**Tier 1 — Account-wide overview (GAQL, parallel):**
-- Impression share query (campaign-level, fits easily in 50 rows)
-- Ad groups query (top 50 by spend — may miss tail ad groups in large accounts)
-- Negative keywords query (no metrics, still capped at 50 rows — supplement with `getNegativeKeywords(campaignId, limit: 500)` per campaign for accounts with extensive negative lists)
-- Daily campaign performance (campaign-level, rows = campaigns × days — may need date range narrowed to LAST_7_DAYS)
-
-**Tier 2 — Top campaigns deep dive (helpers, parallel):**
-- From `listCampaigns`, rank campaigns by spend. Select the top N campaigns that account for 80% of total spend (usually 3-5 campaigns even in large accounts — spend follows Pareto).
-- For each of these top campaigns, run in parallel: `getKeywords(limit: 100)`, `getSearchTermReport(limit: 100)`, `listAds`
-- This gives you 100 keywords and 100 search terms per top campaign — much more than GAQL's 50 total.
-
-**Tier 3 — Tail campaigns (GAQL, only if needed):**
-- If the analysis requires data from smaller campaigns, use targeted GAQL with a campaign filter:
- ```
- WHERE campaign.id IN (123, 456, 789)
- ```
-
-**Total API calls: ~10-20** (4 GAQL + 3-5 campaigns × 3 helpers + optional tier 3)
-
-This is more calls than Strategy A/B, but FAR fewer than the naive approach of calling every helper for every campaign (which would be 7 × 10+ = 70+ calls).
-
-### Decision flowchart
-
-```
-listCampaigns
- │
- ├─ 1-3 active campaigns ──→ 7 GAQL queries (done)
- │
- ├─ 4-10 active campaigns ─→ 7 GAQL queries
- │ │
- │ └─ any hit 50-row limit?
- │ ├─ no ──→ done
- │ └─ yes ─→ supplement top 2-3 campaigns
- │
- └─ 10+ active campaigns ──→ 4 GAQL (overview) + helpers for top 80%-spend campaigns
-```
-
-## Important notes
-
-- Cost is in **micros** (millionths). Divide by 1,000,000: `cost_micros / 1000000 = dollars`.
-- Date ranges: `DURING LAST_30_DAYS`, `DURING LAST_7_DAYS`, `DURING THIS_MONTH`, or `BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'`.
-- Always filter `campaign.status = 'ENABLED'` unless you need paused/removed data.
-- `ORDER BY metrics.cost_micros DESC` ensures the 50-row limit captures highest-impact entities.
-- If `runGaqlQuery` errors or is unavailable, fall back entirely to per-campaign helper tools.
-
-## Standard GAQL query patterns
-
-### Keywords with Quality Score
-
-```
-SELECT campaign.id, campaign.name,
- ad_group.id, ad_group.name,
- ad_group_criterion.keyword.text,
- ad_group_criterion.keyword.match_type,
- ad_group_criterion.quality_info.quality_score,
- ad_group_criterion.status,
- metrics.impressions, metrics.clicks,
- metrics.cost_micros, metrics.conversions
-FROM keyword_view
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
-ORDER BY metrics.cost_micros DESC
-LIMIT 50
-```
-
-### Search terms
-
-```
-SELECT campaign.id, campaign.name,
- search_term_view.search_term,
- search_term_view.status,
- metrics.impressions, metrics.clicks,
- metrics.cost_micros, metrics.conversions
-FROM search_term_view
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
-ORDER BY metrics.cost_micros DESC
-LIMIT 50
-```
-
-### Impression share
-
-```
-SELECT campaign.id, campaign.name,
- metrics.search_impression_share,
- metrics.search_budget_lost_impression_share,
- metrics.search_rank_lost_impression_share,
- metrics.search_absolute_top_impression_share,
- metrics.impressions, metrics.clicks,
- metrics.cost_micros
-FROM campaign
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
-ORDER BY metrics.cost_micros DESC
-```
-
-### Ad copy (RSA headlines + descriptions)
-
-```
-SELECT campaign.id, campaign.name,
- ad_group.id, ad_group.name,
- ad_group_ad.ad.responsive_search_ad.headlines,
- ad_group_ad.ad.responsive_search_ad.descriptions,
- ad_group_ad.ad.final_urls,
- ad_group_ad.status, ad_group_ad.ad.type,
- metrics.impressions, metrics.clicks,
- metrics.cost_micros, metrics.conversions
-FROM ad_group_ad
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
- AND ad_group_ad.status != 'REMOVED'
-ORDER BY metrics.cost_micros DESC
-LIMIT 50
-```
-
-### Ad groups
-
-```
-SELECT campaign.id, campaign.name,
- ad_group.id, ad_group.name,
- ad_group.status,
- metrics.impressions, metrics.clicks,
- metrics.cost_micros, metrics.conversions
-FROM ad_group
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
-ORDER BY metrics.cost_micros DESC
-LIMIT 50
-```
-
-### Negative keywords
-
-Note: This query has no metrics to ORDER BY, and accounts with 50+ campaign-level negatives will be silently truncated. For full negative keyword coverage, supplement with `getNegativeKeywords` per campaign (supports up to 500 rows per campaign, much higher than GAQL's 50-row cap).
-
-```
-SELECT campaign.id, campaign.name,
- campaign_criterion.keyword.text,
- campaign_criterion.keyword.match_type
-FROM campaign_criterion
-WHERE campaign_criterion.type = 'KEYWORD'
- AND campaign_criterion.negative = TRUE
- AND campaign.status = 'ENABLED'
-ORDER BY campaign.name
-```
-
-### Daily campaign performance
-
-```
-SELECT campaign.id, campaign.name,
- segments.date,
- metrics.impressions, metrics.clicks,
- metrics.cost_micros, metrics.conversions,
- metrics.conversions_value
-FROM campaign
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
-ORDER BY segments.date DESC
-```
-
-## Specialized queries
-
-### Zero-conversion keywords by spend (waste detection)
-
-Use this query to surface waste candidates. The `/ads-audit` skill's waste formula uses a stricter threshold: `spend > 2x account avg CPA` (not clicks > 10). Calculate account avg CPA from `listCampaigns` data first, then filter these results accordingly.
-
-```
-SELECT campaign.name, ad_group.name,
- ad_group_criterion.keyword.text,
- ad_group_criterion.quality_info.quality_score,
- metrics.clicks, metrics.cost_micros
-FROM keyword_view
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
- AND metrics.conversions = 0
-ORDER BY metrics.cost_micros DESC
-LIMIT 50
-```
-
-### Converting search terms (keyword mining)
-
-```
-SELECT campaign.name, search_term_view.search_term,
- metrics.conversions, metrics.cost_micros, metrics.clicks
-FROM search_term_view
-WHERE segments.date DURING LAST_30_DAYS
- AND campaign.status = 'ENABLED'
- AND metrics.conversions > 0
-ORDER BY metrics.conversions DESC
-LIMIT 50
-```
-
-### Filter to specific campaigns
-
-When you need data from a subset of campaigns (e.g., tier 3 in Strategy C):
-
-```
-WHERE campaign.id IN (123456, 789012, 345678)
- AND segments.date DURING LAST_30_DAYS
-```
diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.md
index 1edb2dbf..f14b9c76 100644
--- a/google-ads/shared/preamble.md
+++ b/google-ads/shared/preamble.md
@@ -123,8 +123,14 @@ Use whichever MCP server prefix was detected in Step 3:
Always call tools under the exact prefix detected in Step 3 — do not hardcode `mcp__adsagent__`. Pass `accountId` from the resolved config (Step 2) to every tool call (except `listConnectedAccounts`).
-### Prefer GAQL for multi-campaign reads
+### Reads vs. writes
-When a workflow needs data from 2+ campaigns, use `runGaqlQuery` with bulk queries instead of per-campaign helper calls. See `../shared/gaql-cookbook.md` for ready-to-use query patterns. This typically reduces API calls from `N × data_types` to just the number of data types (e.g., 7 queries instead of 30+). Fall back to per-campaign helpers if GAQL errors or you need >50 rows for a single campaign.
+The MCP server's own instructions are the canonical guide and are surfaced to the agent automatically:
+
+- **Read-only questions** (analytics, audits, dashboards, diagnostics) go through `runScript`, which exposes `ads.gaql(query)` and `ads.gaqlParallel([queries])`. Fan out up to 20 GAQL queries in one call and correlate results in-script — that's one tool call, not 20.
+- **Mutations** go through dedicated write tools (`pauseKeyword`, `updateBid`, `createCampaign`, etc.). Never wrap a mutation in `runScript`.
+- **Schema discovery** (`getResourceMetadata`, `listQueryableResources`) is the right call before writing GAQL against an unfamiliar resource.
+
+The server also publishes ready-to-use playbooks as MCP resources — `adsagent://playbooks/audit-account` and `adsagent://playbooks/explain-regression`. Fetch them when the user asks the matching question rather than rediscovering the query shape.
Config is loaded. Hand control back to the invoking skill.