AdLoop

All Google Ads write tools follow a strict safety workflow to prevent accidental changes.

The Workflow

1. Draft: Call a draft_* tool (e.g., draft_campaign, draft_ad_group, draft_responsive_search_ad). This returns a preview with a plan_id but makes no changes.
2. Review: Show the full preview to the user and wait for explicit approval.
3. Dry Run: Call confirm_and_apply(plan_id=..., dry_run=true) to test the execution against the API.
4. Apply: Only call confirm_and_apply(plan_id=..., dry_run=false) after explicit user confirmation.

Safety Behaviors

• Paused by Default: New campaigns, Reddit entities, and RSAs are created in a PAUSED state. They must be explicitly enabled.
• Targeting Requirements: draft_campaign requires geo_target_ids and language_ids. It will reject drafts missing these.
• Budget Caps: draft_campaign enforces a max_daily_budget safety cap and warns if the budget is below 5x the target CPA.
• Irreversible Actions: remove_entity is irreversible. Always prefer pause_entity unless permanent removal is requested. remove_entity requires double confirmation.
• Replacement vs. Appending: update_campaign replaces positive geo/language targets entirely. It does not append. However, negative geo exclusions are preserved during the swap.

Configuration Overrides

• require_dry_run: true: If set in config, the system will refuse dry_run=false until the user manually changes the config.
• two_phase_apply: true: (Default on AdLoop Cloud) Refuses dry_run=false until the specific plan_id has successfully completed at least one dry_run=true pass.

# Example workflow
plan = draft_campaign(campaign_name='New Promo', daily_budget=50, ...)
# ... user reviews plan ...
confirm_and_apply(plan_id=plan.id, dry_run=True)
# ... user confirms ...
confirm_and_apply(plan_id=plan.id, dry_run=False)

AdLoop implements several safety mechanisms to prevent accidental ad spend:

• Two-step writes: Mutations return a preview first. You must call confirm_and_apply to execute changes.
• Dry-run by default: confirm_and_apply defaults to dry_run=true. You must explicitly set dry_run=false for real changes.
• Two-phase apply (optional): If safety.two_phase_apply: true is configured, confirm_and_apply will refuse dry_run=false until a successful dry-run pass has been completed.
• Budget caps: The server rejects any operation exceeding your configured maximum daily budget.
• New entities are PAUSED: All new campaigns and ads are created in a PAUSED state by default.
• Broad Match protection: draft_keywords prevents adding BROAD match keywords to campaigns that do not use Smart Bidding.
• Audit logging: All operations, including dry runs, are logged to ~/.adloop/audit.log.

In Google Ads, Audiences and Demographics are distinct concepts:

Audiences

User lists like remarketing, in-market, or affinity segments. Use get_audience_performance to analyze them.

Demographics

Fixed buckets for Age, Gender, Parental Status, and Income. Use get_demographic_targeting and draft_demographic_targeting.

Compatibility Matrix

Key Constraints:

• Custom segments cannot be attached to Search campaigns.
• PMax uses audience segments as signals (hints), not hard targeting filters.
• Demographic Exclusions: Campaign-level demographic criteria can only be exclusions (negative=True). Positive (narrowing) demographic targeting must be applied at the ad group level.

GAQL is a SQL-like language used to query Google Ads data. When using run_gaql, adhere to these critical rules to avoid errors:

• No SELECT *: You must explicitly name every field you want to retrieve.
• Ordering Constraint: Any field used in an ORDER BY clause must also be present in your SELECT clause. For example, ORDER BY metrics.cost_micros will fail if metrics.cost_micros is not selected.
• Field Compatibility: Certain resource attributes cannot be combined with specific metrics or segments. If a query fails, verify the field compatibility for that resource.
• Micros Conversion: Values for cost_micros are returned in micros. To get the actual currency amount, divide the value by 1,000,000. (Note: Dedicated read tools like get_campaign_performance handle this conversion automatically; only run_gaql returns raw micros).
• Date Segments: When selecting segments.date, results are broken down by day. The search_term_view resource always requires a date segment in the WHERE clause.

SELECT field1, field2, ...
FROM resource
WHERE condition
ORDER BY field [ASC|DESC]
LIMIT n

When diagnosing tracking issues, you must account for GDPR cookie consent, which creates a natural discrepancy between Google Ads and GA4 data.

The Consent Gap

• Google Ads: Counts all clicks regardless of user consent.
• GA4: Only records sessions and events for users who accept analytics cookies.
• Expected Ratio: A ratio of 2:1 to 5:1 (clicks:sessions) is normal when consent banners are present. This is not necessarily a tracking bug.

Diagnostic Workflow

Before flagging tracking as broken, evaluate the following:

1. Consent Rejection: If Ads shows 10 clicks but GA4 shows 3 sessions, this is likely due to consent rejection.
2. Zero Sessions: If GA4 shows zero sessions from paid traffic, check UTM parameters and GA4 filters in addition to consent.
3. Systemic Failure: Only flag tracking as broken if the discrepancy cannot be explained by consent (e.g., GA4 shows zero sessions for all traffic sources, including organic).

Google Consent Mode v2

If GA4 data appears closer to Google Ads data than expected, the site may be using Consent Mode, which sends cookieless pings to GA4. You can verify this by searching the codebase for gtag('consent', ...) calls.

You can add AdLoop to Claude Code using the CLI or by editing your .mcp.json file.

Using CLI:

claude mcp add --transport stdio adloop -- /absolute/path/to/adloop/.venv/bin/python -m adloop

Using .mcp.json:

{
  "mcpServers": {
    "adloop": {
      "command": "/absolute/path/to/adloop/.venv/bin/python",
      "args": ["-m", "adloop"]
    }
  }
}

Install Orchestration Rules: After connecting, run the following command to install slash commands (prefixed adloop-*) and orchestration rules:

adloop install-rules

Install Modes:

• inline (default): Embeds full rules into ~/.claude/CLAUDE.md. Adds ~10K tokens to every session.
• lazy: Use adloop install-rules --lazy. Places a small directive in CLAUDE.md pointing to ~/.claude/rules/adloop.md. The LLM only reads the rules when AdLoop tools are in scope, saving tokens.

Maintenance:

• Refresh rules after upgrade: adloop update-rules
• Remove rules: adloop uninstall-rules

To reduce the token cost in MCP clients (like Claude, ChatGPT, or Cursor), you can limit the number of tools loaded by setting the ADLOOP_TOOLSETS environment variable. This prevents the model from loading the entire 18k token catalog at the start of every session.

Set the variable in your MCP client's env block using a comma-separated list of toolset names.

Available Toolsets:

• ads: Google Ads reads, writes, and planning (Keyword Planner).
• ga4: Google Analytics reports, realtime, and key events.
• tracking: Cross-channel attribution and tracking code generation.
• gtm: Google Tag Manager audits and reads.
• gsc: Search Console reads.
• web: PageSpeed / Core Web Vitals.
• merchant: Merchant Center feed health.
• reddit: Reddit Ads reads, writes, and planning.

Note: health_check and confirm_and_apply are always included. Unsetting the variable loads the full catalog.

"env": { "ADLOOP_TOOLSETS": "ads,ga4" }