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.jsonindex 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.jsonindex 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.mdindex 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### Changeddiff --git a/VERSION b/VERSIONindex 34a83616..54d1a4f2 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.12.1+0.13.0diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.mdindex 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.mdindex 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.mdindex 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 URLFind 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 websitediff --git a/google-ads/ads-audit/references/persona-discovery.md b/google-ads/ads-audit/references/persona-discovery.mdindex 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 Templatediff --git a/google-ads/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.mdindex 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.mdindex 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, andGoogle 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 pagesFigure 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 pagediff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.mdindex 86bc861c..666260ff 100644--- a/google-ads/ads/SKILL.md+++ b/google-ads/ads/SKILL.md@@ -2,7 +2,6 @@name: adsdescription: 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.0triggers:- 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_*` resourcesdiff --git a/google-ads/ads/references/session-checks.md b/google-ads/ads/references/session-checks.mdindex 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mdindex 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.