negative-keyword-sweep

Goal

Pull the search-terms report, identify spend that isn't producing, group it intelligently, and add negatives at the right level — without nuking legitimate intent.

Inputs to confirm (batch)

1. Account name (substring) — required.
2. Scope — single campaign, list of campaigns, or "all Search campaigns" — required.
3. Lookback — default 30 days; user can override (60 / 90).
4. Waste thresholds — defaults; allow override:
   • No-converter: spend ≥ $X over lookback AND 0 conversions. Default $X = 2× target CPA, or $50 if no target.
   • Low-CVR offender: spend ≥ 3× target CPA AND CVR < 25% of account CVR.
   • Off-brand / off-intent: terms that match a denylist of words (e.g. free, jobs, careers, tutorial, review, salary, download, cheap, pirate, crack) — calibrated to vertical.
5. Negative scope preference — default behavior:
   • Recurring junk seen across multiple campaigns → account-level shared negative list.
   • Waste seen only in one campaign → campaign-level.
   • Single-theme misintent (e.g. "free" only hurts a paid product ad group) → ad-group-level.
   • Default match type: phrase, except for single-word obvious junk → broad isn't an option (negatives have no broad), so use exact for single tokens like free.

Workflow

1. Discover ops: gads_select_accounts, gads_list_report_fields, gads_get_report, gads_create_negative_keyword_list, gads_attach_negative_list_to_campaigns, gads_add_keywords_to_negative_list, gads_add_negative_keywords_to_campaigns, gads_add_negative_keywords_to_ad_groups.
2. Inspect every op via get_operation_inputs.
3. Resolve account (substring).
4. Pull search-terms report via gads_get_report at the search-term granularity (search_term_view resource). Required fields: search_term, campaign_id/name, ad_group_id/name, impressions, clicks, cost, conversions, conv_value, ctr, cvr.
5. Compute baselines: account-level CVR over lookback. Compute target CPA if not given (use account history / average across the scope).
6. Apply thresholds → candidate list. Tag each candidate with the trigger reason (no-conv, low-CVR, denylist).
7. Cluster candidates by intent. Group on shared roots / themes (e.g. free trial spreadsheet, free template excel, free download → cluster "free*"). For each cluster, propose:
   • Negative keyword(s) (the minimum tokens needed to block the cluster — usually a phrase).
   • Match type (phrase by default; exact for single-token denylist hits; phrase for multi-word patterns).
   • Scope (account / campaign / ad-group) per the rules above.
8. Build a preview table showing every proposed negative with: keyword, match, scope, target campaigns/ad groups, wasted spend that would have been blocked, and a sample of 1–3 search terms it covers. Wait for user confirmation.
9. Execute:
   • Account-level batch → if a list with the right purpose already exists, use gads_add_keywords_to_negative_list. If not, gads_create_negative_keyword_list then gads_add_keywords_to_negative_list then gads_attach_negative_list_to_campaigns.
   • Campaign-level batch → gads_add_negative_keywords_to_campaigns.
   • Ad-group-level batch → gads_add_negative_keywords_to_ad_groups.
10. Confirm: count by scope, total estimated spend blocked.