---
name: analyze-and-optimize-keyword-performance
description: >-
  Runs the recurring keyword triage for a Search campaign: pulls per-keyword efficiency and visibility data,
  sorts every keyword with enough clicks into four action groups (scale the proven winners, repair the expensive
  converters, grow the constrained performers, diagnose-or-pause the non-converters), then executes bid, budget,
  pause, and promotion actions with approval. Reach for it on the monthly keyword review, after CPA or ROAS has
  drifted 30%+ off target for two straight weeks, or when evaluating a restructure. It is keyword-level work, for
  the full multi-lever campaign routine use run-search-campaign-optimization-cycle instead; for mining queries it
  hands off to analyze-search-term-reports; for aggregated word-pattern negation use run-n-gram-analysis; and when
  the diagnosis points at Quality Score components, route to improve-quality-score rather than fixing copy here.
---
# Keyword Triage and Action Cycle

## Purpose
Every keyword that has accumulated real click volume deserves exactly one next action: push it harder, fix its
economics, buy it more visibility, or stop paying for it. This skill turns the keyword report into that decision, mechanically where the data allows, and with explicit routing to deeper skills where the fix lives elsewhere
(Quality Score, landing pages, query hygiene).

## When to run
- Scheduled keyword review: monthly for campaigns under ~6 months old, monthly or every other month once mature.
- Campaign CPA or ROAS has been 30%+ away from target for two consecutive weeks.
- A restructure or match-type expansion just bedded in and needs a post-change evaluation.
- Spend is concentrating in keywords nobody has looked at individually in a while.

## When NOT to run
- You want the whole campaign routine (terms, ads, bids, extensions, competition) → `run-search-campaign-optimization-cycle`.
- You are hunting irrelevant queries or promotion candidates in raw search terms → `analyze-search-term-reports`.
- You suspect systematic waste from recurring words across many terms → `run-n-gram-analysis`.
- The problem is clearly one keyword's Quality Score components → `improve-quality-score` directly.
- The campaign has under 30 days of keyword data, there is nothing statistically safe to act on yet.

## Prerequisites
- At least 30 days of keyword history (60–90 days preferred for mature campaigns).
- A defined campaign-level target: tCPA or tROAS from the bidding strategy, or a stated business target.
- Knowledge of whether the campaign runs Smart Bidding or Manual CPC (changes which actions are legal).

## Procedure
1. **Pull the keyword dataset.** Call `gads_get_keyword_performance` for the campaign over 30–90 days. Supplement
   with `gads_run_gaql_query` on `keyword_view` to capture the columns the summary tool may omit: quality score and
   its three components (`ad_group_criterion.quality_info.*`), impression share lost to rank and to budget,
   conversion value, and match type.
2. **Set the data floor.** Split the list: keywords with 100+ clicks in the window are actionable; everything below
   is tagged "insufficient data" and carried to the next cycle untouched. Zero conversions on 40 clicks is noise,
   not a verdict.
3. **Compute campaign benchmarks.** From the same data, derive per-campaign (never account-wide) averages: CPA,
   conversion rate, and ROAS where value bidding applies. These are the yardsticks for classification.
4. **Classify each actionable keyword** into one of four groups using the rules in Decision rules below: WINNERS
   (converting at/better than target), EXPENSIVE (converting but over target), CONSTRAINED (efficient or promising
   but starved of impressions), NON-CONVERTERS (meaningful spend, zero conversions). Report the distribution by
   keyword count and by share of spend, if EXPENSIVE plus NON-CONVERTERS hold more than 30% of spend, say so
   up front: that is the headline finding.
5. **Consult the policy guardrail.** Before the session's first Google Ads write, call `gads_policy_guardrail` and
   respect its output.
6. **Act on WINNERS first (protect, then scale).**
   - If the campaign shows impression share lost to budget above 10%, propose a raise via `gads_update_budget`, preview first (validate_only default), apply only after explicit user approval.
   - If a winner runs on phrase or broad only, propose adding its exact-match twin via `gads_add_keywords`
     (preview → approval → commit) so query routing stays anchored in this campaign.
7. **Act on NON-CONVERTERS second (stop the bleeding).** For each, run a four-point diagnosis before pausing:
   quality score under 5? actual queries relevant (check via `gads_get_search_terms_report` filtered to the
   keyword)? landing page matched to intent (HUMAN STEP to review the page itself)? CTR healthy, strong CTR
   that never converts points at the landing experience, weak CTR points at the ad or the query match itself.
   If a credible fix exists, route it (see
   Decision rules) and grant 30 more days. If there is no fix path, pause via `gads_pause_keyword`, preview → approval → commit.
8. **Act on EXPENSIVE third (repair efficiency).** Grade by how far CPA sits above target and route per the bands
   in Decision rules: copy/landing tune-ups for mild overruns, full Quality Score diagnosis for moderate, and a
   30-day fix-or-pause deadline for keywords at 2x+ target.
