ppc-negative-keyword-applier
Skill8 starsChanged 45 days agoMITView on GitHub
Find the exact Sponsored Products search terms burning budget with no sales, then add them as negative keywords through DataDoe Actions - always a dryRun preview first, and a real change only on your explicit approval. The write follow-through to the wasted-spend watchdog. Live from DataDoe, runs in chat. Use for "wasted ad spend", "add negative keywords", "negate search terms", "search terms with no sales", "stop paying for these clicks", or "clean up my PPC".
In this repository26 other files it gives its agents.
- amazon-asin-search-auditorSkill
- amazon-listing-optimizerSkill
- buy-box-loss-root-causeSkill
- create-amazon-reconciliation-dashboardSkill
- create-orders-managerSkill
- daily-account-health-checkSkill
- daily-performance-health-checkSkill
- fba-inventory-ledger-reportSkill
- fba-stock-restock-plannerSkill
- keyword-rank-sqp-trackerSkill
- net-profit-pl-analyzerSkill
- ppc-asin-acos-alertSkill
- ppc-bid-optimizer-applySkill
- ppc-campaign-acos-alertSkill
- ppc-profit-bid-applySkill
- ppc-wasted-spend-watchdogSkill
- promotions-managerSkill
- restock-priority-alertSkill
- return-refund-analyzerSkill
- sales-movers-scannerSkill
- suppressed-inactive-listings-checkSkill
- vendor-inventory-reportSkill
- vendor-performance-dashboardSkill
- vendor-pnl-dashboardSkill
- weekly-business-reviewSkill
- weekly-sales-briefingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 53
Starting from a Watchdog hand-off: When the user hands over terms from ppc-wasted-spend-watchdog (its dead terms and negate bleeders, each …
- Very specific: line 72
Read source: Search Term Performance (Ads) - amazon_ads_search_terms_by_campaign_by_date (source id e94e967198): ad_search_term, …
- Very specific: line 86
Write action: AMAZON_ADS_TARGETS_ADD (negative keyword), gated behind a dryRun step.
- Very specific: line 98
Match type is
EXACT/PHRASE/BROAD: - never NEGATIVE_EXACT / NEGATIVE_PHRASE. - Very specific: line 327
Write skill. It uses DataDoe Actions and only writes on explicit approval.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PPC Negative-Keyword Applier
Finds the exact Sponsored Products search terms that are burning budget with no
sales, then adds them as negative keywords through DataDoe Actions. It always
runs a dryRun first and shows you every change before anything reaches Amazon,
so it is safe to demo and safe to run. MCP-native end to end.
When to use this
- Your ACoS is creeping up and you suspect junk search terms.
- Weekly PPC cleanup: stop paying for clicks that never convert.
- Right after a launch, when broad/auto campaigns catch a lot of irrelevant traffic.
- Trigger phrases: "wasted ad spend", "negative keywords", "add negatives", "search terms with no sales", "stop paying for these clicks", "clean up my PPC".
The framework. Find, confirm, apply
- Find the wasteful terms from performance data (read).
- Confirm the list and the exact match type with the user (nothing is automatic).
- Apply as negatives via a
dryRunAction, review the validated payload, then run for real only on explicit approval.
What counts as "wasteful" (defaults, tune per user)
A search term is a negative candidate when, over the last 30-60 days:
ad_spend>= 2x your target CPA (or >= the item price if you do not know CPA), ANDad_orders= 0 (no attributed orders), ANDad_clicks>= 10 (enough clicks to trust the zero).
Borderline (spend above target CPA but a few orders) -> list separately as "review", do not auto-negate.
Starting from a Watchdog hand-off. When the user hands over terms from
ppc-wasted-spend-watchdog (its dead terms and negate bleeders, each with campaign and ad
group ids), use that list as the candidates: skip steps 3-4 and the spend rule above - the
Watchdog applied its own rules, and its negate bleeders have orders by design - and say
which Watchdog run (window, break-even ACoS) the list came from. Still run the own-keyword
guard when the hand-off has no keyword detail (export 3b for those ad groups), the dedupe
(step 5), the live state check (step 5b), the confirmation and the dry run. Applying the
spend rule to a Watchdog list drops most of it (one run: 30 handed-over dead terms at GBP
1.50-7.20 each, below 2x CPA).
Exclude ASIN-target terms first. Many "dead" search terms are ASIN strings (e.g.
b0ch3jb9h1 - a 10-char B0... alphanumeric) = deliberate competitor-ASIN targeting,
not junk queries. Filter these out (or list them separately as "ASIN target - review")
before negating, so you don't kill legitimate competitor targeting - they often dominate
the top spenders.
Configuration
- MCP base:
https://mcp.datadoe.com/mcp/v1 - Read source:
Search Term Performance (Ads)-amazon_ads_search_terms_by_campaign_by_date(source ide94e967198):ad_search_term,ad_campaign_id,ad_group_id,ad_spend,ad_clicks,ad_orders,ad_campaign_type(+ names), and for the guardsad_keyword,ad_keyword_id,ad_match_type,ad_keyword_status,ad_campaign_status. - Two guards before anything is proposed as a negative: (1) own keyword - a search
term that equals the ad group's own bid keyword (
lower(trim(ad_search_term)) == lower(trim(ad_keyword))with a positivead_match_typeEXACT / PHRASE / BROAD) is never negated; negating it silently switches off the keyword the seller is paying for. Route it toppc-bid-optimizer-apply(pause or lower the bid onad_keyword_id). (2) live state - a negative inside a PAUSED or ARCHIVED campaign or ad group validates and does nothing; confirm state withAMAZON_ADS_CAMPAIGNS_FIND/AMAZON_ADS_AD_GROUPS_FIND(stateFilter.include: ["ENABLED"]) before the dryRun. The*_rawAds tables are 72-hour snapshots and are only the fallback when FIND is refused because that Action type is disabled. FIND runs on Read only and Read and write accounts. - Write action:
AMAZON_ADS_TARGETS_ADD(negative keyword), gated behind adryRunstep. A negative keyword isnegative: true+targetType: "KEYWORD"+targetDetails: { keywordTarget: { keyword, matchType } }, scoped to acampaignId+adGroupId; max 25 targets per action (schemamaxItems: 25) - batch longer lists into several actions. - Dedupe source:
Negative Keywords-amazon_ads_negative_keywords(source id36596ff85e):ad_campaign_id,ad_group_id,ad_keyword_text,ad_match_type,ad_keyword_state. Weekly snapshot (date= Monday),requiresDatePeriod: true; large (about 34,800 Sponsored Products negatives per snapshot on one UK account), so always read one snapshot filtered to the candidates' campaigns (step 5). Itsad_match_typeis Amazon's reporting name (NEGATIVE_EXACT/NEGATIVE_PHRASE) - that is read-side naming only; the ADD payload still usesEXACT/PHRASE+negative: true. - Match type is
EXACT/PHRASE/BROAD- neverNEGATIVE_EXACT/NEGATIVE_PHRASE. The negativity is carried by the separatenegative: trueflag, not by the match-type value; the live backend rejectsNEGATIVE_*match types. - Currency/marketplace: read
marketplace_country_codefor display/currency in the output only. Do NOT put marketplace in the ADD payload -AMAZON_ADS_TARGETS_ADDon Sponsored Products rejectsmarketplaceScope/marketplaces; thecampaignId/adGroupIdalready scope the negative to the right marketplace. - Prerequisites for a live apply: the Seller or Vendor must be Read and write
(Accounts page), and the
AMAZON_ADS_TARGETS_ADDAction type must be enabled (Settings > Actions).AMAZON_ADS_CAMPAIGNS_FIND,AMAZON_ADS_AD_GROUPS_FIND, andAMAZON_ADS_TARGETS_FINDrun on Read only and Read and write accounts. A dry run still validates the write on a Read only account and does not queue it. The find and preview always run.
Step-by-step workflow (MCP-native)
Phase 1 - Find (read)
sellers_and_vendors_list-> pick the seller, keepsellerOrVendorId.exports_sources_get(query "search term") -> confirmamazon_ads_search_terms_by_campaign_by_dateisenabled.- Two
exports_createcalls onamazon_ads_search_terms_by_campaign_by_date, last 30-60 days, filterad_campaign_type = SPONSORED_PRODUCTS, CSV. Never export the ungrouped daily rows and aggregate them yourself: they run to tens of thousands (86,082 Sponsored Products rows in 60 days on one UK account) against the 5,000-row CSV cap, so each term would be judged on whatever fraction of its days fit on the page.- (a) Candidates, term grain:
groupBy ["ad_search_term", "ad_campaign_id", "ad_group_id"], sumad_spend,ad_clicks,ad_orders,ad_saleswith distinct aliases (spend_sum,clicks_sum,orders_sum,sales_sum),having clicks_sum >= 10,limit5,000; sort by spend in code. If it can exceed one page, do not page withskipon spend or term - the backend sorts by one column and none is unique at this grain, so rows can be read twice or never. Split by ad group instead, as the Watchdog's step 3a does: a size map (groupBy ["ad_campaign_id", "ad_group_id"],countDistinct(ad_search_term)), whole ad groups packed into chunks of at most 5,000 terms, one export per chunk withad_group_id in (...); an ad group above 5,000 terms alone is ordered byad_search_term(unique inside one ad group) and paged withskipfrom 0. This is the negative's own grain: a negative is added per ad group and blocks the term for every keyword and target there, so zero orders must hold across all of them. Never add keyword, status or name columns to thisgroupBy- one term then splits into one row per matched keyword or target, and a term that converts through another target looks dead (observed: 0 orders through an ASIN target, 22 through a category target, same ad group). - (b) Keyword detail, for the guards only:
groupBy ["ad_search_term", "ad_campaign_id", "ad_group_id", "ad_keyword", "ad_keyword_id", "ad_match_type", "ad_keyword_status", "ad_campaign_status"](+ad_campaign_name/ad_group_namefor the report), the same sums plusmax(date) as last_seen, filterad_group_id in (...)for the candidate ad groups from (a), in chunks of ad groups that each fit one page (if a chunk returns exactly 5,000 rows, split it - noskip, this grain has no unique order). It returns every term in those ad groups (1,647 rows for three ad groups on one UK account); to shrink it, also filterad_search_term in (...)for the candidate terms- the
invalue is a comma-separated list, so a term that itself contains a comma needs its own=filter. Join to (a) on(ad_campaign_id, ad_group_id, ad_search_term).
- the
- (a) Candidates, term grain:
- Poll, download, and apply the wasteful rule above to (a) - dead candidates are the rows
with
orders_sum = 0and enough spend; rows with spend above CPA and a few orders go to "review". Own-keyword guard: drop every candidate whose normalised term equalsad_keywordon any of its (b) rows with a positive match type - one term can match several keywords in one ad group (close variants -trainer cleaning kitmatched bothtrainer cleaning kitandtrainers cleaning kit) - and list them under "Excluded: own keyword - route to bid optimizer" with thead_keyword_id(note "already paused" when that keyword's latestad_keyword_status, bylast_seen, is PAUSED). Observed on a UK account: the top dead term was the exact keyword of its own ad group. Produce the candidate list with spend, clicks, orders, and the target campaign/ad group ids. - Dedupe against existing negatives - two exports on
amazon_ads_negative_keywords(weekly snapshot,date= Monday; it needs a date period):- Pick the snapshot first, independent of state:
from= 14 days ago,to= today,groupBy ["date"],count(ad_keyword_id), filterad_campaign_type = SPONSORED_PRODUCTSonly - no state filter. The newestdatereturned is the snapshot. Never choose it from state-filtered rows: a negative paused this week has no ENABLED row on the newest date, but last week's ENABLED row would survive and wrongly suppress the candidate as "already negated". - Read that snapshot only:
from=to= that date, filterad_campaign_type = SPONSORED_PRODUCTSandad_campaign_id in (...)for the candidates' campaigns, columnsdate,ad_keyword_id,ad_campaign_id,ad_group_id,ad_keyword_text,ad_match_type,ad_keyword_state, CSV,orderByColumn ad_keyword_id- it must be among the selected columns (the backend rejects the request otherwise withFIELD_NOT_FOUND: Order by column ... must be in selected columns, group by, or aggregations) and it is unique within one snapshot, soskippages are stable - page until a page returns fewer rows, then keep the rows withad_keyword_state = ENABLED. Even filtered to the candidates' campaigns this can run to thousands of rows (14,965 for 27 campaigns on one UK account - three CSV pages); dedupe only after reading every page. Drop every candidate whose lower-cased term already exists for the samead_campaign_id
ad_group_id(match onad_campaign_id+ term alone whenad_group_idis null - it is null for Sponsored Products rows before 2026-07-01). Report the skipped count as "already negated". The snapshot is weekly, so a negative added in the last few days can still slip through; if the live ADD then reports a duplicate for that term, treat it as a no-op, not a failure. 5b. Live state check (campaign and ad group).actions_startAMAZON_ADS_CAMPAIGNS_FINDwithcampaignQuery.adProductFilter.include: ["SPONSORED_PRODUCTS"],campaignIdFilter.include: [<candidate campaign ids>],stateFilter.include: ["ENABLED"],maxResults: 100; thenAMAZON_ADS_AD_GROUPS_FINDwithadGroupQuery.adGroupIdFilter.include: [<candidate ad group ids>]and the same product, state andmaxResultssettings. Read every page before judging: pollactions_getuntil each FIND completes; while the result carries anextToken, start the same FIND again with thatnextTokenand an otherwise identical query, and collect the returned ids across all pages. A page holds at most 100 results, and an ID filter longer than 100 is queried in groups of 100 that page throughnextTokenas well (only one ID filter per FIND may exceed 100). Only when both FINDs are exhausted: any candidate whose campaign or ad group is missing from the collected ids is paused or archived - drop it and list it under "Skipped: campaign / ad group paused". Observed: a live FIND returneddeliveryReasons: ["AD_GROUP_PAUSED"]for an ad group holding a dead term - a negative there would validate and do nothing. Read only access is enough for these FIND Actions. If FIND is refused because the Action type is disabled, fall back toad_campaign_statusfrom the export andamazon_ads_ad_groups_raw.ad_group_state(a 72-hour snapshot) and say the check uses the snapshot. Do not ask for Read and write only to run FIND. Optional: whenad_keywordis empty,AMAZON_ADS_TARGETS_FINDwithnegativeFilter.include: [false]andkeywordFilter: { include: [<term>], queryTermMatchType: "EXACT_MATCH" }on the ad group confirms whether a positive keyword with that text exists.
- Pick the snapshot first, independent of state:
Phase 2 - Confirm
- Show the ranked candidate list (most wasted spend first, ASIN-target terms excluded /
flagged) and the total spend it would stop. Ask the user which to negate and at what
match type -
EXACTis safest (negates only that exact term);PHRASEis broader. The term is negated bynegative: true; the match type is justEXACT/PHRASE/BROAD. Do not proceed without a selection.
Phase 3 - Apply (dryRun, then real)
actions_details_schema_getforAMAZON_ADS_TARGETS_ADDand read the exacttargetDetailsshape before building the payload.- Build one
targets[]entry per approved term:{ "campaignId": "<ad_campaign_id>", "adGroupId": "<ad_group_id>", "adProduct": "SPONSORED_PRODUCTS", "state": "ENABLED", "negative": true, "targetType": "KEYWORD", "targetDetails": { "keywordTarget": { "keyword": "<ad_search_term>", "matchType": "EXACT" } } }matchTypemust beEXACT/PHRASE/BROAD(neverNEGATIVE_*); the negativity is thenegative: trueflag.keywordTargetis the schema's wrapper key; a flattargetDetails: { keyword, matchType }also validates whentargetTypeis set. Max 25 targets per action - split longer lists. Do NOT addmarketplaceScope/marketplaces-AMAZON_ADS_TARGETS_ADDon Sponsored Products rejects them ("does not support marketplaceScope/marketplaces for SPONSORED_PRODUCTS"); thecampaignId/adGroupIdalready scope the negative to the right marketplace. actions_start type="AMAZON_ADS_TARGETS_ADD"withdryRun: true. This validates the whole batch without touching Amazon (works even if the Action type is disabled) - confirmstatus: VALIDATED, valid: true, actionId: null.- Show the validated result and the before/after list. Only if the user explicitly
approves, call
actions_startagain withdryRun: false, pollactions_getuntil it completes, and report per-term acceptance. Otherwise stop - nothing changed.
Output format
Negative-keyword candidates - {marketplace} - last {N} days{ - from the Watchdog run of {window}, break-even {t}%}
Spend on these terms in the window: {currency}{sum} (past spend the negatives would have blocked){; the negate bleeders among them also had {o} orders / {currency}{sales} of sales, which a negative stops too}
Already negated (skipped): {m} terms (snapshot {date}; {n} existing negatives read)
Excluded: own keyword - route to bid optimizer: {k} terms ({ad_keyword_id}, ...){, {u} removed upstream by the Watchdog}
Skipped: campaign / ad group paused: {p} terms{, {u2} removed upstream by the Watchdog}
# Search term Spend Clicks Orders Campaign / Ad group Match
1 {term} {cur}{v} {n} {o} {campaign} / {group} EXACT (neg) (0 for dead terms; orders shown for negate bleeders)
...
Dry run: {k} targets validated, 0 errors ({b} batches of <= 25).
Reply "apply" to add these negatives for real, or edit the list first.Worked example (illustrative)
A term with ~€42 spend, ~61 clicks, 0 orders in an auto/discovery campaign: above
2x CPA, zero orders, plenty of clicks -> negative candidate. Proposed as a negative
(negative: true) with matchType: "EXACT". Dry run returns VALIDATED / actionId:
null. On "apply", the negative is added and future spend on that term stops.
Quality self-check
- Did I only include terms with enough clicks to trust the zero-order signal - or, for a Watchdog hand-off, use its list as given and still run dedupe, live state and dry run?
- Did I find candidates from the grouped term-grain export (search term + campaign + ad
group), never from ungrouped daily rows truncated at 5,000, and never with keyword or
status columns in that
groupBy- and if it needed more than one page, in ad-group chunks rather thanskippages on spend? - Did I select
ad_keyword_idin the dedupe export, since it is theorderByColumn? - Did I exclude / flag ASIN-target terms (
b0...) so I don't kill competitor targeting? - Did I use
matchType: EXACT/PHRASE/BROAD+negative: true(neverNEGATIVE_*)? - Did I keep each negative in its own campaign/ad group (ids from the data)?
- Did I drop terms already present in
amazon_ads_negative_keywordsfor that campaign/ad group - reading only the newest snapshot, picked before any state filter and filtered to the candidates' campaigns - and report how many I skipped? - Did I split the batch so no action carries more than 25 targets?
- Did I exclude terms that are the ad group's own bid keyword and route them to the bid optimizer instead of negating them?
- Did I confirm campaign and ad-group state live (
CAMPAIGNS_FINDandAD_GROUPS_FIND, ENABLED only) before the dry run? Read only access is enough. FollownextTokenthrough every page before calling a missing id paused, and skip paused ones. - Did I run
dryRun, confirmVALIDATED/actionId: null, and show it before any real write? - Did I get explicit approval before
dryRun: false? - Is the marketplace / currency right for the output display (it is NOT passed in the ADD payload)?
Common mistakes
- Negating a term after 2-3 clicks - too little data, you may kill a converter.
- Aggregating ungrouped daily search-term rows yourself - the export stops at 5,000 rows (86,082 existed in 60 days on one account), so a term's converting days can fall off the page and it looks dead. Group by search term, campaign and ad group in the export.
- Treating an id missing from the first FIND page as paused - FIND returns at most 100
results per page; follow
nextTokenwith the same query until it runs out. - Choosing the negatives snapshot after filtering
ad_keyword_state = ENABLED- last week's ENABLED row of a negative paused this week survives and suppresses a real candidate. Pick the newestdatefirst, then filter state. - Adding a negative account-wide instead of to the campaign/ad group that spent.
- Skipping the dry run. Always validate first; you are responsible for writes.
- Confusing search term (what the shopper typed) with keyword (what you bid on) - you negate the search term.
- Using
NEGATIVE_EXACT/NEGATIVE_PHRASEas the match type - the live backend only acceptsEXACT/PHRASE/BROAD; negativity is the separatenegative: trueflag. - Negating ASIN-target terms (
b0...strings) - that's deliberate competitor targeting, not a junk query. - Re-adding a negative that already exists - check
amazon_ads_negative_keywordsfirst; duplicates waste the 25-target budget and confuse the before/after report. - Negating a term that is the ad group's own bid keyword - that silences the keyword without anyone seeing why. Pause or lower it via the bid optimizer instead.
- Adding a negative inside a paused campaign or ad group - it validates and changes
nothing. Confirm state live first; the
*_rawtables are 72-hour snapshots. - Trusting the JSON schema alone - always dryRun against the live backend. The schema
still lists
marketplaceScope/marketplaces, but the backend rejects them forAMAZON_ADS_TARGETS_ADDon Sponsored Products (verified by dryRun 2026-10-03:EXACT+negative: true->VALIDATED;NEGATIVE_EXACT-> "Invalid option";marketplaceScope-> "does not support marketplaceScope for SPONSORED_PRODUCTS").
Notes
- Write skill. It uses DataDoe Actions and only writes on explicit approval;
dryRuncovers demos and testing with no live changes. - A DataDoe skill, built on the DataDoe Search Term Performance source +
AMAZON_ADS_TARGETS_ADD.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

