Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 51 additions & 2 deletions .claude/rules/adloop.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog

| Tool | When to Use | Key Parameters |
|------|-------------|----------------|
| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads connectivity | (none) |
| `health_check` | First thing to run when tools are failing — tests OAuth token, GA4, Ads, and (when configured) Reddit Ads and Microsoft Advertising connectivity | (none) |

**A tool you expect is missing?** Apps such as claude.ai, ChatGPT and Perplexity cache AdLoop's tool list from when the connection was made. `health_check` returns `adloop_version` and `tools_offered`, the tools this server offers to you. If the user asks for something a tool in `tools_offered` does and that tool isn't in your own tool list, don't improvise with other tools: tell the user their app shows an older list and to refresh the AdLoop connection (claude.ai: Settings → Connectors → AdLoop; ChatGPT: the AdLoop plugin's settings; Perplexity: remove and add the connector again; coding agents: reconnect the MCP server or start a new session).

Expand Down Expand Up @@ -265,6 +265,53 @@ Reddit is a second ad platform with its own connection (own OAuth app, no develo
4. Cross-check `get_reddit_ads` for `REJECTED` ads (`rejection_reason`) and `PENDING_APPROVAL` — they explain missing spend
5. Present spend, clicks, CTR, CPC, conversions, CPA in account currency; compare against Google Ads only on CPA/ROAS, never on CTR (feed placements behave differently from search)

### Microsoft Advertising Tools

Microsoft Advertising (Bing, Yahoo, AOL, DuckDuckGo search ads) through the REST API v13. Toolset `microsoft_ads`; needs `microsoft_ads.developer_token`, `microsoft_ads.client_id` (an Entra app with public client flows and the msads.manage permission) and a one-time `adloop microsoft-login` (browser sign-in; the Entra app registers `http://localhost/callback` and the sign-in listens on a free port of it, since Entra ignores the port of localhost redirects. Sign in with the user that has access to the ad accounts. Directories with security defaults block the device-code flow with sign-in error 530035, so `--device-code` is only a fallback). Users who sign in to Microsoft Advertising with Google are not supported yet: an `MICROSOFT_ADS_NOT_AN_ACCOUNT_USER` error after a working sign-in means the Microsoft identity is not a user of the ad account; invite a Microsoft account or work (Entra) user and sign in as that user. `customer_id` is the manager account, `ad_account_id` the default ad account; `list_microsoft_ads_accounts` shows both.

| Tool | When to Use | Key Parameters |
|------|-------------|----------------|
| `list_microsoft_ads_accounts` | Discovery: the signed-in user, manager accounts, ad accounts (id, number, currency, time zone, status) | (none) |
| `get_microsoft_campaigns` | Budget (own or shared), bidding, languages, included/excluded locations and location intent | `include_targeting` |
| `get_microsoft_ad_groups` | Bid, network (search partners on/off), Audience Network exposure, dates, campaign status | `campaign_id` |
| `get_microsoft_keywords` | Match type, bid, status, editorial review, parent statuses | `campaign_id`, `ad_group_id` |
| `get_microsoft_ads` | Headlines (pins), descriptions, paths, final URLs, editorial review | `campaign_id`, `ad_group_id` |
| `get_microsoft_performance` | Spend, clicks, CTR, CPC, conversions, CPA, revenue, impression share and share lost to budget/rank | `level` (account/campaign/ad_group/keyword/ad), date range, `breakdown` (date/device), `campaign_id`, `compact` |
| `get_microsoft_search_terms` | What people searched, the keyword and match type it matched, waste candidates | date range, `campaign_id`, `min_clicks`, `compact` |
| `get_microsoft_location_performance` | Where clicks came from; people physically there vs searching about the place | date range, `group_by` (city/metro/state/postal_code/most_specific) |
| `get_microsoft_conversion_setup` | Audit: UET tag status, conversion goals (tracking status, excluded from bidding), campaign goals, clicks without conversions | date range, `min_clicks` |
| `update_microsoft_campaign_budget` | Draft a new daily budget (own budget only; capped by `max_daily_budget`) | `campaign_id`, `daily_budget` |
| `pause_microsoft_entity` / `enable_microsoft_entity` | Draft pausing or enabling a campaign, ad group, keyword or ad | `entity_type`, `entity_id`, `parent_id` (optional) |
| `search_microsoft_locations` | Location ids (country, state, metro, city, postal code) by name; Microsoft's file is cached | `query`, `location_type` |
| `update_microsoft_campaign` | Name, bid strategy (ManualCpc, EnhancedCpc, MaxClicks, MaxConversions + target CPA), tracking template, final URL suffix | `campaign_id` + fields |
| `update_microsoft_campaign_targeting` | Included / excluded locations (full lists), location intent, ad schedule (replaces; account time zone, or the searcher's when the campaign uses AdScheduleUseSearcherTimeZone: the preview's `hours_in` says which) | `campaign_id`, `location_ids`, `excluded_location_ids`, `location_intent`, `ad_schedule` |
| `draft_microsoft_campaign` | New Search campaign, paused, with budget, bidding, languages, locations, intent | `name`, `daily_budget`, `languages`, `location_ids` |
| `draft_microsoft_ad_group` / `update_microsoft_ad_group` | New ad group (with keywords) / name, default bid, network, Audience Network adjustment | `campaign_id` or `ad_group_id` + fields |
| `draft_microsoft_keywords` / `update_microsoft_keyword_bids` | Add keywords (duplicates skipped) / change keyword bids | `ad_group_id`, `keywords` or `bids` |
| `get_microsoft_negative_keywords` | Direct negatives and shared lists with items, attachments and `remove_id`s | `campaign_id` |
| `propose_microsoft_negative_keyword_list` / `add_to_microsoft_negative_keyword_list` | New shared list (attached) / append to a list | `list_name` or `list_id`, `keywords`, `campaign_ids` |
| `attach_microsoft_negative_keyword_list` / `detach_microsoft_negative_keyword_list` | Link or unlink a list and campaigns | `list_id`, `campaign_ids` |
| `add_microsoft_negative_keywords` | Negatives directly on a campaign or ad group | `campaign_id` or `ad_group_id`, `keywords` |
| `draft_microsoft_responsive_search_ad` / `update_microsoft_responsive_search_ad` | New RSA (paused) / replace headlines, descriptions, URL, paths | `ad_group_id` or `ad_id` + copy |
| `get_microsoft_ad_extensions` | Sitelinks, callouts, snippets, call and image extensions per ad group, campaign and account, with `remove_id`s (image rows add `alt_text`, `display_text`, `layouts`, `media_ids` and `images` with each picture's size and `url`, to look at a photo before unlinking it) | `campaign_id` |
| `draft_microsoft_sitelinks` / `draft_microsoft_callouts` / `draft_microsoft_structured_snippet` / `draft_microsoft_call_extension` | Create and link extensions to a campaign (or the account) | `campaign_id` or `scope="account"` + content |
| `draft_microsoft_image_extension` | Photos with the search ads: uploads up to 10 images to the media library, creates one image extension per image and links them | `campaign_id`, `ad_group_id` or `scope="account"`; `image_paths` / `image_urls` / `upload_ids`; `alt_text` (required, ≤35); optional `display_text` (≤35), `final_url` |
| `remove_microsoft_entity` | Delete (irreversible, double confirmation): campaign, ad group, ad, keyword, or by `remove_id` a negative, list item, criterion, extension link (account, campaign or ad group; unlinking keeps the extension) | `entity_type`, `entity_id` |

- **Statuses at every level.** Keyword and ad rows carry the ad group and campaign status; reports carry `campaign_status`, `ad_group_status`, `keyword_status`. An account whose status is not Active serves nothing; `BudgetPaused` campaigns stopped on budget.
- **Location intent matters for local businesses.** `PeopleInOrSearchingForOrViewingPages` (Microsoft's default) also reaches people elsewhere searching about the area. `get_microsoft_location_performance` shows how much spend that "location of interest" traffic took.
- **Monthly spend:** Microsoft may spend up to 30.4 × the daily budget in a month; the budget preview says so.
- **Writes** go through draft → preview → `confirm_and_apply`. Microsoft has no validate-only mode: the dry run re-reads the target, refuses if the budget or status changed since the draft or the campaign moved to a shared budget, and re-checks the cap. The real apply runs the same checks again right before sending, so a change made in Microsoft Advertising in between is refused, not overwritten: draft again. Updates send only the changed field.
- **Management rules** mirror Google Ads: broad match is refused unless the campaign uses conversion-based bidding (MaxConversions, MaxConversionValue, or a target CPA/ROAS; Maximize Clicks does not count), moving to any other strategy is refused while active broad keywords exist, MaxConversions is refused (at the draft and the dry run) while the account has no active conversion goal, because Microsoft refuses it then, new campaigns need languages (not `All`) and locations (default PeopleIn), new RSAs and campaigns are paused, while new keywords and ad groups are created Active as in Google Ads (the preview's `status_on_create` says so, and keywords in a live ad group serve as soon as they are applied), keyword and ad group bid raises are capped by `max_bid_increase_pct` (including a keyword falling back to the ad group bid), a first ad schedule needs a double confirmation. Replacing a schedule window deletes the old window before adding the new one when they overlap; the preview warns when that leaves the campaign briefly unscheduled. Negative keywords go in shared lists by default; every negative draft names active keywords it would block.
- **Multi-step applies** (a campaign then its targeting, a list then its attachments, extensions then their links) end with `PARTIAL_APPLY` when a later step fails, or when Microsoft creates some items of a batch and refuses others: `created` lists the IDs that exist, and the plan is retired so nothing is created twice. Check the account, then draft only what is missing.
- **Image extensions** (`draft_microsoft_image_extension`): JPEG, PNG or non-animated GIF, at most 5 MB, **1.91:1** (e.g. 1200x628), at least 703x368, at most 2592 wide and 2048 high; the draft refuses anything else and says how to crop it. Ask the user for alt text that describes the photo. Microsoft's help allows 25 image extensions per account, campaign or ad group, its API reference says 6: the draft warns above 6 and refuses above 25. `display_text` adds the multi-image layout, which needs at least five images in four extensions. **Caution:** image extensions can take search ads beyond Bing results: Microsoft's audience ads guide says search ads are extended to native placements on the Microsoft Audience Network (Outlook, MSN) with their image extensions, so check the ad groups' Audience Network setting with `get_microsoft_ad_groups` when the client wants search only. Images without a public URL go through `upload_images` first.
- Reports are built asynchronously and take a few seconds; long date ranges at keyword or search-term level take longer.
- **Rate limits:** Microsoft counts calls per customer in a sliding 60-second window (code 117) and caps concurrent reports (code 207). Both come back as `MICROSOFT_ADS_RATE_LIMITED` with `retry_after` 60: wait that long, never retry in a loop.
- **Removing a criterion** (`remove_microsoft_entity`, `campaign_criterion`) reads it first and names it; the last targeted location is refused, because the campaign would serve everywhere. Replace locations with `update_microsoft_campaign_targeting` instead.
- **Audience Network:** an ad group without its own `audience_ads_bid_adjustment` inherits the campaign's; -100 switches it off. `get_microsoft_ad_groups` shows the effective setting and where it is set (`audience_network`).
- Search terms with clicks and no conversions are candidates, not verdicts: calls from Microsoft ads convert outside its view unless call tracking feeds back.
- **Conversions** come from Microsoft's `ConversionsQualified` columns (the old `Conversions` columns are deprecated and read 0 in keyword and search-term reports); conversion rate and CPA are computed from them. A UET tag is required only by URL, duration, pages-per-visit and event goals: offline-import goals need none, and an unverified tag that no active goal uses is a loose end (warn), not a broken setup.

### When user asks about organic traffic, SEO, or paid/organic overlap

1. Call `list_gsc_sites` if no site is configured; confirm the property with the user
Expand Down Expand Up @@ -293,7 +340,7 @@ For images that have no public URL: a file on the user's computer, or an image t

- **With the card** (`upload: "card"` in the result): the user drops PNG, JPEG or GIF files (up to 5 MB) on the card; it then posts the upload ids into the chat. Wait for that message instead of asking for a URL.
- **With an upload link** (`upload_url`): give the user the link (valid 30 minutes) to open in the browser, then call `list_uploads` once they say they are done. A coding agent that has the file on disk can upload it itself: `curl -T "logo.png" "<upload_url>/"`, one call per file.
- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded.
- **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `draft_microsoft_image_extension(upload_ids=["up_..."])` for Microsoft Advertising; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded.
- Uploads expire after 24 hours. Self-hosted without a card, pass local files directly (`image_paths`).

### Offline Conversion Uploads
Expand Down Expand Up @@ -427,6 +474,8 @@ Same draft → preview → `confirm_and_apply` gate; the plan carries `platform:
- `require_dry_run: true` in config overrides `dry_run=false` — the user must change the config to allow real mutations.
- `two_phase_apply: true` in config (always on for AdLoop Cloud) refuses `dry_run=false` with status `DRY_RUN_REQUIRED` until that plan_id has completed one `dry_run=true` pass. Run the dry run, show the user, then apply — do not retry `dry_run=false` in a loop.
- All operations (including dry runs) are logged to `~/.adloop/audit.log`.
- `blocked_operations` is checked again by `confirm_and_apply`: a plan whose operation was blocked after it was drafted is refused with status `BLOCKED`, dry run and apply alike, and no confirmation dialog is shown for it.
- **`PARTIAL_APPLY` and `UNKNOWN_OUTCOME`** (platforms without transactional writes): `PARTIAL_APPLY` means part of the change is in the account (`created` names it), from a multi-step apply whose later step failed or a batch the platform accepted only in part; `UNKNOWN_OUTCOME` means the platform never answered a create, so it may or may not exist. In both cases the plan is retired and cannot be applied again: read the account back, tell the user what exists, and draft only what is missing.

## Safety Rules (CRITICAL — always follow)

Expand Down
Loading
Loading