9. **Act on CONSTRAINED last (buy visibility carefully).** If impression share is lost to budget, reallocate from
   paused spend via `gads_update_budget` (preview → approval). If lost to rank on a Manual CPC campaign, raise the
   keyword bid 10–15% via `gads_update_keyword_bid` (preview → approval). On Smart Bidding, do NOT touch bids, rank losses there are fixed through Quality Score work, so route to `improve-quality-score`. Consider a
   match-type broadening only when Smart Bidding has volume to control it.
10. **Overlay Quality Score.** Filter all actionable keywords to QS < 7 regardless of group. Identify the weak
    component from the GAQL pull and route: expected-CTR gaps → `improve-expected-ctr`; keyword-to-ad mismatch →
    `improve-ad-relevance`; landing page label → `improve-landing-page-experience`. Prioritize winners' QS fixes
    first (cheapest CPC savings on your best traffic), then EXPENSIVE, then salvageable NON-CONVERTERS.
11. **Check close-variant drift on top keywords.** For the highest-spend WINNERS and EXPENSIVE keywords, pull
    `gads_get_search_terms_report` and compare the exact query against its variants on CTR, CVR, and CPA. A variant
    that beats its parent with real volume becomes an exact-match add (`gads_add_keywords`, preview → approval);
    a persistently worse variant becomes a negation candidate routed to `analyze-search-term-reports`.
12. **Deliver the prioritized action list.** One table sorted by impact (spend × expected improvement): keyword,
    group, action taken or proposed, expected effect, re-check date. Include the carry-forward list of
    insufficient-data keywords and every 30-day deadline set in steps 7–8.

## Decision rules
- **Actionability floor:** 100+ clicks in the analysis window. Below that, no action, no exceptions.
- **Group assignment (CPA campaigns):** WINNERS = conversions > 0 and CPA ≤ target. EXPENSIVE = conversions > 0
  and CPA > target. CONSTRAINED = low impressions/clicks with CPA ≤ target or too little conversion data.
  NON-CONVERTERS = 0 conversions after 100+ clicks.
- **Group assignment (ROAS campaigns):** same shape with ROAS ≥/< target; NON-CONVERTERS = 0 conversions after
  spend of roughly 2x the CPA-equivalent of target.
- **Spend-health signal:** EXPENSIVE + NON-CONVERTERS above 30% of campaign spend = the account's biggest single
  optimization opportunity; lead the report with it.
- **EXPENSIVE severity bands:** CPA 1–1.5x target → tighten copy/landing alignment, watch 2 weeks. 1.5–2x →
  full QS + landing + query diagnosis, watch 30 days. 2x+ → fix now with a 30-day deadline; still 2x+ after the
  deadline → pause.
- **NON-CONVERTER routing:** QS < 5 with a fixable component → QS skill + 30 days. Irrelevant queries → negatives +
  tighter match type + 30 days. Landing mismatch → landing fix + 30 days. No fix path → pause immediately.
- **Bid changes:** only on Manual CPC, only ±10–15% per cycle. Smart Bidding campaigns get budget, target, or QS
  levers, never per-keyword bids.
- **Budget trigger:** impression share lost to budget > 10% on a WINNER-heavy campaign justifies a raise or a
  reallocation from paused waste.

## Common failure modes
- **Acting under the click floor.** Pausing a 30-click keyword for zero conversions throws away a keyword that was
  never tested. Tag and wait.
- **Benchmarking against the account average.** A lead-gen campaign and a brand campaign have wildly different
  economics; classification only means something against the keyword's own campaign target.
- **Raising bids on Smart Bidding campaigns.** The algorithm owns bids; manual nudges either do nothing or distort
  learning. Rank problems there are quality problems.
- **Scaling CONSTRAINED keywords too hard.** An aggressive bid or match-type jump converts a promising keyword into
  an EXPENSIVE one. Move in 10–15% steps and re-read in two weeks.
- **Pausing before diagnosing.** Half of zero-conversion keywords have a specific, fixable cause (bad queries, bad
  page, bad ad). The four-point check in step 7 exists to find it before the pause.
- **Skipping the write-up.** Without the action list and deadlines, next cycle re-litigates the same keywords from
  scratch.

## Related skills
- Run alongside: `analyze-search-term-reports` (query-level hygiene feeding this triage).
- Route to for fixes: `improve-quality-score`, `improve-expected-ctr`, `improve-ad-relevance`,
  `improve-landing-page-experience`.
- Downstream of variants: `promote-search-terms-to-keywords` for formal promotion, `run-n-gram-analysis` for
  pattern-level negation.
- Orchestrated by: `run-search-campaign-optimization-cycle` as its keyword phase.