Documentation
Connect your marketing data to Claude, ChatGPT and other LLMs.
Negatives — read all 4 mechanisms, manage from Claude
Google Ads has four distinct mechanisms for negative keywords / placements / brand exclusions. Most tools only show one. gadspilot reads all four into a unified view + lets Claude manage them all via dedicated MCP tools.
The 4 mechanisms (and why this matters)
| Mechanism | Used by | How to add (UI) | How to add (Claude / MCP) |
|---|---|---|---|
| Direct campaign-level negatives | Search campaigns | Campaign → Keywords → Negative keywords | add_negative_keywords(level=CAMPAIGN, ...) |
| Direct ad-group-level negatives | Search campaigns (granular) | Ad group → Keywords → Negative keywords | add_negative_keywords(level=AD_GROUP, ...) |
| Shared lists (campaign_shared_set + shared_criterion) | PMax (the only mechanism) + Search via shared lists | Tools & Settings → Shared library → Negative keyword lists | shared_set_create + campaign_shared_set_link + shared_set_criterion_add |
| Brand exclusions (campaign_criterion type=BRAND) | PMax (mostly), some Search | Campaign → Settings → Brand exclusions | shared_set_create(type=BRANDS) + shared_set_criterion_add |
add_negative_keywords on a PMax campaign, the API rejects. Use the shared set workflow instead (4-step pipeline below).Negatives tab on /accounts/{id}/insights
Open any account insights page → bottom tabs → Negatives (count badge shows total deduplicated). The unified table shows :
- Keyword / Brand — the actual text
- Match — color-coded (green EXACT, cyan PHRASE, amber BROAD, pink BRAND)
- Level — color-coded badge :
- 🔴 BOTH — exists at campaign AND ad group level (most impactful)
- 🔵 CAMPAIGN — direct campaign-level only
- 🟠 AD GROUP — direct ad-group-level only
- 🟣 SHARED LIST — via a shared list (PMax mechanism)
- 🩷 BRAND EXCLUSION — brand exclusion (PMax-specific)
- Source / List — for shared lists, shows the list name (ex: "PMax brand negatives B2B")
- Campaign + Ad group — context
Filters at the top : All / Both / Campaign / Ad group / Shared list / Brand exclusion + live keyword search.
4-step PMax negative pipeline (via Claude)
1. List existing shared sets to see if a relevant one exists :
list_shared_sets(type="NEGATIVE_KEYWORDS")
2. If none, create one + link to the PMax campaign :
shared_set_create(name="PMax brand negatives B2B", type="NEGATIVE_KEYWORDS")
campaign_shared_set_link(campaign_id="123", shared_set_id="456")
3. Add the keywords :
shared_set_criterion_add(
shared_set_id="456",
keywords=[
{text: "free", match_type: "BROAD"},
{text: "tutorial", match_type: "PHRASE"}
]
)
4. Verify :
list_shared_set_criteria(shared_set_id="456")
Removing negatives
Single criterion or batch — same approach
# 1. Get criterion_ids from the list
list_shared_set_criteria(shared_set_id="456")
# returns [{criterion_id: 789, text: "free", ...}, {criterion_id: 790, text: "tutorial", ...}]
# 2. Remove one or many
shared_set_criterion_remove(
shared_set_id="456",
criterion_ids=["789", "790"]
)
Detach a shared list from a campaign without deleting it
Useful to A/B test the impact of an exclusion list :
campaign_shared_set_unlink(campaign_id="123", shared_set_id="456") # Run the campaign for 1 week with no shared list, measure impact, then re-link if needed.
How the AI uses the negatives in context
Every time you launch the in-app AI chat on the Insights page, the system fetches up to 80 negative criteria (across all 4 mechanisms) and injects them in the prompt under NEGATIVE_KEYWORDS. The AI is then bound by Rule 5bis in the system prompt :
shared_set_criterion_add and not add_negative_keywords directly. The AI also flags negatives that are too broad (ex: "free" BROAD blocking legitimate "free trial" queries).FAQ
Why does the same keyword appear in 2 sources?
Some agencies maintain a "master list" (shared) that overlaps with per-campaign direct negatives. The unified view shows both so you can clean up the duplication. The AI flags this too.
Can I block a YouTube channel via shared list?
Yes — use shared_set_create(type=NEGATIVE_PLACEMENTS) then shared_set_criterion_add with placements (URL, YouTube channel ID, etc.). Or for one-off blocks on a specific campaign, use add_negative_placements(campaign_id, youtube_channel_ids=[...]) directly.
What's a brand exclusion vs a regular negative?
Brand exclusions exclude a Google-recognized BRAND ENTITY (a normalized brand identity) instead of a literal keyword string. Used in PMax to protect brand bidding (don't show on competitor brand searches). Created via shared sets of type BRANDS.
Can I see how many search terms each negative actually blocks?
Not directly — Google doesn't expose this. But you can run the in-app AI chat with question "Which of my negatives blocks the most volume? Cross-reference with last 30 days search terms." and the AI estimates from the data it has.
