# Amazon Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/amazon-ads Manage Amazon Ads with AI — 61 tools for Sponsored Products, Sponsored Brands, and Sponsored Display. Create campaigns by ASIN, track ACOS and ROAS, and find wasted spend. # Amazon Ads Integration Adspirer's newest ad platform brings Amazon advertising to your AI assistant. Create and manage Sponsored Products, Sponsored Brands, and Sponsored Display campaigns with 61 specialized tools. Build campaigns from your ASINs and SKUs, run AUTO or MANUAL keyword targeting, get Amazon-native bid and keyword recommendations, and track ACOS and ROAS — all from a conversation. Multi-region advertiser profiles (NA, EU, FE) are discovered and routed automatically, and every campaign is created PAUSED so you can review before it spends. ## Prerequisites > [!NOTE] > > * An Amazon Advertising account ([create one here](https://advertising.amazon.com)) > * Products listed on Amazon under a Seller or Vendor account > * Amazon Brand Registry — required for Sponsored Brands campaigns > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting Amazon Ads Adspirer connects to Amazon Ads through OAuth using Login with Amazon (LwA). Once you've set up Adspirer with your AI client, connect Amazon: 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my Amazon Ads account" 3. Adspirer opens your browser for Amazon authorization 4. Sign in with Login with Amazon and approve the requested permissions (read campaign data, create campaigns, manage budgets) 5. On connect, Adspirer imports each Amazon advertiser profile as an ad account — the first becomes active, and you can activate the others later Adspirer discovers advertiser profiles across all three Amazon regions (NA, EU, and FE) and routes requests to the correct one automatically. Tokens refresh server-side, and your credentials are never stored client-side. Verify the connection: ``` Check my connected ad platforms ``` You should see your Amazon advertiser profiles listed with profile name, account ID, region, and active status. To target a specific Amazon account, the assistant uses that profile's ID (`profile_id`) — find them anytime with `list_amazon_profiles`. > [!NOTE] > > There is no Amazon sandbox — campaigns run against production. To protect your spend, Adspirer creates everything PAUSED so you can review the campaign before launching it. ## What You Can Do (61 Tools) ### Accounts * `list_amazon_profiles` -- List your Amazon advertiser profiles across NA, EU, and FE, with profile IDs, regions, and active status * `list_amazon_brands` -- List the Brand Registry entities on a profile, with each brand's `brandEntityId` -- the value sellers must pass to create Sponsored Brands campaigns ### Campaign Management (SP + SB + SD) * `list_amazon_campaigns` -- List campaigns across Sponsored Products, Brands, and Display with status and budget * `create_amazon_sp_campaign` -- Create a Sponsored Products campaign (created PAUSED) * `create_amazon_sb_campaign` -- Create a Sponsored Brands campaign (created PAUSED) * `create_amazon_sd_campaign` -- Create a Sponsored Display campaign (created PAUSED) * `update_amazon_campaigns` -- Update name, budget, or bidding strategy across campaign types * `pause_amazon_campaigns` -- Pause one or more campaigns * `resume_amazon_campaigns` -- Resume paused campaigns * `delete_amazon_campaigns` -- Archive campaigns ### Sponsored Products Structure * `list_amazon_ad_groups` / `create_amazon_ad_groups` / `update_amazon_ad_groups` / `delete_amazon_ad_groups` -- Manage ad groups within Sponsored Products campaigns * `list_amazon_product_ads` / `add_amazon_product_ads` / `update_amazon_product_ads` / `delete_amazon_product_ads` -- Manage the product ads (your ASINs/SKUs) inside each ad group * `list_amazon_keywords` / `add_amazon_keywords` / `update_amazon_keywords` / `delete_amazon_keywords` -- Manage keywords for MANUAL targeting (bids, match types) * `list_amazon_negative_keywords` / `add_amazon_negative_keywords` / `delete_amazon_negative_keywords` -- Block irrelevant search terms to cut wasted spend * `list_amazon_targets` / `add_amazon_targets` / `update_amazon_targets` / `delete_amazon_targets` -- Manage product and category targeting ### Sponsored Brands Structure * `list_amazon_sb_ad_groups` -- List Sponsored Brands ad groups * `list_amazon_sb_ads` / `update_amazon_sb_ads` / `create_amazon_sb_ad` -- Manage Sponsored Brands ads across all 7 ad types (productCollection, video, brandVideo, storeSpotlight, autoCollection, manualCollection, productCollectionExtended) * `list_amazon_sb_creatives` / `update_amazon_sb_creative` -- Manage Sponsored Brands creative assets * `list_amazon_sb_keywords` / `add_amazon_sb_keywords` / `update_amazon_sb_keywords` / `delete_amazon_sb_keywords` -- Manage Sponsored Brands keywords * `add_amazon_sb_negative_keywords` -- Add negative keywords to Sponsored Brands campaigns * `list_amazon_sb_targets` / `add_amazon_sb_targets` / `update_amazon_sb_targets` -- Manage Sponsored Brands product and category targets * `add_amazon_sb_themes` -- Add theme-based targets to Sponsored Brands campaigns ### Creative Assets * `upload_amazon_asset` -- Upload a creative asset (for example a brand logo required by productCollection ads) * `search_amazon_assets` -- Find existing assets in your Amazon account library * `get_amazon_moderation` -- Read an ad's review status: APPROVED, IN\_PROGRESS, REJECTED, or FAILED, broken out per component (image, text, video). On a rejection you get the policy violation and what it objected to, instead of an ad that silently never runs. Works for Sponsored Products, Sponsored Display, and Sponsored Brands Find out why an Amazon ad isn't running. Check the moderation status of my Amazon ad and tell me if anything was rejected and why. > [!NOTE] > > **Sponsored Products ad extensions are console-only.** Amazon's Ads API accepts ad extensions for Sponsored Brands, Sponsored Display, and Amazon DSP, but not for Sponsored Products — those have to be created in the Amazon Ads console. Ask for one on a Sponsored Products campaign and Adspirer tells you that plainly rather than returning Amazon's cryptic `ACTION_NOT_SUPPORTED`. ### Recommendations & Budget Intelligence * `get_amazon_keyword_recommendations` -- Suggested Sponsored Products keywords for your ASINs * `get_amazon_bid_recommendations` -- Suggested Sponsored Products bids by keyword or target * `get_amazon_sb_keyword_recommendations` -- Suggested keywords for Sponsored Brands * `get_amazon_sb_bid_recommendations` -- Suggested bids for Sponsored Brands * `get_amazon_budget_recommendations` -- Recommended budget changes based on performance * `get_amazon_budget_usage` -- How much of each campaign's budget is being consumed ### Reporting & Analytics * `get_amazon_campaign_performance` -- Campaign metrics including impressions, clicks, spend, sales, ACOS, and ROAS * `get_amazon_search_terms` -- The actual search terms shoppers used to find your ads * `get_amazon_report` -- Retrieve an async Amazon report by report ID once it's ready ### Amazon-Specific Analytics * `analyze_amazon_wasted_spend` -- Find keywords and targets spending without converting * `optimize_amazon_budget` -- Budget reallocation recommendations based on ACOS and ROAS * `get_amazon_product_performance` -- Per-ASIN/SKU performance breakdown * `analyze_amazon_placements` -- Compare performance across placements (top of search, product pages, rest of search) * `analyze_amazon_targeting` -- Evaluate keyword and product targeting effectiveness * `get_amazon_purchased_products` -- Cross-sell view of what shoppers actually bought after clicking your ads ### Power Tool * `amazon_unified_api` -- Direct access to Amazon's Advertising API for advanced operations not covered by the dedicated tools above ### Large accounts: paging through long lists Accounts with thousands of product ads or a big asset library used to hit a wall — a long list would be cut off partway through, and the tail was simply unreachable. Three places now page properly: * **`list_amazon_product_ads`** returns a continuation token when there is more to fetch, so your assistant can keep going until the list is done. You can also narrow it up front by state or by ad group instead of paging through everything. * **`search_amazon_assets`** pages through the asset library rather than stopping at the first batch. * **`get_amazon_product_performance`** returns the page you asked for. It used to always render the top 20 no matter which page you requested, so ASIN 40 was invisible. Rows come back compact, which is what makes a long list survive the trip in one piece. **Reports stay inside the ad product you ask for.** Sponsored Products, Sponsored Brands, and Sponsored Display share one analytics store, and a Sponsored Brands campaign report used to come back with Sponsored Products and Display campaigns mixed in, plus account-wide totals. Campaign, search-term, targeting, product, ad-group, and placement reads now return only the product you requested. `ad_product` accepts `SP`, `SB`, `SD` or the full names, and anything else is rejected with an error instead of quietly defaulting to Sponsored Products. Reach past the first page of a large Amazon account. List every enabled product ad in my Amazon ad group, paging through all of them, then show me per-ASIN performance for the second page. ## Sponsored Products Creation Workflow Sponsored Products campaigns follow this workflow: ``` 1. get_connections_status ↓ (verify Amazon Ads is connected) 2. list_amazon_profiles ↓ (pick the advertiser profile / region to advertise under) 3. get_amazon_keyword_recommendations + get_amazon_bid_recommendations ↓ (find keywords for your ASINs and suggested bids) 4. create_amazon_sp_campaign ↓ (campaign created PAUSED — you review before launching) ``` A Sponsored Products campaign has a full structure underneath it: campaign → ad groups → product ads (your ASINs/SKUs) → keywords (AUTO or MANUAL targeting) → product/category targets → negative keywords. You can build all of it in one conversation or add to an existing campaign later. ## Example Prompts ### Check Performance Amazon campaign metrics with ACOS and ROAS. Pull my Amazon Ads performance for the last 30 days. Show impressions, clicks, spend, sales, ACOS, and ROAS. Which Sponsored Products campaigns have the lowest ACOS? ### Create a Sponsored Products Campaign Sponsored Products campaign by ASIN with keyword research. Create a Sponsored Products campaign for ASIN B08XXXXXXX: * Targeting: MANUAL keyword targeting * Budget: \$40/day * Get keyword and bid recommendations first * Add the top recommended keywords with suggested bids Build it PAUSED so I can review before launching. ### Find Wasted Spend ACOS-based wasted spend analysis with negative keyword suggestions. Analyze my Amazon Ads for wasted spend over the last 60 days. Which keywords are spending with no sales or a very high ACOS? Suggest negative keywords I should add. ### Launch a Sponsored Brands Campaign Sponsored Brands productCollection campaign with brand logo. Launch a Sponsored Brands campaign: * Ad type: productCollection * Feature ASINs: B08XXXXXXX, B09YYYYYYY, B07ZZZZZZZ * Brand logo: \[provide image URL or upload one] * Budget: \$75/day * Get Sponsored Brands keyword and bid recommendations first Create it PAUSED for review. ## ACOS, ROAS, and Amazon-Native Metrics Amazon reporting uses retail-specific metrics that differ from other ad platforms. Adspirer surfaces them directly: * **Impressions, clicks, CTR, spend** -- standard delivery metrics * **Purchases and sales** -- units ordered and attributed revenue * **ACOS (advertising cost of sales)** -- ad spend ÷ attributed sales, expressed as a percentage. Lower is better. ACOS is the metric most Amazon advertisers optimize toward. * **ROAS (return on ad spend)** -- attributed sales ÷ ad spend. ROAS is the inverse of ACOS: higher is better. * **Per-ASIN / per-SKU performance** -- see which products your ads are actually selling, not just campaign totals * **Cross-sell / purchased products** -- what shoppers bought after clicking, even if it wasn't the advertised ASIN The key difference from Google, Meta, TikTok, and LinkedIn: Amazon attributes sales of your actual products, so ACOS and ROAS are tied to real retail revenue rather than off-platform conversion events. Use `get_amazon_campaign_performance` for the rollup, `get_amazon_product_performance` for the per-ASIN view, and `get_amazon_purchased_products` for the cross-sell view. ### Reporting is asynchronous Amazon Reporting v3 generates reports asynchronously. Adspirer requests a report, then polls Amazon until it's ready, and `get_amazon_report` retrieves it by `report_id` once complete. For large date ranges, a report may still be processing when first requested — ask the assistant to check again in a moment, or pass the `report_id` to `get_amazon_report`. > [!TIP] > > **Analytics now serve instantly.** Adspirer keeps a nightly-refreshed analytics store of your Amazon performance, so the deeper analytics tools — wasted-spend detection, budget optimization, per-ASIN and purchased-products views, and targeting analysis — return **immediately** instead of waiting on a live Amazon report to generate. Point-in-time reports (`get_amazon_report`) still fetch fresh from Amazon when you need the very latest numbers. ## Sponsored Brands & Brand Registry > [!WARNING] > > Sponsored Brands campaigns require Amazon Brand Registry. Sellers supply a brand entity ID during creation -- read yours with `list_amazon_brands` -- and productCollection ads require a brand logo asset. Upload one with `upload_amazon_asset` (or reference an existing asset with `search_amazon_assets`) before creating the ad. If your brand isn't enrolled in Brand Registry, you can still run Sponsored Products and Sponsored Display campaigns. Sponsored Brands supports all 7 ad types — productCollection, video, brandVideo, storeSpotlight, autoCollection, manualCollection, and productCollectionExtended — plus a full creative asset pipeline and keyword, target, and theme management. ### Finding your brand entity ID Sellers need a `brandEntityId` to create a Sponsored Brands campaign, including SB video, and to register a creative asset. `list_amazon_brands` returns every Brand Registry entity on the profile with its `brandEntityId`, its `brandId`, and its registered name. Read the brand entity IDs on your Amazon profile. List my Amazon Brand Registry brands and show me the brand entity ID for each one Pass the `brandEntityId` -- the long value beginning `ENTITY` -- not the shorter `brandId` beside it. Each advertiser profile has its own, so a brand you sell under in more than one marketplace has a different ID per profile: ask against the profile you are about to advertise on. Vendor accounts can usually omit the field entirely. ## Best Use Cases for Amazon Ads * **Product launches:** Drive visibility for new ASINs that have no organic ranking yet * **Category capture:** Show up when shoppers search for your product category (high purchase intent) * **Brand defense and conquest:** Protect your branded search and target competitor products with Sponsored Display * **Best-seller scaling:** Pour budget into proven ASINs with strong ACOS to grow share * **Cross-sell and catalog depth:** Use purchased-products data to find which products to advertise together **Not ideal for:** B2B lead generation (use [LinkedIn Ads](/docs/ad-platforms/linkedin-ads)), products sold off Amazon or on your own store (use [Google Ads](/docs/ad-platforms/google-ads) or [Meta Ads](/docs/ad-platforms/meta-ads)), brand awareness to a younger consumer audience (use [TikTok Ads](/docs/ad-platforms/tiktok-ads)). ## Troubleshooting ### "Amazon account not connected" error Re-authenticate with Login with Amazon: ``` Connect my Amazon Ads account ``` If you manage multiple advertiser profiles, confirm the right one is active. List them with `list_amazon_profiles` and ask the assistant to switch to the correct `profile_id` (and region) before creating or pulling data. ### "Brand Registry required" error on Sponsored Brands Sponsored Brands campaigns need an enrolled brand. Make sure your brand is in Amazon Brand Registry and that you've supplied the brand entity ID -- run `list_amazon_brands` to read it off the profile. If it returns nothing, the brand is enrolled under a different profile: pass that `profile_id` and ask again. For productCollection ads, upload a brand logo with `upload_amazon_asset` first. If you don't have Brand Registry, run Sponsored Products or Sponsored Display instead. ### "Report still processing" / no report data yet Amazon reports are asynchronous (Reporting v3). The report is requested, then polled until Amazon finishes generating it. If a report isn't ready on the first try, wait a moment and retrieve it again with `get_amazon_report` using the `report_id`. Large date ranges take longer to generate. ### Campaign created but not spending This is expected. Adspirer creates every Amazon campaign PAUSED because campaigns run against production (there's no Amazon sandbox). Review the campaign, then ask the assistant to resume it with `resume_amazon_campaigns`. If you're using [agent skills](/docs/agent-skills/overview), the AI enforces the correct workflow automatically. ## FAQ > **How is Amazon Ads billed in Adspirer?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical Sponsored Products campaign creation uses a handful of tool calls (profiles, recommendations, create). See [full pricing](https://www.adspirer.com/pricing). > **Does Adspirer support multiple Amazon marketplaces and regions?** > > Yes. On connect, Adspirer discovers your advertiser profiles across all three Amazon regions — North America (NA), Europe (EU), and Far East (FE) — and routes requests to the correct region automatically. Each profile is imported as a separate ad account. Use `list_amazon_profiles` to see them and target a specific one by its `profile_id`. > **What's the difference between Sponsored Products, Sponsored Brands, and Sponsored Display?** > > **Sponsored Products (SP):** Keyword- and product-targeted ads that promote individual listings in search results and on product pages. The workhorse of Amazon advertising. No Brand Registry required. > > **Sponsored Brands (SB):** Brand-building ads (logo, custom headline, multiple products, or video) shown in prominent placements. Requires Amazon Brand Registry and supports all 7 ad types. > > **Sponsored Display (SD):** Audience and contextual targeting (audiences-remarketing plus contextual) shown on and off Amazon — strong for retargeting and competitor-product placements. > **Do I need Amazon Brand Registry?** > > Only for Sponsored Brands. Sponsored Products and Sponsored Display work without it. To run Sponsored Brands, enroll your brand in Brand Registry, supply the brand entity ID (`list_amazon_brands` reads it for you), and upload a brand logo with `upload_amazon_asset` for productCollection ads. > **Will Adspirer launch my Amazon campaigns automatically?** > > No. There is no Amazon sandbox, so campaigns run against production. Adspirer creates everything PAUSED so you can review it first. When you're ready, ask the assistant to resume the campaign with `resume_amazon_campaigns`. > **Is my Amazon advertising data secure?** > > Yes. Adspirer connects via OAuth through Login with Amazon — your Amazon credentials are never stored client-side. Tokens refresh server-side, and all connections are HTTPS-encrypted. You can revoke access at any time from your Amazon account's connected-apps settings. ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [TikTok Ads Integration](/docs/ad-platforms/tiktok-ads) * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) * [ChatGPT Ads Integration](/docs/ad-platforms/chatgpt-ads) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your Amazon Ads account (\$39 one-time) # ChatGPT Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/chatgpt-ads Run ads inside ChatGPT (OpenAI Ads) with AI — 50 tools to launch, target, manage, and measure chat_card ads from a conversation, all created paused. # ChatGPT Ads Integration Publish ads that appear **inside ChatGPT responses** as a **"chat card"** — a title, body, image, and click-through URL — and manage them conversationally from ChatGPT, Claude, or any supported AI client. ChatGPT Ads (OpenAI Ads) is a **pay-per-click** auction. Adspirer turns the launch, management, and measurement of these ads into plain-language requests across **50 tools**: describe the ad you want and the agent builds the campaign, ad group, image upload, and chat\_card ad for you — every object **created PAUSED** until you resume it. ## Prerequisites > [!NOTE] > > * An OpenAI Ads (Advertiser) account with an **Advertiser API key** (generated in OpenAI Ads Manager → Settings → API keys) > * Adspirer account connected via [ChatGPT](/docs/ai-clients/chatgpt), [Claude Code](/docs/ai-clients/claude-code), or any [supported AI client](https://www.adspirer.com/integrations) > * A **public image URL** (PNG or JPG) for the ad creative ## Connecting ChatGPT Ads ChatGPT Ads is the first Adspirer platform that connects with a **pasted API key** instead of an OAuth browser login. You connect **once in the Adspirer web app** — the chat agent never asks for your key. > [!NOTE] > > **One API key = exactly one ad account.** Unlike Google, Meta, TikTok, LinkedIn, and Amazon (which use an OAuth browser redirect and import several accounts at once), a ChatGPT Ads key maps to a single advertiser account. To manage more than one account, connect one key per account. 1. In OpenAI Ads Manager, go to **Settings → API keys** and generate (or copy) your **Advertiser API key** 2. Open the Adspirer web app and go to the **Connections** tab 3. Click **"Connect ChatGPT Ads"** 4. **Paste your Advertiser API key** and save — the key is stored **encrypted** Once connected, the account joins your Adspirer **multi-account switcher** and is usable from chat. Verify the connection from your AI assistant: ``` Check my connected ad platforms ``` You should see your ChatGPT Ads account listed with its name, account ID, and review status. ### Managing several ChatGPT Ads accounts Agencies and multi-brand advertisers can connect more than one ChatGPT Ads account. In the **Connections** tab, use **"Connect another account"** and paste that account's own Advertiser API key. Each account is disconnected on its own, so removing one leaves the rest alone. How many you can keep active at once depends on your plan — see [pricing](https://www.adspirer.com/pricing). From chat, nothing changes while you have a single account connected: every tool uses it automatically and you never pass an account ID. Once you have two or more, tell the agent which account you mean. Ask for `list_chatgpt_accounts` to see each one with its `account_id`, name, and currency, then name the account in your request. If a request is ambiguous, the agent comes back with the list of your accounts rather than guessing at one — pick the one you meant and it re-runs against it. See every connected ChatGPT Ads account with its ID and currency. List my ChatGPT Ads accounts with their account IDs and currencies, then show me last week's spend for the Northwind Retail one. ### Optional: Conversions step In the same Connect flow, set up conversion measurement (recommended). You can configure one or both: * **Client-side Pixel** — a small JS snippet you add to your site ``, configured with your **Pixel ID** * **Conversions API (server-side)** — paste a **Conversions API key** for more reliable attribution Supported events include `order_created`, `lead_created`, `subscription_created`, and `trial_started`. You can also configure and verify conversions from chat (see [Conversion Tracking](#conversion-tracking) below). ## What You Can Do (50 Tools) ChatGPT Ads is driven through Adspirer's conversational tools. Connecting and disconnecting are done in the web app, not via a chat tool — everything else is available from your AI assistant. ### Accounts * `list_chatgpt_accounts` -- Your connected ChatGPT Ads account(s), each with name, `account_id`, currency, and account review status ### Campaigns * `list_chatgpt_campaigns` / `get_chatgpt_campaign` -- List campaigns or get the full detail of one * `create_chatgpt_campaign` -- Create a campaign (created PAUSED), with a budget, a bidding type, and included/excluded locations * `update_chatgpt_campaign` -- Change budget, bidding, schedule, or targeting. Only the targeting side you name changes; the other is preserved * `pause_chatgpt_campaign` / `resume_chatgpt_campaign` -- Stop serving, or resume to go live * `archive_chatgpt_campaign` -- Archive a campaign. **Permanent** — asks you to confirm first ### Ad Groups * `list_chatgpt_ad_groups` / `get_chatgpt_ad_group` -- List ad groups or get one * `create_chatgpt_ad_group` -- Add an ad group (bid + targeting) to a campaign * `update_chatgpt_ad_group` -- Update bid, schedule, or targeting * `pause_chatgpt_ad_group` / `resume_chatgpt_ad_group` / `archive_chatgpt_ad_group` -- Control ad-group state. Archiving is **permanent** and asks you to confirm ### Ads * `list_chatgpt_ads` / `get_chatgpt_ad` -- List ads or get one * `create_chatgpt_ad` -- Create a chat\_card ad (title, body, image, destination URL) * `update_chatgpt_ad` -- Update an ad's creative * `pause_chatgpt_ad` / `resume_chatgpt_ad` / `archive_chatgpt_ad` -- Control ad state. Archiving is **permanent** and asks you to confirm ### Launch & Creative * `launch_chatgpt_ad` -- The one-shot orchestrator. Builds the whole **paused** ad in one step from URL + headline + body + image + budget + geo (creates the campaign, ad group, image upload, and chat\_card ad) * `upload_chatgpt_creative` -- Upload a chat\_card image from a public URL * `chatgpt_geo_lookup` -- Resolve a location like "California" to a valid targeting value (used for both included and excluded locations) ### Insights * `get_chatgpt_performance` -- Headline metrics: impressions, clicks, spend, CTR, CPC (plus conversions once the pixel/CAPI is live) * `get_chatgpt_insights` -- Scoped, detailed insights with selectable fields, filters, sort, pagination, and zero-impression rows * `get_chatgpt_conversion_insights` -- The conversion side of the funnel: conversions, click-through conversions, and view-through conversions, at account, campaign, ad-group, or ad level, optionally split by country or device ### Custom Audiences * `create_chatgpt_custom_audience` -- Build an audience, empty or seeded from an uploaded file * `list_chatgpt_custom_audiences` / `get_chatgpt_custom_audience` -- List audiences with their status and matched-user size range, or poll one until it's `ready` * `add_chatgpt_custom_audience_members` / `remove_chatgpt_custom_audience_members` -- Add or remove customer identifiers * `replace_chatgpt_custom_audience_members` -- Swap the entire membership from a file * `merge_chatgpt_custom_audiences` -- Combine 2–64 audiences into a new one * `list_chatgpt_custom_audience_operations` / `get_chatgpt_custom_audience_operation` -- Track the async work behind those changes * `resume_chatgpt_custom_audience_operation` / `cancel_chatgpt_custom_audience_operation` -- Restart or stop an add/remove in progress * `archive_chatgpt_custom_audience` -- Retire an audience. **Permanent** — asks you to confirm first ### Conversions * `set_chatgpt_conversions_config` / `get_chatgpt_conversions_config` -- Configure (or review) your Pixel and Conversions API setup * `list_chatgpt_conversion_events` -- See the conversion events being recorded * `test_chatgpt_conversion` -- Send a test conversion to confirm tracking works end to end * `send_chatgpt_conversion_event` -- Send a **real** server-side conversion with customer matching (see [Sending conversions from your own systems](#sending-conversions-from-your-own-systems)) ### Conversions Setup Create the measurement sources themselves without leaving the conversation. * `create_chatgpt_pixel` -- Create a web measurement pixel and get the ready-to-paste site snippet back * `list_chatgpt_pixels` -- List your pixels, each with its **Source ID** and short **Pixel ID** * `create_chatgpt_conversions_api_key` -- Create a server-side Conversions API key (shown once; saved encrypted so Adspirer can start sending events) * `create_chatgpt_event_setting` -- Tie a conversion event (`order_created`, `lead_created`, a custom event) to a pixel or Conversions API source * `list_chatgpt_event_settings` -- List your conversion event settings with their event type, source, and attribution window > [!NOTE] > > The object model (Account → Campaign → Ad Group → Ad) is hidden by the agent — you just describe the ad you want, and it builds the right structure. Budgets and bids are in **your account's own currency**, never micros — see [Budgets, bidding, and targeting](#budgets-bidding-and-targeting). ### Asking for a slice of a long list Every list tool — campaigns, ad groups, ads, pixels, event settings — takes a free-text search, a status filter, a sort by any field, a date range, and paging, so you can ask for what you want rather than reading back the whole account. Campaigns can also be filtered by bidding type. On ads, the free-text search covers the copy itself: title, body, and destination URL. The result says how many matched out of how many exist. A filter that matches nothing comes back as *0 of 41*, not as an empty account. Search ChatGPT Ads copy across an ad group. In my ChatGPT Ads spring campaign, show me the paused ads whose copy mentions "free trial", sorted by name. ## How a Launch Works Launching never spends money on its own. Everything is created **paused**, and you resume it when you're ready. **1. You describe the ad** "Run a ChatGPT ad for adspirer.com, \$25/day, target California, headline 'Your AI Paid Media Agent', body 'Run ads from ChatGPT', use this image: \[url]." **2. The agent builds everything — PAUSED** `launch_chatgpt_ad` resolves the location, creates the campaign + ad group, uploads the image from your URL, and builds the chat\_card ad. **Nothing serves or spends yet.** (Prefer step-by-step control? The agent can build the same tree with `create_chatgpt_campaign` → `create_chatgpt_ad_group` → `upload_chatgpt_creative` → `create_chatgpt_ad`.) **3. You review** Check the campaign, budget, and creative. The agent reports the ad's review status honestly — it never claims an ad is "live" while review is pending or rejected. **4. You resume to go live** On your say-so, `resume_chatgpt_campaign` takes it live — subject to OpenAI's review. Want to stop again? `pause_chatgpt_campaign`. ``` launch_chatgpt_ad → everything created PAUSED ↓ you review the budget + creative ↓ resume_chatgpt_campaign → live (pending review) ``` ## Budgets, Bidding, and Targeting ### Money is in your account's currency ChatGPT Ads accounts don't all bill in dollars — AUD, BRL, CAD, GBP, MXN, and NZD are all in use. Every budget and bid you give the agent is read as **your account's own currency**, never USD and never cents: ask for a budget of `25` and you get 25 a day in whatever currency the account bills in. `list_chatgpt_accounts` shows each account's currency. Create and update responses read the applied budget and bidding back to you in that currency, so you can confirm the number that landed rather than assume it. | Setting | Minimum | Maximum | | - | - | - | | **Daily budget** | 25 per day, in account currency | — | | **Lifetime budget** | 1, in account currency | — | | **Ad group max bid** | 0.000001, in account currency | 100, in account currency | > [!NOTE] > > OpenAI's floor for a **daily** budget is 25 a day, not 1. A smaller daily budget is caught before the request is sent, with your account's currency named in the message. ### Bidding type `create_chatgpt_campaign` and `update_chatgpt_campaign` take a `bidding_type`: | `bidding_type` | What it does | | - | - | | `clicks` | Pay per click (CPC). The Adspirer default | | `impressions` | Pay per thousand impressions (CPM). OpenAI's own default | | `conversions` | oCPC — optimizes toward the clicks most likely to convert, still billed per valid click | `conversions` needs **exactly one** conversion event to optimize toward, passed as `conversion_event_setting_ids`. Get the ID from `list_chatgpt_event_settings`, or create the event first with `create_chatgpt_event_setting` (see [Conversion Tracking](#conversion-tracking)). Ask for conversions bidding without one and the agent says so before sending the request. Move a ChatGPT Ads campaign onto conversions bidding. List my ChatGPT Ads conversion event settings, then switch my Spring Launch campaign to conversions bidding against the order\_created one. ### Ad-group bid strategy A campaign's `bidding_type` decides what you pay for. An ad group's **strategy** decides whether you set the bid or OpenAI does: | `strategy` | What it does | Max bid | | - | - | - | | `fixed_bid` | You set the bid. The default | Required | | `maximize_clicks` | Auto-bids for clicks. Needs a `clicks` campaign | Don't pass one | | `maximize_conversions` | Auto-bids for conversions. Needs a `conversions` campaign | Don't pass one | Strategy is settable when you create the ad group and changeable afterwards. Switching to a maximize strategy drops the manual bid; switching back to `fixed_bid` needs a new one. A strategy that doesn't match the campaign's bidding type is caught before the request is sent. Move a ChatGPT Ads ad group onto automatic bidding. Put my ChatGPT Ads ad group on maximize clicks instead of the fixed 1.20 bid, and confirm what OpenAI applied. ### Including and excluding locations Target places by name or by OpenAI location ID, and exclude them the same way: * `location_query` / `location_ids` — where the campaign **should** serve * `exclude_location_query` / `exclude_location_ids` — where it **shouldn't** Editing targeting only changes the side you name. Add an exclusion and your existing included locations stay exactly as they were. > [!WARNING] > > A location the agent can't resolve is treated as an **error**, not an empty list — a misspelled place name leaves your targeting untouched and tells you so. To genuinely serve everywhere, ask for targeting to be cleared; the agent uses `clear_targeting` rather than inferring it from an empty list. `update_chatgpt_campaign` also compares OpenAI's response against what you asked for and names any field OpenAI left at its previous value, so an edit that didn't take is never reported as done. Add a location exclusion without disturbing existing targeting. My ChatGPT Ads campaign targets California. Keep that, but exclude Los Angeles, and show me the targeting that ended up applied. ### Targeting your own customer list Upload a customer list as a **custom audience** and target it — or keep it out. Give the agent emails, phone numbers, already-hashed identifiers, or Google Advertising IDs inline, or point it at a file you've uploaded to OpenAI. Building and changing an audience is asynchronous. The tool hands back an operation to poll and the agent waits for the audience to reach `ready` rather than reporting a size it can't see yet. | What you're doing | What it needs | | - | - | | **Include** an audience in campaign targeting | Roughly 25,000 matched users or more | | **Exclude** an audience from campaign targeting | No minimum | | **Bid more or less** for an audience at ad-group level | Roughly 25,000 matched users or more | Per-audience bid adjustments run from **0.1× to 10×**, with 1× meaning no change — so you can pay up for your highest-value list without splitting the campaign. > [!WARNING] > > Audience size is reported as **OpenAI's matched-user range**, never an exact number, because OpenAI doesn't publish one. An audience can also come back `too_small` or `failed` instead of `ready`; the agent tells you which. Archiving an audience is **permanent**. Target an uploaded customer list and bid up for it. Create a ChatGPT Ads custom audience from this customer list, wait until it's ready, then target it in my Spring Launch campaign and bid 1.5x for it. ### Which ChatGPT surfaces you serve on Campaigns can be restricted to particular ChatGPT surfaces — `ios_app`, `android_app`, `ios_web`, `android_web`, `desktop_web`, `web` — instead of running everywhere. Leave it unset and the campaign serves on all of them. Surfaces are a fifth targeting side alongside included and excluded locations and included and excluded audiences, and the same rule holds for all five: **change one and the other four are left exactly as they were.** If the agent can't read your current targeting to merge a change into it, it says so rather than sending an edit that could wipe a side. ### Tagging your landing-page URLs Set a query string once on the campaign and it's appended to every landing page under it — no editing each ad's URL: ``` utm_source=chatgpt&utm_medium=cpc&utm_campaign={campaign_id} ``` `{campaign_id}`, `{ad_group_id}`, `{ad_id}`, and `{ad_account_id}` are filled in by OpenAI when the ad is served, so your analytics gets the real identifiers back. ## Example Prompts ### Launch an Ad Launch a ChatGPT chat\_card ad — created paused so you review before it goes live. Run a ChatGPT ad for adspirer.com. Budget: \$25/day, target California. Headline: "Your AI Paid Media Agent" Body: "Run ads from ChatGPT" Image: \[public PNG/JPG URL] Build it paused so I can review before resuming it. ### Check Performance ChatGPT Ads metrics for the week — impressions, clicks, spend, CTR, CPC. How's my ChatGPT ad doing this week? Show impressions, clicks, spend, CTR, and CPC. Include conversions if the pixel is live. ### Pause or Adjust Budget Pause a ChatGPT campaign or change its daily budget. Pause my ChatGPT campaign. Then bump the budget to \$50/day, but keep it paused until I resume it. ## Creative Requirements The ChatGPT ad renders as a single **chat\_card** — a title, body, image, and destination URL. | Field | Rule | | - | - | | **Title / headline** | 3–50 characters | | **Body** | Up to 100 characters | | **Image** | One image, supplied as a **public image URL** (PNG or JPG). Adspirer uploads from the URL — no binary file upload. **Square, at least 256×256 px** recommended | | **Destination URL** | Must be `http`/`https` | > [!WARNING] > > Provide a **public, reachable** image URL. Non-PNG/JPG files or unreachable URLs are **rejected up front**. Non-square or smaller-than-256px images produce a **warning** — they can still be rejected at review. ## Conversion Tracking Conversion measurement is optional but recommended. Set it up in the **Conversions step** of the Connect flow (see [Connecting ChatGPT Ads](#optional-conversions-step)), or configure and verify it from chat with `set_chatgpt_conversions_config` and `test_chatgpt_conversion`. You can use either or both methods: * **Client-side Pixel** — add a small JS snippet to your site ``, configured with your **Pixel ID** * **Conversions API (server-side)** — paste a **Conversions API key** for more reliable attribution Supported events: | Event | Meaning | | - | - | | `order_created` | A purchase or order was completed | | `lead_created` | A lead was captured | | `subscription_created` | A subscription started | | `trial_started` | A free trial began | Use `test_chatgpt_conversion` to fire a test event and confirm tracking works, then `list_chatgpt_conversion_events` to see what's being recorded. Once the pixel or Conversions API is live, conversions appear alongside impressions, clicks, spend, CTR, and CPC in `get_chatgpt_performance`. ### Creating the pixel and API key from chat You no longer need OpenAI Ads Manager to create the measurement sources — the agent can build them for you and hand back what you need. **1. Create the pixel** `create_chatgpt_pixel` creates a web measurement pixel and returns the **site snippet ready to paste** into your ``, plus two identifiers: a short **Pixel ID** for the snippet and Conversions API, and a **Source ID** (`cds_…`) you use in the next step. Automatic Advanced Matching — which hashes the customer details your site forms collect so more conversions match — is **on by default**; ask for it off if you'd rather opt out. **2. Add a Conversions API key (optional)** `create_chatgpt_conversions_api_key` creates a server-side key. **The secret is shown once and can never be retrieved again**, so copy it if you need it elsewhere. By default Adspirer stores it encrypted so it can start sending server-side conversions immediately. **3. Define what counts as a conversion** `create_chatgpt_event_setting` ties an event — `order_created`, `lead_created`, one of the other supported types, or a custom event of your own — to a pixel or Conversions API source, with an attribution window (OpenAI recommends 30 days). `list_chatgpt_event_settings` shows what you've defined. > [!WARNING] > > **Pixels, Conversions API keys, and event settings are permanent.** OpenAI provides no way to delete them, so the agent asks you to confirm before creating one, and it will not replace a pixel or key you already have unless you explicitly tell it to. ### Sending conversions from your own systems With a Pixel ID and a Conversions API key in place, `send_chatgpt_conversion_event` posts a real conversion server-side — the path that survives ad blockers and cross-device journeys the pixel misses. Send an `order_created`, `lead_created`, or any configured event type with its value, currency, and an order or event id so OpenAI can de-duplicate it against the pixel. Advanced matching raises how many of those conversions OpenAI can tie back to an ad. You can pass email addresses, phone numbers, names, external ids, country, city, region, postal code, IP, user agent, and Google Advertising ID. > [!NOTE] > > **Raw customer details are hashed before they leave the tool.** Emails, phone numbers, and names are SHA-256 hashed at the point of the call, so the plain values never reach Adspirer's backend and are never written to your tool-call history. The response tells you which match keys were included, never the values. You can also pass identifiers you've already hashed yourself. Values are whole minor units — 2599 for \$25.99 — and a decimal is rejected rather than quietly truncated. Set a dry run with `validate_only` to check the event is accepted before sending anything real. Once conversions are flowing, `get_chatgpt_conversion_insights` reports them by campaign, ad group, or ad, split by country or device if you ask. **View-through conversions are reported on their own line and never folded into the total** — a 1-day window, kept separate so a view isn't counted as a click. Send a server-side conversion with customer matching. Send a ChatGPT Ads order\_created conversion for order 10482, 84.50 USD, with this customer's email and postal code, and dry-run it first. ## Ad Review and Policy > [!WARNING] > > Every ad — and the **account** itself — must pass **OpenAI's review** before it can serve. OpenAI's ad policies **disallow some categories**, notably **"third-party AI services"**, so AI-company advertisers should expect extra scrutiny. The agent reports the review status (`in_review` → `approved`/`rejected`) **honestly** — it will not tell you an ad is "live" while review is pending or rejected. ## Safety Guardrails These are built into the tools, not optional settings: * **Everything is created PAUSED.** Nothing serves or spends until you resume it with `resume_chatgpt_campaign`. * **The agent speaks in your account's currency,** never micros, and reads the applied budget back to you after a create or update. * **Archiving asks first.** OpenAI has no un-archive endpoint, so `archive_chatgpt_campaign`, `archive_chatgpt_ad_group`, `archive_chatgpt_ad`, and `archive_chatgpt_custom_audience` require an explicit confirmation — and the agent offers pausing instead when that's what you meant. * **Targeting edits never widen your reach by accident.** A campaign has five targeting sides — included and excluded locations, included and excluded audiences, and surfaces — and changing one preserves the other four. An unresolvable location leaves targeting untouched rather than clearing it, and an edit the agent can't safely merge is refused rather than guessed. * **Customer details are hashed before they leave the tool.** Emails, phone numbers, and names passed to `send_chatgpt_conversion_event` are SHA-256 hashed at the point of the call and never written to your tool-call history. * **Review status is reported honestly** — no false "live" claims while review is pending or rejected. An update that OpenAI silently ignored is reported as ignored, not as applied. ## Best Use Cases for ChatGPT Ads * **Reaching people inside ChatGPT** — put your offer in front of users at the moment they're asking an AI for help * **Simple, single-card creative** — one headline, one short body line, one image, one link; no video production required * **Pay-per-click testing** — start at OpenAI's 25-a-day daily minimum, review before you resume, and read CTR/CPC before scaling **Not ideal for:** rich multi-format creative (use [Meta Ads](/docs/ad-platforms/meta-ads) for image/video/carousel), high-intent search capture (use [Google Ads](/docs/ad-platforms/google-ads)), or categories OpenAI's policies disallow (e.g. third-party AI services). ## Troubleshooting ### "Not connected" — ChatGPT Ads doesn't appear ChatGPT Ads is connected in the **web app**, not from chat. Open the Adspirer web app → **Connections** tab → **"Connect ChatGPT Ads"** and paste your Advertiser API key. Then ask your assistant to "Check my connected ad platforms." ### "Invalid API key" The pasted key is wrong, revoked, or for the wrong account. Generate a fresh Advertiser API key in **OpenAI Ads Manager → Settings → API keys**, then re-paste it in the Connections tab. Remember: **one key = one ad account**. ### Ad stuck in review OpenAI reviews both the account and each ad before it can serve. `in_review` is normal for new ads and accounts. AI-related advertisers face extra scrutiny — if the ad is `rejected`, the category may be disallowed (see [Ad Review and Policy](#ad-review-and-policy)). Use `list_chatgpt_accounts` to check the account review status. ### A budget change didn't take effect Budget updates on ChatGPT Ads campaigns used to report success without changing anything — the value reached OpenAI in the wrong shape and was discarded. That's fixed. If a campaign has been spending at an old rate since you changed it from chat, check the current budget with `get_chatgpt_campaign` and set it again; the response now reads back the budget that actually applied. ### Image rejected Make the image **square and at least 256×256 px**, in **PNG or JPG**, served from a **public, reachable URL**. Non-PNG/JPG files and unreachable URLs are rejected up front; non-square or undersized images warn and may be rejected at review. ## FAQ > **Why do I paste a key instead of logging in?** > > ChatGPT Ads (OpenAI Ads) authenticates with an **Advertiser API key**, not an OAuth browser redirect like Google, Meta, TikTok, LinkedIn, and Amazon. You paste the key once in the Adspirer web app's Connections tab; it's stored encrypted and the chat agent never asks for it. One key maps to exactly one ad account. > **Can I connect more than one ChatGPT Ads account?** > > Yes. Because a ChatGPT Ads key maps to one advertiser account, several accounts means several keys — add each with **"Connect another account"** in the Connections tab, and disconnect them one at a time. How many you can keep active at once depends on your plan; see [pricing](https://www.adspirer.com/pricing). > > With one account connected, tools use it automatically. With two or more, name the account you mean in your request — `list_chatgpt_accounts` shows each one's `account_id`, name, and currency. Leave it ambiguous and the agent replies with your account list instead of picking one for you. > **Can Adspirer create my ChatGPT Ads pixel for me?** > > Yes. `create_chatgpt_pixel` creates the pixel and returns the site snippet ready to paste into your ``, so you don't have to open OpenAI Ads Manager. `create_chatgpt_conversions_api_key` does the same for server-side tracking, and `create_chatgpt_event_setting` defines what counts as a conversion. > > All three create something **permanent** — OpenAI has no delete endpoint for them — so the agent confirms with you first and won't overwrite a pixel or key you already have unless you tell it to. A Conversions API key's secret is shown **once** and can't be retrieved again. > **How is ChatGPT Ads billed in Adspirer?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49–150/mo. Pro: $99–600/mo. Max: \$199–3,000/mo. Launching a ChatGPT ad uses a handful of tool calls. Your ad spend is billed separately by OpenAI. See [full pricing](https://www.adspirer.com/pricing). > **Can the agent spend money without my approval?** > > No. Everything is created **PAUSED** — nothing serves or spends until you resume it with `resume_chatgpt_campaign`. The agent always speaks in your account's own currency (not micros) and reads the applied budget back to you, so the number is clear before you go live, and you can `pause_chatgpt_campaign` at any time. Archiving — the one irreversible action, since OpenAI has no un-archive — needs an explicit confirmation of its own. > **What image do I need?** > > One image, supplied as a **public PNG or JPG URL** — Adspirer uploads it from the URL (no file upload). **Square, at least 256×256 px** is recommended. Non-square or smaller images produce a warning and may be rejected at review; non-PNG/JPG or unreachable URLs are rejected up front. > **Is my ChatGPT Ads API key secure?** > > Yes. Your Advertiser API key is stored **encrypted** in the Adspirer web app and is never exposed to the chat agent. All connections are HTTPS-encrypted. You can disconnect the account from the Connections tab at any time, and you can revoke the key from OpenAI Ads Manager. > **What metrics can I see?** > > `get_chatgpt_performance` reports impressions, clicks, spend, CTR, and CPC. `get_chatgpt_insights` gives a scoped, detailed view with selectable fields, filters, sort, and pagination. Once you've configured the client-side Pixel or the Conversions API, conversions (`order_created`, `lead_created`, `subscription_created`, `trial_started`) appear alongside those metrics. ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) * [ChatGPT Setup](/docs/ai-clients/chatgpt) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [Pricing & Plans](https://www.adspirer.com/pricing) # Google Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/google-ads Manage Google Search, Performance Max, Shopping, App, Display, YouTube, and Demand Gen campaigns with AI — 156 tools for keywords, ad copy, and optimization. # Google Ads Integration The most comprehensive ad platform integration. Create Search, Performance Max, Shopping, App, Display, YouTube, and Demand Gen campaigns, research keywords with real CPC data, generate ad copy, and optimize performance with 156 specialized tools — including Manager-parity deep management down to the ad-group, asset-group, and product-partition level. > [!NOTE] > > **Approved at the agency level for the Google Ads API.** Google classified Adspirer as an agency, full-service ad platform and granted Standard Access — so there's **no daily cap** on the work Adspirer can do on Google. Bulk builds, large restructures, and account-wide optimization run at full speed. [Google Ads + Claude: Instant Clarity with Adspirer](https://www.youtube.com/embed/xf4mRLs1VR8) Google Ads + Claude: Instant Clarity with Adspirer ## Prerequisites > [!NOTE] > > * Google Ads account ([create one here](https://ads.google.com)) > * An active ad account with billing information > * Admin or Standard access to the account you want to manage > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting Google Ads For a full walkthrough with screenshots and example prompts, see [How to Connect ChatGPT to Google Ads](https://www.adspirer.com/blog/connect-chatgpt-google-ads) or [How to Connect Claude to Google Ads](https://www.adspirer.com/blog/connect-claude-google-ads). Once you've set up Adspirer with your AI client, connect Google Ads: 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my Google Ads account" 3. Adspirer opens your browser for OAuth authorization 4. Sign in to your Google account and select the ad account you want to manage 5. Approve permissions (read campaign data, create ads, manage budgets) Verify the connection: ``` Check my connected ad platforms ``` You should see your Google Ads account listed with account name, customer ID, and active status. > [!TIP] > > **Connect multiple Google logins to one Adspirer account.** Agencies and consultants managing Google Ads across separate Google identities can attach multiple Google OAuth grants to a single Adspirer account. Each grant contributes its own non-overlapping customer IDs; the agent transparently routes tool calls to the right OAuth based on the customer you reference. Add a second login from **Connections → Google Ads → Add another Google login**. Available on **Max annual** today; rolling to other paid tiers behind a feature flag. See [Multi-Account](/docs/knowledge-base/multi-account) for details. ### If an account is greyed out An account you have access to but that Google hasn't activated — billing never set up, or the account deactivated — appears in the picker as a greyed-out row you can't select, with the reason shown alongside it. This is not a connection problem and reconnecting won't clear it: activate the account in [Google Ads](https://ads.google.com), then reopen the picker and it becomes selectable. A greyed row shows the account number and the reason only. Currency and time zone are omitted, because the lookup that would have supplied them is the one that failed. Accounts that are active are never greyed out. If a check against Google fails temporarily, the account stays selectable rather than being locked. ## What You Can Do (156 Tools) ### Performance Analysis * `get_campaign_performance` -- Pull metrics for campaigns (spend, conversions, CPA, ROAS) * `get_ad_performance` -- Per-ad performance breakdown (one row per ad): impressions, clicks, CTR, cost, conversions, conversion value, CPC, CPA, ROAS, video views, ad strength, and an is-live flag — with a head-to-head comparison when an ad group has multiple ads. Covers Search, Display, Demand Gen, and YouTube. * `analyze_wasted_spend` -- Find keywords with spend but zero conversions * `analyze_search_terms` -- Review actual search queries triggering your ads. Supports `raw_report` mode to see the exact search terms users type into Google. Covers Search and Shopping — for a Performance Max campaign use `analyze_pmax_search_terms` instead. * `analyze_pmax_search_terms` -- Per-term search queries a Performance Max campaign matched, with cost, clicks, impressions, conversions, conversion value, CTR, and CPC * `analyze_pmax_search_categories` -- The same demand grouped into Google's search categories, so you can read the themes rather than ten thousand individual queries * `explain_performance_anomaly` -- Diagnose sudden CPA spikes or CTR drops * `optimize_budget_allocation` -- Recommend budget shifts based on ROAS/CPA ### Keyword Research * `research_keywords` -- Find keywords with real CPC data from Google Keyword Planner (search volume, competition, estimated bids) **Researching a city or a small region returns keywords.** Keyword Planner scopes search volume to the area you target, so a city's volumes are a fraction of a country's. A fixed minimum-volume filter used to remove every result on those targets and then report an empty result as though Google had found nothing. The filter can no longer empty a list that had something in it: where it would remove everything, the **top 20 keywords by volume** are kept and labelled as low volume, so you get the ideas and can judge the volumes yourself. When the result genuinely is empty, the message says who emptied it. "Google Keyword Planner returned nothing" now means exactly that; if Adspirer filtered the ideas out, you are told what was removed — near-duplicates and junk phrases, or keywords below the volume floor — rather than being pointed at Google. ### Ad Copy & Content * `suggest_ad_content` -- Generate headlines and descriptions optimized for Google's character limits * `get_ad_creative` -- Export the creative composition of existing ads: YouTube video IDs and watch/thumbnail URLs, downloadable image URLs (with role + dimensions), every headline/description/business name/CTA, and carousel cards. Covers Demand Gen, Responsive Search, and Responsive Display ads. * `help_user_upload` -- Guide users through the asset upload process ### Campaign Creation * `discover_existing_assets` -- Browse the account's complete asset inventory (images, headlines, descriptions, sitelinks, videos), now paginated across all asset types so nothing is silently capped, with downloadable image URLs and a clear forward path when a square logo is missing * `validate_and_prepare_assets` -- Verify assets meet Google's requirements before campaign creation * `create_search_campaign` -- Launch Google Search campaigns (text ads on search results, created PAUSED) * `create_pmax_campaign` -- Launch Performance Max campaigns (ads across all Google channels, created PAUSED) ### PMax Search Themes & Audience Signals * `add_pmax_search_themes` -- Add search themes to guide PMax targeting (max 50 per asset group) * `get_pmax_search_themes` -- View current search themes on a PMax campaign * `remove_pmax_search_themes` -- Remove specific search themes * `add_pmax_audience_signal` -- Add audience signal combining in-market, affinity, custom audiences, and user lists * `get_pmax_audience_signals` -- View current audience signals * `remove_pmax_audience_signal` -- Remove an audience signal * `search_audiences` -- Search for audiences by keyword across all types ### PMax search terms Ask for the search terms on a Performance Max campaign and you used to get **"No search term data"** — Google keeps PMax queries in a different place than Search and Shopping queries, and `analyze_search_terms` only reads the latter. Two tools read the PMax side. * `analyze_pmax_search_terms` -- Every query the campaign matched, one row each: cost, clicks, impressions, conversions, conversion value, CTR, CPC. Sorted by cost by default, so the highest-spending queries are the ones you see first * `analyze_pmax_search_categories` -- Google's own grouping of those queries into search categories, with clicks, impressions, conversions, and conversion value per category. Google returns an **(Other search terms)** bucket for the long tail it doesn't categorize Both take a `campaign_id` and a `lookback_days` window of 7, 30, 60, 90, or 120 (default 30). Money comes back in your ad account's own currency. A PMax campaign can match thousands of queries, so neither tool expects you to read them all. `analyze_pmax_search_terms` opens with a **summary across the whole window** — how many terms, total cost, total conversions, and how many terms recorded no conversions along with what they cost. Those are the facts, not a verdict: a query with no conversions may be upper-funnel or tracked somewhere else, and you decide which. To narrow it, filter or re-rank rather than paging. `query` is a case-insensitive substring match on the term, `sort_by` takes `cost`, `clicks`, `impressions`, `conversions`, `conversion_value`, `ctr`, or `cpc` (categories sort on impressions, clicks, conversions, or conversion value), and `sort_order` flips the direction. Paging is deliberately capped near the top of the ranking — you can't walk deep into a ten-thousand-term result. Find the queries a PMax campaign is paying for. Show me the search terms my Performance Max campaign spent on over the last 60 days, then break the same period down by search category. ### PMax Brand Guidelines Brand Guidelines is Google's brand-controlled PMax layout. With it on, Google requires the square logo and business name on the **campaign** rather than on the asset group, and the campaign cannot serve without them: * `create_pmax_campaign` with `brand_guidelines_enabled` -- Turn Brand Guidelines on and link the logo and business name at the campaign level in the same call. Create-time only; Google does not allow the setting to change afterwards * `add_pmax_campaign_logo` -- Link a square logo to an existing campaign, by `asset_id` from your account's library or by image URL, with an optional `business_name` (max 25 characters) attached in the same call. Skips a logo that is already linked * `get_pmax_conversion_goals` -- Read a campaign's conversion goals: each goal's category, origin, and whether it is biddable Removing or pausing a logo, landscape logo, or business name on a Brand Guidelines campaign is refused, because the campaign would stop serving without it. To swap one, add the replacement first and then remove the old asset. ### Campaign Management * `update_campaign` -- Change the daily budget, or update campaign settings: language targeting, locations, Search Partners, Display Expansion, audience targeting mode (OBSERVATION / TARGETING), AI Max * `pause_campaign` -- Stop a campaign * `resume_campaign` -- Restart a paused campaign * `pause_ad_group` -- Pause an individual ad group within a campaign * `resume_ad_group` -- Resume a paused ad group * `add_negative_keywords` -- Block irrelevant search terms from triggering your ads * `list_negative_keyword_lists` -- List the account's shared negative keyword lists, each with its keyword count and how many campaigns it's attached to * `get_negative_keyword_list` -- Read the keywords inside one list, with their match types * `create_negative_keyword_list` -- Create a new, empty shared list * `add_negative_keywords_to_list` -- Add negative keywords to a shared list, each with a match type * `attach_negative_keyword_list_to_campaign` -- Attach a shared list to a campaign * `bulk_update_keyword_status` -- Pause or re-enable up to 300 keywords in one ad group in a single call. Takes explicit keyword IDs (there is no pause-everything mode), works in both directions, and is safe to re-run — a keyword already in the target status is left alone. Use this instead of `remove_keywords` when you want keywords stopped rather than deleted. * `bulk_update_ad_status` -- Pause or enable any number of ads in one ad group in a single call. Takes `ad_group_id`, explicit `ad_ids`, and `PAUSED` or `ENABLED`; get the IDs from `get_campaign_structure` or `get_ad_performance`. One call per ad group — to sweep several, make one call each * `bulk_update_ad_group_status` -- Pause or enable any number of ad groups in a single call, on any campaign type (Search, Performance Max, Display, Demand Gen). Pass `campaign_id` as well and each ad group is checked to belong to that campaign, so an ID from a different campaign is reported as not found rather than changed * `bulk_update_campaign_status` -- Pause or enable any number of campaigns in a single call, from a list of campaign IDs > [!NOTE] > > **How the three bulk status tools behave.** There is no cap on how many IDs you pass. They set status and never remove anything, so re-running with the opposite status undoes the change. An entity already in the target status is skipped rather than rewritten; an ID that isn't in the ad group or campaign you named comes back as not found; and a removed entity can't be re-enabled, because Google has no route back from removed. > > Every change is **read back from Google after the write**. Anything that didn't actually land is moved into the failure list with the reason, so a mutation Google swallowed is never reported as a success. Enabling campaigns can start real spend — Adspirer asks you to confirm before it does. * `update_bid_strategy` -- Change a campaign's bidding strategy (Maximize Conversions, Target CPA, Target ROAS, Maximize Clicks, Target Impression Share). Detects shared **portfolio** bid strategies and explains how to change them; surfaces Smart Bidding prerequisites when conversion data is missing. On App campaigns it checks the strategy against the campaign's App bidding goal before calling Google, and names the strategy that goal requires instead of returning Google's "incompatible with the goal type" error. * **Max CPC ceiling.** `cpc_bid_ceiling` caps what a strategy will pay for a click, on **Maximize Clicks** and **Target Impression Share** -- the only two strategies Google gives a max-CPC field. Pass it in the account's own currency as a decimal (`8` for a CA\$8.00 cap, not cents, not USD). Omit it and any existing ceiling is left untouched; pass it on a strategy that has no such field and the call is refused up front rather than silently dropping the cap. The response shows the ceiling **read back from Google** after the write, so "not set" means the cap is genuinely absent rather than an echo of what you sent. `list_campaigns` and `get_campaign_structure` report the ceiling and the strategy it sits on. * `add_business_name_asset` -- Attach a business name asset to a Search campaign (max 25 characters). Skips the write if the same name is already on the campaign * `add_call_asset` -- Attach a phone number call asset with optional call conversion tracking. Skips the write if the same number is already on the campaign * `add_search_campaign_image` -- Attach image assets to Search campaigns (logos, marketing images). Skips the write if the same image is already linked under that field type * `get_campaign_targeting` -- View targeting for existing campaigns: locations, languages, audiences, devices, ad schedules, topics, and content labels (all criterion types). Locations come back as place names rather than Google's raw criterion IDs -- `Australia | Country | 2036`, not `geoTargetConstants/2036` -- for excluded locations as well as targeted ones. Radius targets show the full address and units rather than just a country code, and the Proximity and Locations tables carry a Criterion ID column. Targeting reads refresh within a minute, and any targeting change you make shows on the next read > [!NOTE] > > **Search campaigns lose campaign-level language targeting in late September 2026.** Google is retiring the setting — Search ads will match on the language of the ad itself instead. Performance Max keeps it, and reading a campaign's existing language criteria still works everywhere. > > Until Google's cutover, setting languages on a Search campaign through `update_campaign` works exactly as it does today. After it, Adspirer tells you plainly that Google no longer accepts the change rather than returning a bare failure — and it never records languages as applied when they weren't. If you asked for a language change and nothing else in the same call, you get that explanation instead of a success message. Campaign reads report a target CPA or target ROAS whichever way Google stores it, and say which. A bare **Target CPA** is a standalone bid strategy; **Target CPA (target on Maximize Conversions)** is a ceiling sitting on a maximize strategy. The two behave differently, so the readback names the shape rather than just the number. **Target Impression Share** bids for visibility rather than for a cost or return target. You choose where to appear — absolute top of page, top of page, or anywhere on the page — and the share of auctions you want to win there, from 1 to 100. Set a **max CPC ceiling** with it: without a ceiling, a high target keeps bidding up to reach the number. The ceiling is a plain amount in the ad account's own currency, so a €4 ceiling is `4`. Every bid strategy change is **read back from Google after it's written**. If the campaign isn't on the strategy you asked for, you get an error saying so rather than a success message. Strategy changes take one to two weeks to settle, so a false success used to cost a lot of time before anyone noticed. ### Shared negative keyword lists `add_negative_keywords` blocks a search term on **one** campaign. A shared negative keyword list is the reusable version: build the list once, attach it to as many campaigns as you like, and every campaign it's attached to blocks the whole set. Add a term to the list later and it takes effect everywhere at once — which is how most accounts handle a standing brand-safety or job-seeker block list. The five tools cover the full life of a list: `list_negative_keyword_lists` and `get_negative_keyword_list` to see what you have, `create_negative_keyword_list` to start an empty one, `add_negative_keywords_to_list` to fill it, and `attach_negative_keyword_list_to_campaign` to put it to work. Each keyword carries a match type — `EXACT`, `PHRASE`, or `BROAD`, defaulting to `BROAD`. Attaching a list doesn't move the keywords into the campaign, so detaching later leaves the list intact for everything else using it. Build a block list once and reuse it. Create a Google Ads negative keyword list called "Job seekers", add "careers", "jobs" and "salary" as phrase match, then attach it to all my Search campaigns. ### Ad Extensions (Assets) Sitelinks, callouts, structured snippets, and call assets each have full add / remove / list coverage. Ask for "extensions" or "ways to make my ads better" and Adspirer suggests sitelinks first (the highest-impact extension) — you don't have to know the term. * `add_sitelinks` -- Add sitelink extensions. Accepts natural field names — `text` or `headline` for the label, `url` or `link` for the destination. * `remove_sitelinks` -- Remove sitelink extensions from a campaign * `add_callout_extensions` -- Add callout extensions (short promotional blurbs, max 25 characters each) * `remove_callouts` -- Remove callout extensions from a campaign * `add_structured_snippets` -- Add structured snippet extensions (a header like "Brands" or "Styles" plus values) * `remove_structured_snippets` -- Remove structured snippet extensions from a campaign (clear out stale values before adding fresh ones) * `list_call_assets` -- List every phone number on a campaign with its country code, status, and the asset ID you need to pause or remove it * `set_call_asset_status` -- Pause a phone number so it stops showing, or re-enable it, without unlinking anything. Name specific asset IDs, or omit them to change every call asset on the campaign * `remove_call_assets` -- Unlink phone numbers from a campaign. The asset stays in your Asset Library and can be re-linked elsewhere. Omit the asset IDs to unlink all of them * `list_campaign_extensions` -- List every extension serving on a campaign — sitelinks, callouts, structured snippets, call assets, business names, and images — each with its status and the level it is attached at **Extensions are read at all three levels.** Google lets you attach an extension asset to the **account**, the **campaign**, or an **ad group**, and an ad-group sitelink serves just as much as a campaign one. `list_campaign_extensions` and the Extensions block of `get_campaign_structure` read all three and label each asset with where it lives, so a campaign whose sitelinks are attached to its ad groups reads *"16 at ad-group level -- these serve"* rather than **Sitelinks (0)**. **"None configured at any level"** means all three are genuinely empty — the one case where adding a sitelink is the right move. > [!WARNING] > > If you checked a campaign's extensions before **September 11, 2026** and were told it had none, check again. Only campaign level was being read, so anything attached to an ad group or to the account was invisible, and the answer came back as a flat zero rather than as "not found at this level". **Adding the same asset twice no longer creates a duplicate.** Google stores a call asset's phone number verbatim and never deduplicates it, so re-running `add_call_asset` with a number already on the campaign used to stack a second identical phone extension. `add_call_asset`, `add_business_name_asset`, and `add_search_campaign_image` now check the campaign first and skip the write when the asset is already there, saying so instead of reporting a second success. Pass `force=true` when a genuine duplicate is what you want. ### Placements, Reach & Policy * `get_placement_performance` -- Where your Display, Demand Gen, Video and Smart ads actually ran -- websites, YouTube channels and videos, apps -- with cost and conversions per placement, including automatic placements Google chose. Filter by placement type, minimum cost, or zero-conversion placements only * `add_placement_exclusions` -- Stop serving on specific websites, YouTube channels, videos or apps by adding negative placements to a whole campaign or a single ad group. Nothing is paused or deleted * `get_reach_frequency` -- Unique users reached and average impressions per user for each campaign, the signal for creative fatigue on YouTube, Demand Gen and Video * `get_ad_policy_violations` -- The approval and review status of your ads, with the exact policy topics behind a disapproval or limit ### Ad Group Controls & Targeting * `add_search_ad_group` -- Add a new ad group to an existing Search campaign, optionally seeded with keywords, a Responsive Search Ad, and a manual CPC bid * `create_ad` -- Add a new Responsive Search Ad to an existing ad group to test different messaging * `get_ad_group_settings` / `update_ad_group_settings` -- Read and change an ad group's name, status, bids, ad rotation, tracking suffix and audience targeting mode on any campaign type * `get_ad_group_demographics` / `update_ad_group_demographics` -- Read and set age, gender and household-income targeting on an ad group. You list the segments to target; every segment you leave out is excluded * `get_ad_group_audiences` / `add_ad_group_audiences` -- Read and add in-market, affinity, custom and customer-list audiences on an ad group. Find real audience IDs with `search_audiences` first * `add_campaign_proximity` -- Target a radius around an address, in miles or kilometers, with an optional bid modifier * `remove_campaign_proximity` -- Remove a radius you added. Run `get_campaign_targeting` first and pass the **Criterion ID** from its Proximity table. Only radius targets are removed; an ID that points at a location or keyword is skipped and reported, never deleted * `update_location_targeting` -- Switch a campaign between Presence and Presence-or-Interest location targeting without recreating it * `set_campaign_ad_schedule` -- Run ads only on the days and hours you choose, with optional bid modifiers. Any schedule you add limits ads to those windows * `set_campaign_device_bid_modifiers` / `set_ad_group_device_bid_modifiers` -- Bid up or down by device (mobile, tablet, desktop, connected TV) at campaign or ad group level. `get_ad_group_device_bid_modifiers` reads the current values * `update_pmax_audience_signal` -- Change the audiences in an existing Performance Max signal in place, instead of removing and re-adding it ### Dates, Frequency, Tracking & Labels * `get_campaign_dates` / `update_campaign_dates` -- Read or set a campaign's start and end dates on any campaign type * `get_campaign_frequency_caps` / `update_campaign_frequency_caps` -- Read or set how often a person sees your ads. An update replaces the full set of caps; pass an empty list to remove them all * `get_campaign_tracking` -- Read a campaign's tracking URL template, final URL suffix and custom parameters * `list_labels`, `create_label`, `get_campaign_labels`, `add_campaign_label`, `remove_campaign_label` -- Organize campaigns with account labels. Removing a label from a campaign does not delete the label * `create_conversion_action` -- Create a webpage conversion action so Target CPA, Maximize Conversions and Target ROAS bidding have something to optimize toward. You still install the Google site tag and conversion snippet on your site ### Removing Things * `remove_negative_keywords` -- Remove negative keywords from a campaign by ID. Permanent * `remove_ad` / `remove_ad_group` -- Remove an ad or an ad group (status becomes Removed) * `remove_campaign` -- Permanently delete a campaign and everything in it. It cannot be re-enabled; use `pause_campaign` to stop one temporarily * `add_app_ad_asset` / `remove_app_ad_asset` -- Add or remove an image or video asset on an existing App campaign ad ### Conversion Tracking Analysis * `list_conversion_actions` -- List all conversion actions in your account (purchases, form fills, phone calls, app installs) with tracking method and status * `get_conversion_action_performance` -- Pull conversion volume, value, and CPA broken down by conversion action — see which actions actually drive results * `update_conversion_action` -- Edit an existing conversion action by ID: name, category, status, value and currency, counting type, click-through and view-through lookback windows, whether it counts in the Conversions column, whether it's primary for its goal, and attribution model Only the fields you pass to `update_conversion_action` change — everything else stays as it is, and it never removes a conversion action. To stop one counting, set its status to `PAUSED`, which is reversible. **"Counts in the Conversions column" is the one field Google won't let the API change.** It's derived from the action's category and goal setup — and for conversions imported from Google Analytics, it's controlled in GA4. Ask for it and the rest of your update still applies; you get told to make that one change in the Google Ads UI (Goals → Conversions → the action → Edit settings) or in GA4. If the action is already set the way you asked, nothing is reported at all. The confirmation you get back lists only the fields that actually landed. Value, currency, and always-use-default-value move together as a set. If Adspirer can't read the action's current value settings before writing, the update fails instead of guessing at them: Smart Bidding reads those numbers, and a value quietly rewritten to zero does more damage than an update that didn't land. ### Shopping & Merchant Center Run Standard Shopping campaigns straight from your Google Merchant Center product feed — no per-product ad building. * `link_merchant_center` -- Link a Google Merchant Center account to your Google Ads account so its products are eligible to advertise * `get_merchant_center_links` -- List the Merchant Center accounts linked to your Google Ads account * `unlink_merchant_center` -- Remove a Merchant Center link * `get_shopping_settings` -- View a Shopping campaign's Merchant Center ID, country, and inventory filter * `create_shopping_campaign` -- Launch a Standard Shopping campaign from a linked Merchant Center feed (created PAUSED) * `add_shopping_ad_group` -- Add an ad group to a Shopping campaign * `add_shopping_product_ad` -- Add the product ad that surfaces your feed items * `add_product_group` / `get_product_groups` / `update_product_group` / `remove_product_group` -- Build and manage the **product partition tree** — subdivide your feed by brand, category, product type, or item ID and bid on each partition independently ### App (Universal App / UAC) Campaigns * `create_app_campaign` -- Launch an App campaign to drive **installs, in-app engagement, or pre-registration** across Search, Play, YouTube, Display, and Discover (created PAUSED) * App-ad creative management -- Add and edit the text, image, and video assets Google mixes into your app ads Google files App campaigns under the channel type `MULTI_CHANNEL`, so reading one back used to tell you nothing about the app itself. `list_campaigns` and `get_campaign_structure` now identify an App campaign as one, and name the **promoted app** (Play package name or App Store ID) with its store, plus the **App bidding goal** Google optimizes toward — install volume, installs at a target cost, in-app conversions, return on ad spend, or pre-registration volume. That goal is paired with the bidding strategy: a target-cost goal requires Target CPA, a no-target goal requires Maximize Conversions, and the ROAS goal requires Target ROAS. `update_bid_strategy` enforces the pairing before the call reaches Google, so a mismatch comes back naming the required strategy rather than as Google's "bidding strategy is incompatible with the goal type." App campaigns also report **installs, cost per install, and post-install conversions** in performance data. Cost per install is only reported when there are installs, and periods collected before August 2026 stay at zero until they're re-collected. ### Demand Gen Campaigns * `create_demandgen_campaign` -- Launch a Demand Gen campaign (visual, social-style ads across YouTube, Shorts, Discover, and Gmail) * `add_demandgen_ad_group` / `add_demandgen_ad` -- Build ad groups and image/video ads inside a Demand Gen campaign * `get_demandgen_audiences` / `replace_demandgen_audiences` -- View and set audience targeting * `get_demandgen_channel_controls` / `update_demandgen_channel_controls` -- Choose which surfaces (YouTube, Shorts, Discover, Gmail) the campaign runs on ### PMax Asset-Group Deep Management Beyond search themes and audience signals, manage the full asset-group structure of a Performance Max campaign: * `add_pmax_asset_group` / `get_pmax_asset_groups` / `update_pmax_asset_group` / `remove_pmax_asset_group` -- Full asset-group lifecycle * `add_pmax_asset_group_asset` / `list_pmax_asset_group_assets` / `remove_pmax_asset_group_asset` -- Manage individual headlines, descriptions, images, and videos within an asset group * `add_pmax_asset_group_image` / `list_pmax_asset_group_images` / `remove_pmax_asset_group_image` -- Manage asset-group images specifically * `get_pmax_asset_performance` -- See which assets Google rates Best / Good / Low so you know what to swap * `add_asset_group_listing_filter` / `get_asset_group_listing_filters` / `remove_asset_group_listing_filter` -- Scope a PMax asset group to a subset of your Merchant Center feed (retail PMax) > [!TIP] > > Google Ads has the largest tool set in Adspirer — **156 tools** with Manager-parity depth. The tools listed above are the most commonly used across Search, Shopping, App, PMax, Display, YouTube, and Demand Gen. Additional tools cover ad-group settings, device and ad-schedule bid modifiers, campaign labels, frequency caps, and more. ## Campaign Types ### Google Search Campaigns Text ads that appear when people search specific keywords on Google. Best for capturing high-intent traffic -- people actively looking for your product or service. **When to use:** Lead generation, e-commerce, local services, SaaS signups. ### Performance Max (PMax) Campaigns AI-powered campaigns that show ads across all Google channels: Search, Display, YouTube, Gmail, Maps, and Discover. Google's algorithm automatically optimizes placement and creative combinations. **When to use:** E-commerce (especially with product feeds), broad awareness + conversions, when you have strong creative assets (images + video). **Brand Guidelines** is supported at creation via `brand_guidelines_enabled`, which hands Google your square logo and business name at the campaign level and holds the brand-controlled layout across placements. Decide before you create — the setting cannot be turned on later. ### Display Campaigns New Responsive Display Ads across 2M+ websites, apps, and YouTube display slots. Supports standard Display (full manual control over 5 targeting surfaces: audiences, topics, placements, keywords, demographics) and Smart Display (Google-managed with AI-driven targeting + bidding). 27 dedicated tools covering full CRUD — creation, ad groups, ads, targeting, creative edits, frequency caps, and schedules. **When to use:** Retargeting website visitors, brand awareness, local businesses beyond Search, visual storytelling with image + video creative. → [Full Display Ads guide](/docs/ad-platforms/google-display-ads) ### YouTube Campaigns Video ads on YouTube (In-Feed, In-Stream, Shorts). Uses Demand Gen format with YouTube-only channel controls. **When to use:** Video-first creative, product demos, brand storytelling. → [Full YouTube Ads guide](/docs/ad-platforms/youtube-ads) ### Shopping Campaigns New Standard Shopping campaigns that advertise products directly from your Google Merchant Center feed — Google shows the product image, title, and price. Adspirer links Merchant Center, creates the campaign and product ad, and lets you build a **product partition tree** to bid differently by brand, category, or item. **When to use:** E-commerce and retail with a Merchant Center product feed. Pair with retail PMax (via asset-group listing filters) for full-funnel shopping coverage. ### App Campaigns New Universal App campaigns that drive app **installs, engagement, or pre-registration** across Search, Google Play, YouTube, Display, and Discover from a single set of assets. **When to use:** Mobile app growth — acquiring new installs or re-engaging existing users. ## Search Campaign Creation Workflow Google Search campaigns follow a 5-step workflow. Skip steps and the campaign will fail validation. ``` 1. get_connections_status -> (verify Google Ads is connected) 2. research_keywords -> (input: business description, seed keywords, target location) -> (output: keyword suggestions with real CPC data) 3. discover_existing_assets -> (check if you have headlines/descriptions in Google Ads already) 4. suggest_ad_content (if new assets needed) -> (generate headlines and descriptions within Google's character limits) 5. validate_and_prepare_assets -> (verify everything meets Google's requirements) 6. create_search_campaign -> (campaign created PAUSED -- you review before launching) ``` ## PMax Campaign Creation Workflow Performance Max requires creative assets plus optional search themes and audience signals for targeting: ``` 1. get_connections_status -> (verify Google Ads is connected) 2. discover_existing_assets -> (check for images, videos, logos in your account) 3. help_user_upload (if assets are missing) -> (guide you to upload to Google or provide URLs) 4. validate_and_prepare_assets -> (PMax requires: 5+ images, 1+ video, 5+ headlines, 5+ descriptions) 5. create_pmax_campaign -> (campaign created PAUSED) 6. add_pmax_search_themes -> (add up to 50 search themes to guide targeting) 7. search_audiences + add_pmax_audience_signal -> (find and add audience signals: in-market, affinity, custom, user lists) ``` ### PMax Asset Requirements * **Images:** Minimum 5 (1200x628px landscape + 1200x1200px square) * **Video:** Minimum 1 (under 30 seconds recommended) * **Headlines:** 5 (max 30 characters each) * **Descriptions:** 5 (max 90 characters each) * **Logo:** 1 (1200x1200px). On a Brand Guidelines campaign the square logo and business name go on the campaign instead of the asset group — use `add_pmax_campaign_logo` ## Example Prompts ### Analyze Performance Pull Google Ads metrics and highlight underperforming campaigns. Pull my Google Ads performance for the last 30 days. Show spend, conversions, CPA, and ROAS. Highlight any campaigns with ROAS below 2.0. ### Research Keywords Research keywords with real CPC data from Google Keyword Planner. Research keywords for emergency plumbing services in Chicago. Show me search volume, CPC estimates, and competition level. Suggest which keywords to target and which to avoid. ### Find Wasted Spend Identify keywords spending without converting. Analyze my Google Ads for wasted spend. Find keywords that have spent more than \$50 but generated zero conversions. Recommend which to pause and which to add as negative keywords. ### Create a Search Campaign End-to-end Google Search campaign with keyword research and ad copy. Create a Google Search campaign: * Business: Online pet supply store * Target keywords: organic dog food, natural dog treats, premium pet food * Location: United States * Budget: \$40/day * Objective: Website conversions (purchases) Research the keywords first, generate ad copy, then build the campaign. ### Create a Performance Max Campaign PMax campaign across all Google channels with asset validation. Create a Performance Max campaign for luxury watches: * Budget: \$50/day * Target audience: Men 25-54 interested in fashion and luxury goods * Creative: \[provide image and video URLs] * Objective: Online sales Validate all assets meet PMax requirements first. ### Add Search Themes to PMax Add search themes to an existing PMax campaign to guide targeting. Add search themes to my Performance Max campaign. Use themes related to: AI ad management, automated advertising, MCP tools for ads. Show me the current themes first, then add new ones. ### Add Audience Signals to PMax Find and add audience signals to a PMax campaign for better targeting. Search for in-market and affinity audiences related to "advertising software" and "marketing automation". Add them as audience signals to my PMax campaign. ### Optimize Budget ROAS-based budget reallocation across campaigns. Analyze my Google Ads campaigns for the last 30 days. Which campaigns have the best ROAS? Recommend how to reallocate my \$3,000/month budget to maximize conversions. ### Launch a Shopping Campaign Link Merchant Center and launch a Standard Shopping campaign with a product partition tree. Show my linked Google Merchant Center accounts (link one if none is connected), then create a Standard Shopping campaign at \$50/day. Break the products into partitions by product type and give me a bid on each. Leave it paused so I can review. ## Keyword Research: What You Need to Know The `research_keywords` tool connects directly to Google Keyword Planner data. You get: * **Search volume:** Monthly search estimates for each keyword * **CPC data:** Average cost-per-click and estimated bid range * **Competition level:** Low, Medium, or High * **Keyword suggestions:** Related keywords you may not have considered Each keyword's **search volume, competition, average CPC, and top-of-page bid range** is now passed to your AI assistant as structured data, so it reports the numbers per keyword reliably instead of only in aggregate. > [!WARNING] > > Keyword research is a Read tool (no cost impact), but always review the data before committing budget. High-volume keywords are not always the best choice -- look for keywords with good volume AND manageable CPC relative to your target CPA. If you're calling Adspirer over HTTP, the [research keywords API](/docs/api-reference/google-ads/research-keywords) returns the same Keyword Planner data programmatically, and the [benchmark context API](/docs/api-reference/google-ads/get-benchmark-context) supplies industry CPC and CTR baselines to compare those keywords against. ## Ad Copy Guidelines The `suggest_ad_content` tool generates headlines and descriptions within Google's strict character limits: * **Headlines:** Up to 15 headlines, max 30 characters each * **Descriptions:** Up to 4 descriptions, max 90 characters each * **Display URL paths:** 2 paths, max 15 characters each Google dynamically combines your headlines and descriptions. Provide diverse options so Google's algorithm can find high-performing combinations. ## Budget Guidelines * **Minimum:** \$10/day per campaign (Google's practical minimum for Search) * **Recommended:** \$30+/day for meaningful data collection * **Testing:** Start with \$40/day split across 3-5 ad groups to test different keyword themes * **Scaling:** Once you find keywords with CPA below target, increase budget 20-30% every 5-7 days * **PMax minimum:** \$20+/day recommended (PMax needs budget to test across multiple channels) > [!NOTE] > > **A budget change is confirmed only when it actually landed.** If Google rejects a budget update, Adspirer reports the failure with Google's reason rather than a success message. When you changed other settings in the same request, the response names which of them applied so you only need to retry the budget. ## Best Use Cases for Google Ads * **Demand capture:** Reach people actively searching for your product or service (highest intent of any platform) * **Local services:** Plumbers, dentists, lawyers, restaurants -- people searching "near me" * **E-commerce:** Product searches, comparison shopping, brand searches * **SaaS & B2B:** High-intent keywords like "CRM software" or "marketing automation tool" * **Lead generation:** Contact forms, phone calls, demo requests from search traffic **Not ideal for:** Brand awareness (use [Meta Ads](/docs/ad-platforms/meta-ads) or [TikTok Ads](/docs/ad-platforms/tiktok-ads) instead), visual/video-first products, targeting by job title (use [LinkedIn Ads](/docs/ad-platforms/linkedin-ads)). ## Troubleshooting ### "Ad account not connected" error Re-authenticate your Google Ads account: ``` Connect my Google Ads account ``` Make sure you select the correct Google account and ad account during OAuth. If you manage multiple accounts (MCC), you may need to specify which sub-account to use. ### "Asset validation failed" error Common causes: * Headlines exceed 30 characters or descriptions exceed 90 characters * Fewer than 5 images for PMax campaigns * Image dimensions do not meet minimum requirements * Missing required asset types (PMax needs images, headlines, descriptions, and at least one logo) Run validation separately to diagnose: ``` Validate my Google Ads assets for a Search campaign ``` ### "Campaign creation failed" error Most common reason: skipping workflow steps. Google campaigns require keyword research and asset validation before creation. If you jump straight to `create_search_campaign` without running `research_keywords` and `validate_and_prepare_assets` first, it will fail. **Retail PMax asset groups** used to fail on assets you had actually supplied. Google validates an asset group at the end of each batch of asset links, so creating and linking assets in an interleaved order could start validation before the required assets existed. Every asset is now created before anything is linked. ### Exact or phrase keywords rejected on a Search campaign If a Search campaign is configured for **broad match only** (AI Max), Google rejects exact and phrase keywords — with an error code newer than the client library can name, so the only thing that used to surface was the placeholder *"The error code is not in this version."* Adspirer now checks the campaign's real match-type setting before reporting anything, then tells you plainly that this campaign accepts broad match only. Either add the keywords as broad match, or add them to a campaign that isn't broad-match-only. Exact and phrase keywords on normal Search campaigns are unaffected. If you're using [agent skills](/docs/agent-skills/overview), the AI enforces the correct workflow automatically. ### "Operation not allowed for the given context" (bid strategy) This almost always means the campaign is attached to a **shared (portfolio) bid strategy**, so its bidding can't be changed at the campaign level. `update_bid_strategy` now detects this and tells you the two ways forward: detach the portfolio strategy from the campaign, or edit the shared strategy itself (which applies to every campaign using it). If you're switching to Smart Bidding (Target CPA / Target ROAS), Adspirer also reminds you of the prerequisites — active conversion tracking with recent conversion data — and suggests `MAXIMIZE_CONVERSIONS` as a no-target fallback that works with less data. ### "Assets are duplicated across operations" Google rejects a Responsive Search or Display ad edit if any two headlines (or two descriptions) are identical after ignoring case and whitespace. Adspirer now de-duplicates headlines and descriptions automatically before submitting, so this rarely surfaces. If de-duping leaves you below Google's minimum count, the error tells you exactly how many more **unique** headlines or descriptions to provide. ### "No search term data" on a Performance Max campaign Not a data problem. Google stores Performance Max queries separately from Search and Shopping queries, and `analyze_search_terms` reads only the latter. Ask again with `analyze_pmax_search_terms`, or `analyze_pmax_search_categories` for the grouped view. See [PMax search terms](#pmax-search-terms). ### "Keyword research returned no results" This usually means your seed keywords or business description is too narrow. Try: * Broader seed keywords (e.g., "plumber" instead of "emergency residential copper pipe repair") * Different location targeting (e.g., expand from city to state) * More descriptive business description so the tool can suggest related terms ### High CPA with no conversions Common issue with new campaigns. Troubleshoot: * Review search terms with `analyze_search_terms` -- are irrelevant queries consuming budget? * Add negative keywords with `add_negative_keywords` to block wasteful clicks * Check landing page quality -- Google Ads can drive clicks but conversions depend on your website * Use `analyze_wasted_spend` to identify keywords spending without converting ## FAQ > **What's the difference between Search and Performance Max campaigns?** > > **Search campaigns** show text ads on Google Search results when people search specific keywords. You control which keywords trigger your ads. Best for high-intent traffic. > > **Performance Max campaigns** use Google's AI to show ads across all Google channels (Search, Display, YouTube, Gmail, Maps, Discover). You provide creative assets and a conversion goal, and Google optimizes everything automatically. Best when you have strong creative assets and want broad reach with automated optimization. > **When should I use Display instead of Performance Max?** > > Use **[Display](/docs/ad-platforms/google-display-ads)** when you want precise control — specific audiences, specific websites, specific keywords — or for retargeting website visitors. Display runs on the Display Network only (2M+ sites and apps). > > Use **Performance Max** when you want Google's AI to optimize across every channel (Search, Display, YouTube, Gmail, Maps, Discover) with minimal manual targeting. PMax is broader but less controllable. > > Run Display for retargeting and specific placements; run PMax for broad automated reach. > **Does Adspirer generate images or videos for Google Ads?** > > No. Adspirer generates ad copy (headlines and descriptions) through the `suggest_ad_content` tool, but it does not create images or videos. For PMax campaigns, you provide image/video URLs from Google Drive, Dropbox, S3, or any public URL. The `validate_and_prepare_assets` tool ensures your assets meet Google's specifications. > **Can I manage Google Ads and Meta Ads from the same conversation?** > > Yes. Adspirer supports multi-platform management. You can pull Google Ads performance, then switch to Meta Ads analysis in the same conversation. Use `get_connections_status` to see all connected platforms. > **What's the difference between Google Ads and Meta Ads?** > > **[Google Ads](/docs/ad-platforms/google-ads):** Best for demand capture (reaching people actively searching for solutions). Keyword-based targeting. Higher intent but more expensive clicks. > > **[Meta Ads](/docs/ad-platforms/meta-ads):** Best for demand generation (reaching people who don't know you exist) and visual products. Interest-based targeting. Lower intent but cheaper clicks. > > Most advertisers run both: Google for high-intent searches, Meta for awareness and retargeting. > **What are PMax search themes and audience signals?** > > **Search themes** are short phrases (max 50 per asset group) that tell Google which search queries your Performance Max campaign should target. They supplement Google's automated targeting. > > **Audience signals** tell Google which audience segments are most likely to convert — in-market audiences, affinity audiences, custom audiences, and user lists (remarketing). They are signals, not hard targeting — Google uses them as starting points and expands from there. Only one audience signal is allowed per asset group. > > Both are PMax-only features and do not apply to Search, Display, or other campaign types. > **Can Adspirer run Shopping and App campaigns, not just Search?** > > Yes. Google Ads is Adspirer's deepest integration (156 tools) and covers **Search, Performance Max, Shopping, App (Universal App), Display, YouTube, and Demand Gen**. For Shopping, Adspirer links your Google Merchant Center feed, creates the campaign and product ad, and builds a product partition tree so you can bid by brand, category, or item. For App campaigns, it launches install / engagement / pre-registration campaigns across Search, Play, YouTube, Display, and Discover. Both are created PAUSED for your review. > **How much does Adspirer cost for Google Ads?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical Google Search campaign creation uses 5-6 tool calls. Keyword research alone is 1 call. See [full pricing](https://www.adspirer.com/pricing). > **Is my Google Ads data secure?** > > Yes. Adspirer uses OAuth 2.1 authentication -- your Google Ads credentials are never stored on Adspirer's servers. All connections are HTTPS-encrypted with least-privilege access scopes. You can revoke access at any time from your Google account settings. ## Related Documentation * [Google Display Ads Integration](/docs/ad-platforms/google-display-ads) — Display Network, retargeting, Smart Display * [YouTube Ads Integration](/docs/ad-platforms/youtube-ads) — Video campaigns on YouTube * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) * [TikTok Ads Integration](/docs/ad-platforms/tiktok-ads) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [How to Connect ChatGPT to Google Ads](https://www.adspirer.com/blog/connect-chatgpt-google-ads) — Step-by-step guide for managing Google Ads from ChatGPT * [How to Connect Claude to Google Ads](https://www.adspirer.com/blog/connect-claude-google-ads) — Step-by-step guide for managing Google Ads from Claude * [Google Ads + AI Integration](https://www.adspirer.com/integrations/google-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your Google Ads account (\$39 one-time) # Google Display Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/google-display-ads Create and manage Google Display Network campaigns with AI: standard Display, Smart Display, audiences, topics, placements, and frequency caps. # Google Display Ads Integration Reach people across millions of websites, apps, and YouTube display slots with Responsive Display Ads. Full campaign lifecycle — creation, five targeting surfaces, creative edits, frequency caps, and schedules — all managed through natural language. ## Prerequisites > [!NOTE] > > * Google Ads account ([create one here](https://ads.google.com)) > * An active ad account with billing information > * Admin or Standard access to the account you want to manage > * At least one landscape image (1.91:1) and one square image (1:1) for ad creative > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting Display Ads Display Ads runs through Google Ads — if you've already connected Google Ads, you're ready. No separate connection needed. 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my Google Ads account" 3. Adspirer opens your browser for OAuth authorization 4. Sign in to your Google account and select the ad account 5. Approve permissions Verify the connection: ``` Check my connected ad platforms ``` ## What You Can Do (27 Display Tools) ### Campaign Creation & Structure * `create_display_campaign` — Create a standard Display or Smart Display campaign (created PAUSED) * `add_display_ad_group` — Add additional ad groups with independent targeting * `add_display_ad` — Add additional Responsive Display Ads to an existing ad group * `select_google_campaign_type` — Choose between Search, PMax, Display, YouTube, or Demand Gen when the campaign type isn't specified ### Targeting (5 Surfaces — GET / ADD / REMOVE each) * `get_display_audiences` / `add_display_audiences` — In-market, affinity, custom audiences, user lists * `get_display_topics` / `add_display_topics` — Google content categories (Finance, Travel, etc.) * `get_display_placements` / `add_display_placements` — Specific websites, apps, YouTube channels, YouTube videos * `get_display_keywords` / `add_display_keywords` — Contextual keywords (always BROAD match on Display) * `get_display_demographics` / `update_display_demographics` — Age, gender, parental status, income exclusions * `remove_display_criteria` — Unified removal across all 5 targeting surfaces ### Creative & Campaign Edits * `update_display_ad_creative` — Change colors, CTA, images, videos, promo text, format\_setting on an existing ad * `update_display_ad_group` — Rename or repoint an ad group * `update_display_campaign_schedule` — Edit start/end dates and ad-schedule day/hour windows * `get_display_frequency_caps` / `update_display_frequency_caps` — View and edit impression caps per user * `get_display_ad_group_settings` — Inspect current bidding, status, and targeting on an ad group * `remove_display_ad` / `remove_display_ad_group` — Clean up ads and ad groups ### Geo & Language Resolution (Required Pre-Step) * `resolve_google_locations` — Resolve location names to exact `geoTargetConstants/` (rejects ambiguous inputs — e.g., "Baja" surfaces 5 candidates, no silent US fallback) * `list_google_languages` — Resolve language codes (rejects unknown codes with a clear pointer) ### Reused Lifecycle Tools (Work Across All Google Campaign Types) * `list_campaigns`, `get_campaign_structure`, `get_campaign_targeting` * `pause_campaign`, `resume_campaign`, `update_campaign` (settings and daily budget) * `add_sitelinks`, `add_callout_extensions`, `add_structured_snippets` * `get_campaign_performance`, `analyze_wasted_spend`, `optimize_budget_allocation` ## Campaign Types ### Standard Display Campaign Full manual control over targeting. You choose audiences, topics, placements, keywords, and demographics. Best when you have specific audience data or want to retarget website visitors. **When to use:** Retargeting, brand-safety-sensitive verticals, known audience segments, specific placement strategies (e.g., industry publications). ### Smart Display Campaign Google-managed variant. Google's AI auto-targets, auto-bids (`TARGET_CPA` required), and auto-generates ad combinations. Manual targeting fields are rejected. **When to use:** You have conversion tracking + 50+ Display conversions in the last 30 days and want Google's AI to do the heavy lifting. > [!WARNING] > > Smart Display requires `bidding_strategy=TARGET_CPA` and sufficient conversion history. If you pass any manual targeting (`audience_segments`, `topics`, `managed_placements`, `display_keywords`, `demographics`) with `smart_display=true`, the campaign creation will be rejected — Smart Display is fully automated. ## Campaign Creation Workflow Display campaigns follow a 6-step workflow: ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[resolve_google_locations] -->|Exact geoTargetConstants/id| B[list_google_languages] B -->|Validated language codes| C{Targeting approach?} C -->|Manual| D[search_audiences + prepare topics/placements/keywords] C -->|Smart Display| E[Conversion tracking check] D --> F[Prepare creative: headlines, descriptions, images, colors] E --> F F --> G[create_display_campaign] G -->|PAUSED| H[Add extensions] H --> I[add_sitelinks + add_callout_extensions + add_structured_snippets] ``` ``` 1. resolve_google_locations -> (names -> exact geoTargetConstants/; rejects ambiguous "Baja"-style inputs) 2. list_google_languages -> (validate ISO language codes; no silent fallbacks) 3. search_audiences (if using manual audience targeting) -> (find real in-market/affinity/custom audience IDs — never fabricate) 4. Prepare creative assets -> (1-5 headlines ≤30 chars, 1 long headline ≤90, 1-5 descriptions ≤90, ≥1 landscape image 1.91:1, ≥1 square image 1:1, optional logos/videos) 5. create_display_campaign -> (campaign + default ad group + RDA created PAUSED — you review before launching) 6. add_sitelinks + add_callout_extensions + add_structured_snippets -> (extensions lift CTR 15-25%) ``` ## Asset Requirements ### Required | Asset | Count | Spec | | - | :-: | - | | **Short headlines** | 1-5 | Max 30 characters each | | **Long headline** | 1 | Max 90 characters | | **Descriptions** | 1-5 | Max 90 characters each | | **Business name** | 1 | Max 25 characters | | **Landscape images** | 1+ | 1.91:1, min 600×314, max 5MB | | **Square images** | 1+ | 1:1, min 300×300, max 5MB | | **Final URL** | 1 | Must be HTTPS | ### Optional | Asset | Count | Spec | | - | :-: | - | | **Landscape logos** | 0-5 | 4:1 | | **Square logos** | 0-5 | 1:1, min 128×128 | | **YouTube videos** | 0-5 | 11-char YouTube video IDs | | **Main color** | 1 | Hex (e.g., `#112233`) | | **Accent color** | 1 | Hex (e.g., `#FFAABB`) | | **Price prefix** | 1 | Max 10 chars (e.g., "from") | | **Promo text** | 1 | Max 20 chars (e.g., "Up to 50% off") | You can also reuse existing image assets already in your Google Ads account via the `existing_images` parameter — pass resource names instead of re-uploading. ## Bidding Strategies | Strategy | Best For | Required Field | Conversion Tracking | | - | - | - | :-: | | **MAXIMIZE\_CLICKS** (default) | Most campaigns, driving traffic | — | No | | **MAXIMIZE\_CONVERSIONS** | Optimizing for signups/purchases | — | Yes | | **TARGET\_CPA** | Cap cost per acquisition | `target_cpa` | Yes | | **TARGET\_ROAS** | E-commerce, revenue optimization | `target_roas` (e.g., 3.5 = 350%) | Yes | | **MANUAL\_CPC** | Full bid control | `cpc_bid` | No | | **MANUAL\_CPM** | Viewable CPM (awareness) | `cpm_bid` | No | Smart Display requires `TARGET_CPA`. ## Targeting Surfaces Standard Display campaigns support five independent targeting layers. Mix and match — they intersect, so narrower targeting = narrower reach. ### Audiences * **In-market** — People actively researching a purchase in a category * **Affinity** — Long-term interest-based segments (e.g., "Outdoor Enthusiasts") * **Custom audiences** — Segments you build from keywords, URLs, or app interests * **User lists** — Your remarketing lists and Customer Match uploads * **Combined audiences** — AND/OR combinations of the above Use `search_audiences` first to find real audience IDs — never fabricate them. ### Topics Google's content categorization tree (Finance > Personal Finance > Credit & Lending, etc.). Ads serve on pages matching the selected topics. ### Managed Placements Target specific URLs, mobile apps, YouTube channels, or YouTube videos. Most precise targeting available on Display. ``` [ {"type": "website", "value": "example.com"}, {"type": "youtube_channel", "value": "UCxxxx"}, {"type": "mobile_app", "value": "com.example.app"} ] ``` ### Display Keywords Contextual — ads serve on pages **about** those keywords (always BROAD match on Display). Pass `negative=true` for negative keywords. ### Demographics Exclude demographic groups you don't want to reach. Age ranges, genders, parental statuses, income ranges. > [!NOTE] > > Demographics on Display are **exclusion-based**. Whatever you list is **kept**; whatever you don't list is **excluded**. Be deliberate — omitting `genders` entirely means no gender filter, but passing `["MALE"]` excludes FEMALE and UNDETERMINED. ## Example Prompts ### Create a Standard Display Campaign End-to-end Display campaign with audience + topic + placement targeting. Create a Google Display campaign: * Business: B2B project management SaaS * Landing page: [https://example.com/signup](https://example.com/signup) * Business name: ProjectHub * Budget: \$30/day * Target locations: United States, Canada * Audiences: in-market for "Business Software", affinity "Technophiles" * Topics: Business & Industrial, Computers & Electronics * Managed placements: techcrunch.com, theverge.com * Creative: [https://cdn.example.com/landscape.png](https://cdn.example.com/landscape.png) and [https://cdn.example.com/square.png](https://cdn.example.com/square.png) * Main color #2563eb, accent color #f59e0b * 5 headlines and 3 descriptions * Resolve locations + languages first, then launch ### Retargeting Campaign with User Lists Display retargeting using an existing remarketing list. Set up a Display retargeting campaign for my e-commerce store: * Remarketing list: "Website Visitors — Last 30 Days" * Budget: \$20/day * Bidding: TARGET\_CPA at \$15 * Frequency cap: 3 impressions per user per day * Locations: United States * Creative: reuse existing landscape and square images from my account (check discover\_existing\_assets first) * Promo text: "Welcome back — 15% off" * CTA: SHOP\_NOW ### Smart Display Campaign Google-managed Smart Display for advertisers with conversion tracking. Create a Smart Display campaign: * Business: Online fitness coaching * Landing page: [https://example.com/coaching](https://example.com/coaching) * Budget: \$40/day * Target CPA: \$25 * Locations: United States * Creative: 5 headlines, 1 long headline, 5 descriptions, landscape + square images, 1 logo * This account has 200+ Display conversions in the last 30 days ### Edit Creative on an Existing Display Ad Refresh colors, CTA, and images on a live Display ad. Update the creative on my Display ad ID \[ad\_id]: * New main color #10b981 * Change CTA to BOOK\_NOW * Add 2 new landscape images: \[url1], \[url2] * Remove the old promo text * Set format\_setting to NATIVE ### Add Frequency Caps Cap impressions per user across a Display campaign. Set a frequency cap on my Display campaign \[campaign\_id]: * 5 impressions per user per day * 15 impressions per user per week Show me the current caps first, then apply the change. ## Geo & Language Resolution > [!TIP] > > Always run `resolve_google_locations` before `create_display_campaign` (or any campaign creation). Location strings like "London" are ambiguous — the resolver surfaces candidates (London UK, London Ontario, Londonderry) instead of silently picking one. The resolver: * Rejects ambiguous inputs with multiple candidates (you pick explicitly) * Rejects unknown locations with a clear error * Never silently falls back to "United States" * Returns exact `geoTargetConstants/` values Google Ads accepts `list_google_languages` works the same way for ISO language codes. ## Budget Guidelines * **Minimum:** \$10/day (Google's practical minimum for Display) * **Recommended:** \$20-30/day for meaningful reach and data * **Smart Display minimum:** \$20+/day (Google's AI needs budget to learn) * **Scaling:** Once CPA is below target, increase 20-30% every 5-7 days — Smart Display learning resets on big jumps ## Best Use Cases for Display Ads * **Retargeting:** Re-engage website visitors and cart abandoners with visual reminders * **Brand awareness:** Top-of-funnel reach across 2M+ sites and apps * **Product catalogs:** Show product imagery at scale * **Local businesses:** Geographic targeting with visual creative (works where Search volume is too low) * **App install support:** Reinforce install campaigns with display creative * **Complement Search:** Catch audiences before they type the query **Not ideal for:** High-intent demand capture (use [Google Search Ads](/docs/ad-platforms/google-ads)), B2B targeting by job title (use [LinkedIn Ads](/docs/ad-platforms/linkedin-ads)), short-form social engagement (use [TikTok Ads](/docs/ad-platforms/tiktok-ads)), video-first campaigns (use [YouTube Ads](/docs/ad-platforms/youtube-ads)). ## Display vs Performance Max | Feature | Display | Performance Max | | - | :-: | :-: | | Placements | Display Network only | Search + Display + YouTube + Gmail + Maps + Discover | | Targeting control | Full manual (5 surfaces) | AI-driven, limited signals | | Creative | Images + optional videos | Images + videos + feed required | | Retargeting | Supported (user lists) | Limited | | Minimum budget | \$10/day | \$20/day recommended | | Best for | Retargeting, specific placements | Broad reach + automated optimization | Run Display when you want precise control and specific audiences/sites. Run PMax when you want Google's AI to decide across every channel. ## Troubleshooting ### "Ambiguous location" error The resolver flagged your input because multiple cities match. Fix by narrowing: * `"London"` → `"London, United Kingdom"` or `"London, Ontario, Canada"` * `"Baja"` → `"Baja California, Mexico"` Or pass the exact `geoTargetConstants/` from the resolver's candidate list. ### "Smart Display rejected manual targeting" Smart Display is fully Google-managed. Remove `audience_segments`, `topics`, `managed_placements`, `display_keywords`, and `demographics`. Or switch to standard Display (`smart_display: false`). ### "Headline too long" error Display short headlines are capped at **30 characters** (stricter than Search). The validator tells you the exact character count and how many to remove. Long headline (separate field) is capped at 90. ### Low CTR on Display Common fixes: * Add stronger color contrast (set `main_color` + `accent_color` explicitly) * Include a promo text or price prefix to draw attention * Test different CTA labels (SHOP\_NOW, LEARN\_MORE, GET\_QUOTE, etc.) * Refresh creative — Display fatigue kicks in faster than Search * Narrow targeting — broad audiences dilute CTR ### "Audience ID not found" Never fabricate audience IDs. Always run `search_audiences` first to get real resource names. In-market and affinity segments have Google-assigned IDs; custom audiences and user lists have account-specific resource names. ## FAQ > **Can I use the same creative for Display and PMax?** > > Yes — both use image + video assets. You can reuse existing assets via the `existing_images` parameter instead of re-uploading. However, PMax also requires a product feed for e-commerce use cases; Display does not. > **What's the difference between standard Display and Smart Display?** > > **Standard Display** gives you full manual control — 5 targeting surfaces (audiences, topics, placements, keywords, demographics), any bidding strategy, fine-grained creative settings. > > **Smart Display** is Google-managed. Google's AI auto-targets, auto-bids (`TARGET_CPA` required), and auto-optimizes creative combinations. You just upload assets and set a budget + target CPA. Requires conversion tracking and 50+ Display conversions in the last 30 days. > **Do I need conversion tracking for Display?** > > Only for Smart Display and for conversion-based bidding (`MAXIMIZE_CONVERSIONS`, `TARGET_CPA`, `TARGET_ROAS`). Standard Display with `MAXIMIZE_CLICKS`, `MANUAL_CPC`, or `MANUAL_CPM` works without conversion tracking. > **How is Display different from retargeting on Meta Ads?** > > **Google Display** reaches people across 2M+ websites, apps, and YouTube display slots. Targeting uses Google's ecosystem (in-market segments, user lists, topics). > > **[Meta Ads](/docs/ad-platforms/meta-ads)** retargeting reaches people on Facebook, Instagram, Messenger, and Audience Network. Targeting uses Meta's social graph (custom audiences, lookalikes). > > Most advertisers run both — Google Display catches users browsing the open web; Meta catches them in social feeds. > **Can Adspirer create the display images for me?** > > No. Adspirer manages campaigns, not asset generation. You provide image URLs (Google Drive, Dropbox, S3, CDN, or any public URL) and Adspirer validates + uploads them to Google Ads. Use your preferred design tools (Canva, Figma, Photoshop) for the creative. > **What ad format should I use — NATIVE, NON\_NATIVE, or ALL\_FORMATS?** > > **ALL\_FORMATS** (default) serves across every Display placement — maximum reach. > > **NATIVE** restricts to placements where ads blend with the surrounding content (recommended for premium publishers, higher CPM, better engagement). > > **NON\_NATIVE** restricts to standard banner placements (useful for testing reach vs quality). > > Start with ALL\_FORMATS. Switch to NATIVE if you see low-quality placements consuming budget. > **How much does Adspirer cost for Display Ads?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical Display campaign creation uses 5-7 tool calls (resolve locations + resolve languages + search audiences + create campaign + add extensions). See [full pricing](https://www.adspirer.com/pricing). ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) — Search + PMax * [YouTube Ads Integration](/docs/ad-platforms/youtube-ads) — Video-first Google campaigns * [Meta Ads Integration](/docs/ad-platforms/meta-ads) — Social retargeting alternative * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) — B2B targeting * [TikTok Ads Integration](/docs/ad-platforms/tiktok-ads) — Short-form social * [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) — Retail / e-commerce PPC * [ChatGPT Ads Integration](/docs/ad-platforms/chatgpt-ads) — Ads inside ChatGPT * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your Google Ads account (Display included) (\$39 one-time) # LinkedIn Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/linkedin-ads Connect LinkedIn Ads to Adspirer for B2B campaign management. Target by job title, industry, and seniority with 55 AI tools for image, video, text, and carousel sponsored content. # LinkedIn Ads Integration [LinkedIn Ads with Claude Mobile App and Adspirer](https://www.youtube.com/embed/BxjtR_intmY) LinkedIn Ads with Claude Mobile App and Adspirer B2B advertising done right. Target decision-makers by job title, industry, seniority, and 14 additional facets with 55 specialized tools. Image, video, text, and carousel campaigns, a full campaign-group hierarchy with batch operations, pre-launch audience forecasting, and rollback logic. ## Prerequisites > [!NOTE] > > * LinkedIn Campaign Manager account ([create one here](https://business.linkedin.com/marketing-solutions/ads)) > * A LinkedIn company page (required to run ads) > * An active ad account with billing information > * Admin access to the ad account you want to manage > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting LinkedIn Ads Once you've set up Adspirer with your AI client, connect LinkedIn: 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my LinkedIn Ads account" 3. Adspirer opens your browser for OAuth authorization 4. Sign in to LinkedIn Campaign Manager and select the ad account you want to manage 5. Approve permissions (read campaign data, create ads, manage budgets) Verify the connection: ``` Check my connected ad platforms ``` You should see your LinkedIn ad account listed with organization name, account ID, and active status. ## What You Can Do (55 Tools) ### Performance Analysis * `get_linkedin_campaign_performance` -- Pull metrics for campaigns, ad groups, or individual sponsored posts. Filter by campaign ID or name. * `get_linkedin_engagement_metrics` -- Engagement breakdown: reactions, comments, shares, follows, and click types * `analyze_linkedin_creative_performance` -- Deep analysis of which images/copy combinations perform best * `get_linkedin_audience_insights` -- See which job functions, industries, seniorities, and company sizes actually engage * `analyze_linkedin_wasted_spend` -- Identify campaigns spending without converting and recommend cuts * `explain_linkedin_anomaly` -- Diagnose sudden changes in CTR, CPC, or conversion rate #### Lead-gen campaigns are graded on cost per lead, not ROAS Almost nothing on LinkedIn carries revenue back to the ad, so a ROAS verdict on a B2B campaign is meaningless. `analyze_linkedin_wasted_spend` picks its yardstick from the **campaign's objective**: lead generation and talent leads are measured on cost per lead, and converting campaigns come back in a **Lead Gen Campaign Performance** table sorted best cost-per-lead first, with no ROAS column. A campaign with zero recorded leads is still called out as a loss -- that spend bought nothing -- but as *no leads recorded* rather than `0.00x` ROAS, and the step offered is to confirm your conversion tracking before pausing anything. A target ROAS is only quoted back at you if you actually set one; the analysis no longer prints a default "target ROAS (2.0x)" you never asked for. `optimize_linkedin_budget` stopped labelling every campaign *"Only 0 days of data"*. It counts a campaign's days of data properly, so the under-a-week exclusion it was always meant to apply is now a real one -- rather than a note printed against every campaign while all of them were optimized anyway. When every campaign in the account is under a week old, you get a note saying the recommendation is provisional instead of a confident reallocation. ### Targeting, Research & Forecasting * `search_linkedin_targeting` -- Find audiences by job title, industry, company size, seniority, skills, groups, and 14 additional facets * `research_business_for_linkedin_targeting` -- Input a competitor or target company, get suggested targeting criteria * `estimate_linkedin_audience_size` -- Get the estimated audience size for a targeting spec **before** you launch * `forecast_linkedin_campaign_supply` -- Forecast impressions, clicks, and spend a campaign can deliver at a given budget — plan spend with data, not guesswork * `get_linkedin_campaign_targeting` -- View the full targeting on an existing campaign * `update_linkedin_campaign_targeting` -- Adjust targeting on a live campaign ### Organizations * `get_linkedin_organizations` -- List your company pages (required before campaign creation) ### Campaign Creation (image, video, text, carousel) * `select_linkedin_campaign_type` -- Pick the right format for your creative and objective * `explain_linkedin_objectives` -- Understand which LinkedIn objective fits your goal * `discover_linkedin_assets` -- Check if you have existing creatives in LinkedIn (includes videos uploaded via Campaign Manager) * `validate_and_prepare_linkedin_assets` -- Verify creatives meet LinkedIn's requirements (dimensions, file size) * `generate_linkedin_ad_creatives` -- AI-draft ad copy variations for your campaign * `create_linkedin_image_campaign` -- Launch single-image sponsored content campaigns * `create_linkedin_video_campaign` -- Launch video sponsored content campaigns * `create_linkedin_text_campaign` -- Launch text ad campaigns * `create_linkedin_carousel_campaign` -- Launch multi-card carousel campaigns ### Campaign Groups * `create_linkedin_campaign_group` -- Create a campaign group to organize campaigns and set a shared budget/schedule * `batch_create_linkedin_campaign_groups` -- Create several campaign groups at once * `list_linkedin_campaign_groups` / `search_linkedin_campaign_groups` -- Find and list campaign groups * `update_linkedin_campaign_group` -- Change a group's budget, schedule, or status * `delete_linkedin_campaign_group` -- Remove a campaign group * `add_linkedin_campaign_to_group` -- Add a new campaign to an existing campaign group (different audience, same group) ### Creative Management * `add_linkedin_creative` -- Add new sponsored posts to existing campaigns * `add_linkedin_carousel_creative` -- Add carousel creative variations to campaigns * `add_linkedin_video_creative` -- Add video creatives to campaigns * `add_linkedin_text_creative` -- Add text ad creatives * `update_linkedin_creative` -- Edit copy or creative assets on live ads * `list_linkedin_creatives` -- List creatives on a campaign * `pause_linkedin_creative` / `resume_linkedin_creative` -- Pause or resume individual creatives * `delete_linkedin_creative` -- Remove a creative ### Campaign Management & Lifecycle * `update_linkedin_campaign` -- Change budgets, bids, or targeting (all 19 targeting facets supported) * `update_linkedin_campaign_budget` -- Change a campaign's budget * `update_linkedin_campaign_schedule` -- Change start/end dates * `pause_linkedin_campaign` -- Stop campaigns or ad groups * `resume_linkedin_campaign` -- Restart paused campaigns * `archive_linkedin_campaign` / `reactivate_linkedin_campaign` -- Archive a campaign or bring it back * `delete_linkedin_campaign` -- Permanently remove a campaign * `clone_linkedin_campaign` -- Duplicate a campaign with optional changes * `batch_update_linkedin_campaigns` / `batch_delete_linkedin_campaigns` -- Update or delete many campaigns in one call * `list_linkedin_campaigns` -- List campaigns, filter by campaign group ### Optimization * `optimize_linkedin_budget` -- Reallocate budget based on conversion performance ### Conversions * `manage_linkedin_conversions` -- Set up and track conversion events (form fills, downloads, demo requests) * `list_linkedin_conversions` -- List conversion rules on your account * `associate_linkedin_conversion` -- Attach a conversion rule to a campaign ## Campaign Creation Workflow LinkedIn campaigns follow a 5-step workflow: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 1. get_linkedin_organizations ↓ (select which company page to advertise under) 2. search_linkedin_targeting OR research_business_for_linkedin_targeting ↓ (find your B2B audience) 3. discover_linkedin_assets ↓ (check existing creatives) 4. validate_and_prepare_linkedin_assets ↓ (verify image URLs meet LinkedIn requirements) 5. create_linkedin_image_campaign ↓ (campaign created PAUSED) ``` ## Example Prompts ### Analyze Performance LinkedIn Ads metrics with cost-per-lead analysis. Pull my LinkedIn Ads performance for the last 60 days. Show spend, clicks, conversions, and cost per lead. Highlight campaigns with cost per lead above \$75. ### Research Targeting for a New Campaign B2B audience targeting research with size estimates. I want to target marketing directors at B2B SaaS companies with 100-500 employees. What targeting criteria should I use on LinkedIn? Show me audience size estimates. ### Forecast Delivery Before Launch Estimate audience size and forecast delivery for a proposed LinkedIn budget. For VP-level marketing leaders at US software companies with 200-1000 employees, estimate my LinkedIn audience size and forecast the impressions, clicks, and spend I'd get at \$100/day for 30 days. Is that budget enough to be worth running? ### Create a Sponsored Content Campaign LinkedIn sponsored content with B2B targeting and lead gen. Create a LinkedIn sponsored content campaign: * Product: B2B marketing automation platform * Target: Marketing managers at tech companies with 50-1000 employees * Job titles: Marketing Manager, Demand Gen Manager, Growth Marketing Manager * Industries: Computer Software, Internet, Information Technology * Budget: \$75/day * Creative: \[provide image URL] * Objective: Lead generation (demo request form) Validate the creative first, then build the campaign. ### Optimize Budget Allocation Cost-per-lead analysis with budget reallocation. Analyze my LinkedIn campaigns for the last 30 days. Which campaigns have the best cost per lead? Recommend how to reallocate my \$5,000/month budget to maximize lead volume. ### Competitive Targeting Research Competitor-based LinkedIn targeting research. Research targeting for LinkedIn based on this competitor: HubSpot. What job titles, industries, and seniority levels should I target to reach their customer base? ## B2B Targeting Options LinkedIn's targeting is the most precise for B2B. Here's what you can target: ### Job Criteria * **Job titles:** CMO, VP Marketing, Marketing Manager, Growth Lead, etc. * **Job functions:** Marketing, Sales, Engineering, Operations, etc. * **Seniority:** C-level, VP, Director, Manager, Entry-level * **Years of experience:** 0-2, 3-5, 6-10, 11+ years ### Company Criteria * **Industries:** Computer Software, Financial Services, Marketing & Advertising, etc. (140+ options) * **Company size:** 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+ employees * **Company name:** Target specific companies (ABM campaigns) * **Company growth rate:** Fast-growing companies (20%+ headcount growth) ### Skills & Interests * **Skills:** SaaS, Marketing Automation, SEO, Content Marketing, etc. * **Groups:** Target members of specific LinkedIn groups * **Interests:** Categories professionals engage with ### Additional targeting facets All 19 targeting facets are supported on both campaign creation and update: * Degrees, fields of study, schools * Member behaviors, buyer groups * Age ranges, genders * Employers, followed companies * Years of experience ranges ## Budget Guidelines * **Minimum:** \$10/day (LinkedIn's requirement) * **Recommended:** \$50+/day for meaningful B2B lead volume * **Testing:** Start with \$75/day split across 2-3 audience segments * **CPC range:** Expect \$8-15+ per click (higher than Meta/Google but higher quality leads) * **Cost per lead:** B2B leads typically \$40-150 depending on industry and targeting ## Campaign Groups LinkedIn campaigns can be organized into campaign groups. All create tools accept `campaign_group_id` and `campaign_group_name`. Use `add_linkedin_campaign_to_group` to add campaigns with different audiences to the same group. If a campaign creation fails after the campaign is created but before the creative is added, Adspirer automatically archives the orphaned campaign to prevent duplicates on retry. ## Creative Requirements LinkedIn sponsored content supports single images and carousel formats. The `validate_and_prepare_linkedin_assets` tool checks: * **Dimensions:** 1200x627px (1.91:1 aspect ratio) or 1200x1200px (1:1) * **Format:** JPG or PNG * **File size:** Under 5MB * **Text:** Intro text up to 600 characters (150 shown before "see more") * **Headline:** Up to 200 characters * **Call-to-action:** Learn More, Download, Sign Up, Register, Apply, etc. ## Best Use Cases for LinkedIn Ads * **B2B lead generation:** Demos, webinar signups, whitepaper downloads * **Account-based marketing (ABM):** Target specific companies or job titles * **Thought leadership:** Content promotion to build brand authority * **Event promotion:** Conferences, trade shows, virtual events * **Recruitment:** Job postings to specific professional audiences **Not ideal for:** E-commerce, consumer products, impulse purchases. LinkedIn is a B2B platform. CPC is high, but lead quality is excellent for long sales cycles. ## Troubleshooting ### "No organizations found" error You need a LinkedIn company page before you can run ads. Create one at [linkedin.com/company/setup/new](https://www.linkedin.com/company/setup/new), then reconnect your LinkedIn Ads account in Adspirer. ### "Campaign creation failed" error Most common reason: skipping `get_linkedin_organizations`. You must select an organization before creating campaigns. Run the full workflow in order. If you're using [agent skills](/docs/agent-skills/overview), the AI enforces the correct workflow automatically. ### "Audience too small" warning LinkedIn requires a minimum audience size of 300 members. If your targeting is too narrow (e.g., "CMOs at Series A SaaS startups in San Francisco"), broaden it: * Expand job titles (CMO, VP Marketing, Head of Marketing) * Widen geography (San Francisco -> Bay Area -> California) * Increase company size range (Series A -> Series A-C) ### High CPC but low conversions Common issue with LinkedIn. Your targeting might be too broad. Tighten it: * Add seniority filters (target decision-makers, not individual contributors) * Use negative targeting (exclude students, job seekers) * Test different creative (professional, data-driven imagery works best on LinkedIn) * Optimize your landing page for B2B (short forms, clear value prop, no fluff) ## FAQ > **Can I run video ads on LinkedIn through Adspirer?** > > Yes. Adspirer now supports **image, video, text, and carousel** sponsored content on LinkedIn — use `create_linkedin_video_campaign` (or `add_linkedin_video_creative` to add video to an existing campaign). You supply the video URL; `validate_and_prepare_linkedin_assets` checks it against LinkedIn's requirements before launch. > **Can I estimate audience size or forecast delivery before launching?** > > Yes. `estimate_linkedin_audience_size` returns the reachable audience for a targeting spec, and `forecast_linkedin_campaign_supply` projects the impressions, clicks, and spend a campaign can deliver at a given budget — so you can size a campaign and set a realistic budget before you commit. > **Can I target by company revenue?** > > LinkedIn doesn't expose revenue as a targeting option via the API. You can target by company size (employee count) and industry as a proxy. > **What's the difference between LinkedIn and Google Ads for B2B?** > > **LinkedIn:** Best for demand generation (reaching people who might need your solution but aren't actively searching). Target by job title/seniority. Higher CPC but better B2B lead quality. > > **[Google Ads](/docs/ad-platforms/google-ads):** Best for demand capture (reaching people actively searching for solutions like yours). Target by keywords. Lower CPC but broader intent. > > Most B2B companies run both: Google for high-intent keywords, LinkedIn for cold outreach to specific job titles. > **Can I use LinkedIn's Matched Audiences (retargeting)?** > > Not through Adspirer yet. Matched Audiences (website retargeting, contact list uploads) requires additional API permissions that are in development. For now, focus on interest-based and job title targeting. > **How much does Adspirer cost for LinkedIn Ads?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical LinkedIn campaign creation uses 5-6 tool calls. See [full pricing](https://www.adspirer.com/pricing). ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [LinkedIn Ads + AI Integration](https://www.adspirer.com/integrations/linkedin-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your LinkedIn Ads account (\$39 one-time) # Meta Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/meta-ads Manage Facebook and Instagram campaigns with Adspirer's 60 MCP tools: image, video, carousel, and Advantage+ Catalog (dynamic product) ads, creative fatigue, audiences, and performance. ## Prerequisites > [!NOTE] > > * Meta Business Manager account ([create one here](https://business.facebook.com)) > * An active Meta ad account with billing information > * Admin access to the ad account you want to manage > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting Meta Ads Once you've set up Adspirer with your AI client, connect Meta: 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my Meta Ads account" 3. Enter your email address when prompted 4. Review and accept the Meta Ads disclaimer — you must check the box acknowledging that Adspirer operates independently from Meta's account enforcement systems before proceeding 5. Adspirer opens your browser for OAuth authorization 6. Sign in to Meta Business Manager and select the **Business Manager(s)** you want to grant access to 7. Approve permissions (read campaign data, create ads, manage budgets) > [!TIP] > > **Business Manager-wide import.** When you grant access to a Business Manager, Adspirer discovers **every ad account inside that BM**, not just the one you happened to click during OAuth. The Manage Accounts modal at [adspirer.ai/connections](https://adspirer.ai/connections) lists all of them so you can pick which ones to activate. > [!NOTE] > > The disclaimer confirms that you authorize Adspirer to read your campaign data and manage ads through Meta's official Marketing API, and that Adspirer is not responsible for any account actions taken by Meta (security reviews, restrictions, or account disabling). Verify the connection: ``` Check my connected ad platforms ``` You should see every Meta ad account discovered from your Business Manager listed with name, ID, and active status. Activate the ones you want the agent to work with from the Manage Accounts modal. ### Asset handling across ad accounts When you ask the agent to launch a creative the agent finds in a **different ad account in the same Business Manager**, Adspirer offers to copy that creative into the target account before creating the campaign. This is **opt-in per call** — the agent asks before copying so you stay in control of which ad account holds which assets. Per-account asset discovery (image, video, creative) is scoped to the specific ad account you're targeting so you don't get false "asset not found" errors when the asset lives one BM over. **Cross-account safety.** If you ask the agent to add an ad to an ad set — or an ad set to a campaign — that actually belongs to a *different* one of your accounts, Adspirer catches the mismatch up front, names both accounts, and points to the right tool to list the correct entity, instead of letting Meta return a misleading "missing creative" error. Deselected (inactive) ad accounts are also write-protected: the agent can't create or change ads in them until you re-activate them from the Manage Accounts modal. > [!NOTE] > > Adspirer has Meta approved **Ads Management Standard Access**. This means Adspirer uses Meta's official Marketing API with verified permissions to read campaign data and manage ads on your behalf. > > Meta's account enforcement systems operate independently from Adspirer. Any account actions taken by Meta — including security reviews, restrictions, or account disabling — are governed by [Meta's Community Standards and policies](https://www.facebook.com/policies/ads/), not by Adspirer. ## What You Can Do (60 Tools) ### Performance Analysis * `get_meta_campaign_performance` — Pull metrics for campaigns, ad sets, or individual ads * `get_meta_adset_performance` — Middle-layer analysis: spend, CTR, CPA, ROAS broken down by ad set within a campaign — see which audience segments perform best without going to individual ad level * `analyze_meta_ad_performance` — Deep analysis of ad-level performance with recommendations * `get_meta_audience_insights` — Audience breakdown by age, gender, and interests * `analyze_meta_audiences` — See which audience segments perform best, ranked by the metric your objectives actually support * `analyze_meta_wasted_spend` — Identify campaigns with poor ROAS and recommend cuts * `detect_meta_creative_fatigue` — Identify ads losing effectiveness over time * `explain_meta_anomaly` — Diagnose sudden changes in performance (CPA spikes, CTR drops) * `get_meta_ad_creatives` — View creative details for ads in a campaign > [!NOTE] > > **Which conversions Adspirer counts.** Performance and results reporting count the conversions Meta actually reports — including **Pixel custom events** (e.g. a Calendly booking), **lead-form submissions**, **Messenger conversations**, and **offline conversions** — with a per-event-name breakdown ("5 *invitee\_select\_time* events," not "5 custom conversions"). Lead-gen and sales campaigns are treated as conversion campaigns in wasted-spend, anomaly, and budget analysis, so the agent won't tell you a lead-gen campaign is "optimizing blind." If you recently optimized for a custom Pixel event and saw 0 conversions in older reports, newly collected data now counts it; historical numbers backfill separately. > > The Meta performance dashboard also shows a **conversion breakdown** of every action type and highlights the **purchase-class event** that reconciles with the "Results" column in Meta Ads Manager. So when a "Conversions (all actions)" headline looks higher than Ads Manager — because Meta sums add-to-cart, initiate-checkout, purchase, and more — you can see exactly which figure matches, instead of chasing a phantom discrepancy. #### Metrics that say when they don't apply A traffic, awareness, engagement or link-click campaign earns no revenue, so its ROAS is `0` by design — not a sign the account is failing. `get_meta_campaign_performance` labels the numbers accordingly instead of leaving your AI client to guess: * The **Overall ROAS** row reads **Not applicable** on those accounts, with a line underneath naming the objectives it's based on and the metric that does apply. * Your account's **primary KPI is named** — cost per conversion, cost per install, CPC, CPM, cost per video view — so the agent leads with the number your objectives are actually measured on. * **Lead-gen, messaging, and app accounts** are treated as conversion accounts that carry no revenue, and measured on cost per conversion or cost per install. They are never described as having broken tracking. * If Meta never recorded an objective for your campaigns, you're told that rather than assumed to be a traffic account. The in-chat dashboard tiles carry the same labels, so the widget and the written answer can't disagree. > [!NOTE] > > **Video completion metrics.** View-through rates at 25%, 50%, 75%, and 100% watched were being recorded as `0` on every account — Adspirer was reading the wrong part of Meta's response. Newly collected data is correct. Periods that were already collected before the fix stay at zero until they are re-collected, so a video campaign from earlier this summer can still look flat when you look back at it. Campaign reads also return **`advantage_state_info`** and **`bid_strategy`**, so you can ask whether Advantage+ is on for a campaign and what it's bidding toward without opening Meta Ads Manager. **Audience segments are ranked honestly too.** `analyze_meta_audiences` reports the metric it actually ranked on (ROAS where you track conversion value, CTR where you don't), excludes Meta's `Unknown` demographic bucket from best/worst rankings — it isn't targetable and its ratio compares two different populations — and only tells you to scale a segment when that segment has the volume to support the claim. `Unknown` still appears in the age and gender breakdowns as a measured fact. #### Wasted spend on a lead-gen campaign `analyze_meta_wasted_spend` picks its yardstick from the **campaign's objective**, not from whether any conversion value happens to sit against the campaign. A lead, messaging, or talent-lead campaign is measured on cost per lead even in a mixed account where a stray purchase value has drifted in — the case that used to get a working lead campaign reported as losing money at `0.00x` ROAS. A lead campaign with zero recorded leads is still reported as a loss, because that spend bought nothing. It is not reported as a ROAS verdict: the row reads *spend with no leads recorded (ROAS does not apply to this objective)*, and the next step offered is to confirm your lead tracking rather than to pause the campaign. Lead campaigns that are converting get their own table, sorted by cost per lead, with no ROAS column at all. > [!TIP] > > If a lead campaign shows zero leads and you know it is producing them, the problem is almost always attribution rather than delivery — the Pixel event or lead form that records the lead isn't the one Meta is reporting. Ask Adspirer to check which conversion events the account is recording before changing any budget. #### Checking a campaign you launched today `get_meta_campaign_details` reports on the last 7 days when you don't name a window. Meta's `last_7d` **excludes today**, so a campaign created today used to have a reporting window containing none of its life — and came back as no delivery while it was already spending. A campaign created within the last seven days now defaults to its own run so far: creation date through today. An established campaign still defaults to the last 7 days. Either way you can name the window yourself with `start_date` and `end_date`, or with `date_preset` (`last_7d`, `last_14d`, `last_30d`, `last_90d`, or `maximum` for lifetime to date) — and the window is honoured whether or not you asked for the full ad set and ad hierarchy. Check a campaign you just launched. I launched a Meta campaign today. Is it actually delivering, and what has it spent? #### Campaigns left out of a budget recommendation `optimize_meta_budget` doesn't reallocate against campaigns with less than a week of data — there isn't enough signal to move money on. Those campaigns now appear in the answer under **Constraints Applied**, named, with the reason and the number of days they do have, instead of quietly not being in the recommendation. If every campaign in the account is that young, you get a provisional note saying so rather than a reallocation presented as a finding. The other constraints the optimizer applied — minimum daily budget and the maximum change it allowed itself per campaign — are listed alongside. ### Targeting & Research * `search_meta_targeting` — Find audiences by interests, demographics, behaviors * `browse_meta_targeting` — Explore Meta's targeting categories * `list_meta_custom_audiences` — View existing custom audiences (database lists, lookalikes, website, engagement) **Searching behaviors returns matches, not the whole catalog.** Meta's endpoint for browsing behaviors accepts a search term and a result limit and then ignores both, so a search for "engaged shoppers" used to come back with all 285 behaviors Meta publishes — *Facebook access (OS): Windows 7* included. `search_meta_targeting` pulls the category once and filters it itself, matching your term against each behavior's name, description, and category path, and returning the number of results you asked for. A term that matches nothing returns an empty result rather than everything. Interest search uses a different Meta endpoint and was never affected. ### Location & geo targeting Geo targeting is set as part of campaign and ad-set creation — you describe it in plain language and Adspirer builds the correct Meta targeting: * **Cities, regions, ZIP/postal codes, and countries**, including **city + radius** ("everyone within 20 miles of Austin"). Multiple cities, each with its own radius, work in a single ad set. * **Location reach modes** — control *who* in a location you reach: people who **live** there, were **recently** there, or are **traveling to / interested in** it. * **Safer edits** — when you change an ad set's targeting with `update_meta_ad_set` or `update_meta_catalog_ad_set`, whatever you send **merges onto the existing targeting** rather than replacing all of it, so an age-only or location-only edit doesn't wipe your audiences and placements. Each key you send replaces that whole key; to clear one, send it with an empty value. Omitting it keeps it. Local Meta campaign with city + radius targeting. Create a Meta image campaign targeting people within 15 miles of downtown Denver who live in the area (not just visitors). Budget \$25/day. ### European Union (EU/EEA) targeting — DSA disclosure The EU **Digital Services Act (DSA)** requires every ad set that reaches an EU/EEA country to declare who the ad is for. When you create or update an ad set that targets the EU/EEA, supply: * `dsa_beneficiary` — the person or organization the ad benefits (required for EU/EEA-targeted ad sets) * `dsa_payor` — the entity paying for the ad (optional; defaults to the beneficiary) These fields are sent **only** when an ad set actually targets the EU/EEA — non-EU ad sets are unaffected (Meta rejects DSA fields on them). Without a beneficiary, Meta blocks EU-targeted ad sets, so Adspirer asks you for one up front instead of letting the launch fail. ### Special Ad Categories Meta restricts ads about **housing, employment, credit, and social issues, elections or politics**. A campaign in one of these categories declares two things: the category, and the **country the campaign runs in** — which Meta treats as a separate decision from your targeting. Say what the campaign is for and Adspirer sets the category (`HOUSING`, `EMPLOYMENT`, `CREDIT`, or `ISSUES_ELECTIONS_POLITICS`), then fills the country in from the campaign's own target locations. A housing campaign aimed at Brazil declares Brazil. A special-ad-category campaign targeting a country other than your own. Create a Meta image campaign for a housing listing, targeting Brazil, \$30/day. Set `special_ad_category_country` yourself in two cases: * **Your targeting names no country** — only cities, regions, or ZIP codes. There's nothing to read a country from, so give the ISO country codes directly: `['BR']`, or `['US', 'CA']` for a campaign running in both. * **The declared country differs from the targeting** on purpose. Adspirer never guesses a country. If it can't derive one and you haven't given one, it sends the category alone and lets Meta say what it wants. > [!NOTE] > > Before 20 September 2026 the country was never sent at all, so Meta fell back to your ad account's own country and rejected any special-ad-category campaign targeting elsewhere — *"the locations are not in the countries selected for Special Ad Categories"*. If you gave up on one of these campaigns, it will run now. Campaigns with no special ad category are unaffected: the field isn't sent. ### Campaign Creation * `select_meta_campaign_type` — Choose between Image, Video, or Carousel based on your creative * `discover_meta_assets` — Check if you have existing creatives in Meta * `validate_and_prepare_meta_assets` — Verify images/videos meet Meta's requirements (dimensions, file size, aspect ratio). For a single image it returns an image hash; pass that as `existing_image_hash` to `create_meta_image_campaign` * `create_meta_image_campaign` — Launch single-image campaigns (supports lifetime budgets, end dates, placement controls) * `create_meta_video_campaign` — Launch video campaigns (supports lifetime budgets, end dates, placement controls) * `create_meta_carousel_campaign` — Launch multi-card carousel campaigns (supports lifetime budgets, end dates, placement controls) * `create_meta_dco_ad` — Create dynamic creative optimization (DCO) ads — supply multiple headlines and body texts and Meta mixes-and-matches them; Adspirer auto-enables dynamic creative on the target ad set for both image and video * `duplicate_meta_campaign` — Duplicate an existing campaign with optional modifications ### A new campaign is created paused, at every level Every campaign Adspirer creates starts paused, and so do its ad set and its ad. The create response now says so at each level: ``` Campaign: PAUSED · Ad set: PAUSED · Ad: PAUSED (in Meta review) ``` Meta will review a brand-new ad, and may email you about it, while all three are still paused — which reads like the campaign is about to start spending. It isn't. **Nothing delivers or spends until you set the campaign to Active**, whatever the review says, and the note now shipped with every image, video, and carousel create response says exactly that. Start a campaign you've reviewed. Set my new Meta campaign to active ### Start and stop times use your account timezone Meta reads a date and time with no timezone attached as **UTC**. Left alone, that means an advertiser in Los Angeles asking a campaign to stop at `2026-09-30T23:59:59` had it stop at 5 PM on the 30th, and a dated start ran — and spent — hours before it was meant to be live. Adspirer attaches your **ad account's own timezone** to any start, end, or stop time you give without one, daylight saving handled correctly for the date in question. It applies on every path that sets one: campaign and ad-set creation, all five ad types including catalog ads, and every update tool. A value that already carries an offset (`-07:00`), a `Z`, a Unix timestamp, or a bare date with no time is passed through exactly as you gave it. Update responses echo the time that was **applied**, offset included, so you can read back what Meta stored rather than the string you typed. This is the fastest way to confirm a flight end date landed where you meant it. > [!NOTE] > > `update_meta_campaign` changes the **campaign's** stop time. Ad sets keep their own end times — setting a campaign to stop on the 30th does not stop an ad set scheduled to run past it. Update the ad set with `update_meta_ad_set` if that is what you meant. ### Choosing a Facebook Page Every Meta ad runs from a Facebook Page. Which one depends on how many your ad account can promote: * **One promotable Page** — Adspirer uses it and never asks. Any Instagram account linked to that Page is picked up automatically too. * **Two or more Pages** — Adspirer stops before creating anything and lists them by name and ID so you choose. Meta publishes no "default Page" and returns them in no meaningful order, so guessing would mean running your ad under a brand you didn't ask for. It won't guess the Instagram account in that case either. * **No promotable Page** — unchanged: **"No Facebook Pages found linked to this ad account. Please link a Facebook Page in Meta Business Manager."** Name the Page you want with `facebook_page_id` on any create or add call and Adspirer never asks. To see your options first, use `list_meta_pages`. Pick the Page before you launch. Which Facebook Pages can I run Meta ads from? Then create a \$20/day image campaign from the second one. This applies to image, video, carousel, and Advantage+ Catalog creation, and to `add_meta_ad_set` and `add_meta_ad`. Updating, pausing, resuming, and duplicating are unaffected — those act on an ad that already has its Page. ### Several ads with multiple text variations in one ad set Give a single-image or single-video ad more than one primary text or headline and Meta tests the combinations for you. You can now build **several of those ads inside one ad set**. Previously a multi-text ad was created as Dynamic Creative, and Meta caps a Dynamic Creative ad set at one ad — so the second one failed with *"You can only have one ad in a dynamic creative ad set"* (error `1885553`). Adspirer now builds them as Meta's **Flexible** ad format instead. A Flexible ad is an ordinary ad, so an image ad with three headlines, a video ad with two, and a plain single-text ad can all sit in the same ad set and run against each other. Multiple multi-text ads in one ad set. In my existing Meta ad set, add an image ad with three primary texts and two headlines, then add a second image ad with a different image and its own three primary texts. Two things are deliberately unchanged. **Explicit Dynamic Creative still works the way it did** — `create_meta_dco_ad`, and `is_dynamic_creative` on `add_meta_ad_set`, still produce a Dynamic Creative ad set with its one-ad limit, which is what you want when you specifically want Meta's DCO. And **on-platform lead-form ads** keep the previous shape, so multi-text instant-form ads behave exactly as before. `add_meta_ad` also used to reject multi-text ads outright with *"object\_story\_spec is malformed"* (error `1443048`). That path works now, and a multi-text ad pointed at a lead form carries the form through. ### App install campaigns App-promotion campaigns need the numeric **Facebook App ID** — not an iOS bundle ID (`com.example.app`) and not an Android package name. `list_meta_promotable_apps` returns the apps your ad account is allowed to promote, each with that App ID and the App Store / Google Play URLs Meta already holds, so you never have to go looking for them. Apps with no mobile store listing are returned separately with the reason. Adspirer derives the **operating system from the store URL** and targets it for you — App Store means iOS, Google Play means Android — and constrains the ad set to mobile devices, since an app install can't be fulfilled on desktop. Without that, Meta rejects the ad set with *"Mobile Targeting Mismatch."* This applies to image, video, and carousel campaigns, to `add_meta_ad_set`, and to `update_meta_ad_set` when you repoint an ad set at an app on the other platform. Pass `user_os` to override the derived value. If your override contradicts the store URL, Adspirer stops and tells you, instead of sending Meta the combination it will reject. Launch a Meta app install campaign without hunting for IDs. Which mobile apps can I promote on Meta? Then set up an app install campaign for the iOS one at \$30/day. ### Engagement campaigns An engagement campaign buys reactions, comments, shares, and saves on a Page post. Every attempt to create one used to fail at Meta with: > Performance goal isn't available: You can't use the selected performance goal with your campaign objective (error `100`, subcode `2490408`.) Nothing you passed was wrong. Meta needs an engagement ad set to say **where** the engagement happens, Adspirer left that blank, and Meta rejects post engagement without it. Adspirer now sets the destination to the post itself, so the campaign creates. It applies to `create_meta_image_campaign`, `create_meta_video_campaign`, `create_meta_carousel_campaign`, and `add_meta_ad_set`. An engagement ad set promotes a **Page's** post, so it needs a Facebook Page — the same one [chosen the usual way](#choosing-a-facebook-page). Pass `destination_type` yourself and your value wins; messaging campaigns that send people to WhatsApp, Messenger, or Instagram Direct keep their own destination. Traffic, leads, sales, and awareness campaigns are untouched. Launch an engagement campaign on a Page post. Create a Meta engagement campaign at \$25/day promoting my latest Page post. ### Catalog & commerce ads (Advantage+ Catalog / Dynamic Product Ads) Connect a product **catalog** you already manage in Meta Commerce Manager (or synced from Shopify, WooCommerce, or another store platform) and Adspirer builds **dynamic product ads (DPA)** — Meta pulls each product's image, name, and price straight from the catalog and renders the ad automatically. This is how e-commerce advertisers run **prospecting** (show relevant products to cold audiences) and **retargeting** (re-show the exact products a visitor viewed or added to cart) at scale without hand-building an ad per SKU. * `list_meta_catalogs` — List the product catalogs available to your ad account * `list_meta_products` — Browse the products inside a catalog * `list_meta_product_sets` — View existing product sets (targetable subsets of a catalog) * `create_meta_product_set` — Create a product set with filter rules (e.g. "best sellers under \$50") * `compare_meta_catalog_product_sets` — Compare performance across product sets to find your winners * `validate_catalog_readiness` — Pre-flight check that tells you whether your catalog + recent pixel data can support **retargeting** (needs view/add-to-cart/purchase events) or only **prospecting** — before you spend. A pixel that fires only `InitiateCheckout` or `AddToWishlist` is reported as **limited**: retargeting works, but the audience will be small, so prospecting leads * `create_meta_catalog_campaign` — Launch an Advantage+ Catalog campaign (prospecting or retargeting), created **PAUSED** * `add_meta_catalog_ad_set` — Add a catalog ad set (audience, budget, retargeting window) * `add_meta_catalog_ad` — Add a catalog ad (creative format + product set) * `update_meta_catalog_campaign` — Change catalog-campaign budget, status, or settings * `update_meta_catalog_ad_set` — Update catalog ad-set targeting, budget, or retargeting window * `update_meta_catalog_ad` — Update catalog ad creative or product set * `analyze_meta_catalog_performance` — Product-level performance across the catalog * `get_meta_product_performance` — Per-product spend, sales, and ROAS — see which SKUs actually sell * `detect_meta_catalog_waste` — Flag products burning budget with no return * `diagnose_meta_catalog_funnel` — Walk the catalog funnel (impressions → view → add-to-cart → purchase) to find where it leaks > [!NOTE] > > Adspirer manages the **ads** on a catalog you've already built in Meta Commerce Manager (or synced from your store platform) — it doesn't create or edit the product feed itself. Set the catalog up once in Commerce Manager, then create, target, and optimize the campaigns with your AI assistant. Catalog campaigns are created **PAUSED** so you can review before spending. ### Lead generation * `list_meta_lead_forms` — View lead forms configured in your ad account * `get_meta_lead_form_submissions` — Pull lead submissions from a specific form ### Account & pixel management * `list_meta_pages` — View every Facebook Page that can run ads on the ad account, with any linked Instagram account * `list_meta_instagram_accounts` — View connected Instagram accounts * `list_meta_pixels` — View Meta Pixels configured in your ad account **Passing a pixel on a non-conversion campaign.** Traffic, awareness, and engagement campaigns don't optimize toward a pixel event — but you often still want the events recorded, so you can see what the traffic did later. Give one of those campaigns a `pixel_id` and Adspirer now attaches the pixel as ad-level tracking, so Website Events show up in Meta reporting. Before, the pixel was accepted and then quietly dropped, and the events never turned on. Conversion objectives are unchanged: the pixel is the optimization target there, and it always worked. ### Optimization * `optimize_meta_budget` — Reallocate budget based on ROAS or CPA performance * `optimize_meta_placements` — Shift spend to best-performing placements (Feed, Stories, Reels, etc.) ### Ad set & ad management * `add_meta_ad_set` — Add ad sets to existing campaigns (supports lifetime budgets, end dates, placements, multi-advertiser opt-out) * `add_meta_ad` — Add ads to existing ad sets * `update_meta_campaign` — Change budgets, bids, or targeting, including the campaign's **bid strategy** (`LOWEST_COST_WITHOUT_CAP`, `LOWEST_COST_WITH_BID_CAP`, `COST_CAP`, `LOWEST_COST_WITH_MIN_ROAS`). The capped strategies need a bid cap on the ad sets first — set `bid_amount` via `update_meta_ad_set` or Meta rejects the change * `update_meta_ad_set` — Update ad set budgets, targeting, or schedule * `update_meta_ad` — Update ad creative or status * `pause_meta_campaign` — Stop campaigns or ad sets * `resume_meta_campaign` — Set a paused campaign back to ACTIVE. It only delivers if it also has an active ad set and ad; if nothing delivers, check them with `list_meta_ad_sets` * `list_meta_campaigns` — List all campaigns with status and budget * `get_meta_campaign_details` — Detailed campaign info * `list_meta_ad_sets` — List ad sets in a campaign * `list_meta_ads` — List ads in an ad set ## Campaign Creation Workflow Meta campaigns follow a 6-step workflow. Skip steps and the campaign will fail validation. ``` 1. get_connections_status ↓ (verify you're managing the right Meta account) 2. search_meta_targeting ↓ (find your target audience) 3. select_meta_campaign_type ↓ (image, video, or carousel?) 4. discover_meta_assets ↓ (check existing creatives) 5. validate_and_prepare_meta_assets ↓ (verify asset URLs meet Meta requirements) 6. create_meta_*_campaign ↓ (image/video/carousel — campaign created PAUSED) ``` ## Example Prompts ### Analyze Performance Pull Meta Ads metrics and flag underperforming campaigns. Pull my Meta Ads performance for the last 30 days. Show spend, conversions, CPA, and ROAS. Highlight any campaigns with ROAS below 2.0. ### Detect Creative Fatigue Find fatigued creatives with declining click-through rates. Check my Meta campaigns for creative fatigue. Find ads that have been running for 14+ days with declining CTR. Recommend which creatives to refresh. ### Create an Image Campaign Meta image campaign with creative validation and audience targeting. Create a Meta image campaign: * Product: Organic skincare line for women 25-45 * Target: Women interested in clean beauty, sustainability, wellness * Budget: \$30/day * Creative: \[provide Google Drive link to your image] * Objective: Website conversions (Add to Cart) Validate the creative first, then build the campaign. ### Optimize Placements Compare CPA across Feed, Stories, Reels and recommend shifts. Analyze my Meta ad placements for the last 14 days. Which placements have the best CPA? (Feed, Stories, Reels, etc.) Recommend budget shifts to maximize conversions. ### Audience Analysis Audience breakdown by demographics and interest-based ROAS. Analyze my Meta audiences. Which age groups and genders convert best? What interests correlate with higher ROAS? Show me a breakdown table. ### Launch an Advantage+ Catalog (Dynamic Product Ads) campaign Check catalog readiness, then launch a retargeting DPA campaign from your product feed. List my Meta product catalogs and check whether my catalog is ready for retargeting. If it is, create an Advantage+ Catalog retargeting campaign for my "Best Sellers" product set at \$40/day, targeting people who viewed or added to cart in the last 14 days. Leave it paused so I can review before launch. ## Creative Assets: What You Need to Know Adspirer does NOT generate images or videos. You provide the creative URLs. ### Supported Asset Sources * Google Drive (public or shared links) * Dropbox (public links) * Amazon S3 (public URLs) * Any publicly accessible image/video URL ### Meta's Creative Requirements The `validate_and_prepare_meta_assets` tool checks these automatically: * **Image ads:** 1080x1080px minimum, JPG or PNG, under 30MB, 1:1 or 4:5 aspect ratio * **Video ads:** 1080x1080px minimum, MP4 or MOV, under 4GB, 1:1 or 4:5 or 9:16 aspect ratio, 1-240 seconds * **Carousel ads:** 2-10 cards, each 1080x1080px, JPG or PNG * **Text limits:** Primary text 125 chars (recommended), headline 27 chars, description 30 chars Validating a **carousel** returns the uploaded image hash **for each card**, and names `create_meta_carousel_campaign` as the next step along with the fields it wants per card: `image_hash`, `landing_page_url`, and `headline`. It used to print an `Asset Bundle ID` of `None` — carousels don't have one — and point you at `create_meta_image_campaign`, which is not the tool that builds a carousel. ### How video uploads work You give Adspirer a video URL and **Meta fetches the file from that URL itself**. The file is never downloaded and re-uploaded in between, so a 1 GB video is no slower and no more likely to fail than a 20 MB one. `create_meta_video_campaign`, `add_meta_ad`, and `add_meta_ad_set` all work this way. The one requirement that follows from it: **the URL must be reachable from the public internet.** A Google Drive or Dropbox link shared with "anyone with the link" works. A private link, or one behind a sign-in, does not — Meta can't open it. If Meta can't fetch the file, Adspirer falls back to fetching and pushing it itself. > [!NOTE] > > Large videos used to be downloaded in full before being sent on, which is why they returned `HTTP 503` or timed out. Fixed **August 22, 2026** — if a big video ad failed on you before then, retry it as-is. ## Budget Guidelines > [!NOTE] > > **Budgets and bids are in your ad account's own currency, as a decimal — not cents, and not converted to USD.** For a 20/day budget, send `20`. Adspirer converts to Meta's internal unit for you. > > Descriptions on these fields previously said "cents", which was wrong. An assistant that followed them sent `2000` for a 20/day budget and got a 100x budget. If you set a Meta budget or bid through Adspirer before August 11, 2026, check the value that actually landed. ### Whole-unit currencies (yen, won, and nine others) Meta expects budgets in each currency's smallest unit, and eleven currencies have no smaller unit — the amount *is* the unit. Adspirer used to apply the two-decimal multiplier to every currency, so on one of these accounts **a budget reached Meta 100× larger than you asked for**: a ¥20,000 daily budget was sent as ¥2,000,000. Because the display side divided by the same 100, the number read back correctly and the error stayed invisible. Fixed on both sides as of **August 18, 2026**. What you type is what Meta receives, and budgets, bids, and remaining spend now display with the real conversion and the real symbol — `¥20,000`, not `$200`. > [!WARNING] > > **Billing in one of these currencies? Check your live budgets.** Any Meta budget or bid you set through Adspirer before August 18, 2026 may be 100× too high. Review them in Adspirer or Meta Ads Manager and correct anything that looks wrong. > > **CLP · COP · CRC · HUF · IDR · ISK · JPY · KRW · PYG · TWD · VND** > > Accounts billing in USD, EUR, GBP, or any other currency with cents were never affected. Nothing changes in how you ask. Give the amount in your account's currency either way — `20000` for a ¥20,000 daily budget — and Adspirer applies whichever multiplier Meta specifies for that currency. Budget validation follows the same rule, so a legitimate budget on a yen or won account is no longer rejected for being "too large". * **Minimum:** \$5/day per ad set (Meta's requirement) * **Recommended:** \$20+/day for meaningful data * **Testing:** Start with \$30/day split across 2-3 ad sets to find winners * **Scaling:** Once you find ROAS above 3.0, increase budget 20-30% every 3 days ## Best Use Cases for Meta Ads * **E-commerce:** Visual products (fashion, home goods, beauty) — and with **Advantage+ Catalog / dynamic product ads**, show the exact SKUs from your feed to the right shopper automatically * **Demand generation:** Reach cold audiences with interest-based targeting * **Retargeting:** Re-engage website visitors and cart abandoners — including **catalog retargeting** that re-shows the precise product someone viewed (also see [Google Display Ads](/docs/ad-platforms/google-display-ads) for retargeting across the open web) * **Video storytelling:** Brand awareness campaigns with Reels or Stories * **Lead generation:** On-platform forms (though LinkedIn often performs better for B2B) ## Troubleshooting ### "Ad account not connected" error Re-authenticate your Meta Business Manager: ``` Connect my Meta Ads account ``` Make sure you select the correct ad account during OAuth. If you manage multiple accounts, you may need to reconnect with admin permissions. ### "Asset validation failed" error Common causes: * Image/video URL is private (not publicly accessible) * Wrong dimensions (Meta requires minimum 1080x1080px) * File too large (30MB for images, 4GB for video) * Unsupported format (use JPG/PNG for images, MP4/MOV for video) Run validation separately to diagnose: ``` Validate this Meta creative: [your URL] ``` ### "Campaign creation failed" error Most common reason: skipping workflow steps. Meta campaigns require all 6 steps in order. If you jump straight to `create_meta_image_campaign` without running `validate_and_prepare_meta_assets` first, it will fail. Adspirer now catches the most common failure causes *before* they reach Meta and explains them in plain language: * **Missing pixel on a conversion objective** — a conversion-optimized ad set needs a Meta Pixel (or custom conversion). Adspirer flags this up front instead of letting Meta return the cryptic "promoted object fields missing." Pass a pixel, or pick a non-conversion objective. Use `list_meta_pixels` to find yours. * **Carousel cards** — each card needs an image, a headline, and a landing-page URL (a carousel-level URL covers cards that don't set their own). Adspirer validates every card before submitting and accepts the same Meta image hash its asset discovery returns, so you can build carousels straight from creatives already in your account. Carousel cards take that hash under the key `image_hash`; single-image campaigns call it `existing_image_hash`. * **Wrong account** — if the campaign, ad set, or ad you referenced lives in a different one of your ad accounts, Adspirer names the right account instead of failing deep inside Meta. See [Asset handling across ad accounts](#asset-handling-across-ad-accounts). * **"Mobile Targeting Mismatch" on app campaigns** — fixed. Adspirer sets the ad set's OS targeting from your app's store URL. See [App install campaigns](#app-install-campaigns). * **"The locations are not in the countries selected for Special Ad Categories"** — fixed. A housing, employment, credit, or politics campaign now declares the country it runs in, read from your targeting, so it no longer has to match your ad account's country. See [Special Ad Categories](#special-ad-categories). * **"Performance goal isn't available: You can't use the selected performance goal with your campaign objective"** — fixed. Engagement campaigns now carry the on-post destination Meta pairs with post engagement. See [Engagement campaigns](#engagement-campaigns). * **"No payment method is set" on an account that has a card** — fixed. The precheck used to read a Meta field that stays empty until the account has actually spent, so it false-blocked brand-new funded accounts on their very first campaign — and pushed the real blocker, usually a missing promotable Page, down the list behind it. It now reads Meta's `HAS_VALID_PAYMENT_METHODS` capability, and doesn't block at all if Meta's answer comes back incomplete. If you're using [agent skills](/docs/agent-skills/overview), the AI enforces the correct workflow automatically. ### Checking what an update actually applied Every Meta update tool — campaign, ad set, ad, and the catalog tools — echoes each field it changed **together with the value it applied**, and asks you to review before moving on. The values are live at that point. Money is rendered in the ad account's own currency, so an Australian account reads `A$2,000.00` and a Japanese one reads `¥20,000` — with the right number of decimals for the currency, and the right conversion behind it. That is the fastest way to catch a budget that landed wrong: read the number back, don't assume the field name means the value was right. Reading a campaign back tells you the same story. `list_meta_campaigns`, `get_meta_campaign_details`, and `list_meta_ad_sets` render budgets, bids, and remaining spend in the account's own currency rather than assuming dollars. ### Meta is holding a security check on the account Meta error code **31**, subcode **3858385** — *"Please authenticate your account"* — stops the API from publishing or editing ads, while the account keeps working normally if you build the ad by hand in Ads Manager. **Reconnecting Adspirer does not clear it.** The check is on the Facebook user that connected the account, not on the connection. To clear it: **1. Open Ads Manager with no VPN** Go to [Meta Ads Manager](https://business.facebook.com/adsmanager) and select the affected ad account. A VPN or proxy can make Meta refuse the check outright. **2. Start Authentication under Billing and payments** Open **Billing and payments** and click **Start Authentication**. Meta emails you a code. **3. If there is no button, trigger the prompt** Open a private or incognito window, edit any existing ad's name, and click **Publish**. Meta raises the authentication prompt on the publish attempt. **4. Turn on two-factor authentication** Then check [Account Quality](https://www.facebook.com/accountquality) for anything else outstanding against the account. **5. Retry once, then wait** Ask Adspirer to retry the campaign. If it still fails, wait 24 to 48 hours before trying again — Meta's side takes that long to settle, and repeated attempts don't speed it up. ### Reading a Meta error Adspirer can't explain When Meta rejects something for a reason Adspirer can't translate, the error now ends with a reference line carrying Meta's own identifiers — the error **code**, the **subcode**, and the **`fbtrace_id`**. Quote all three to Meta support. The `fbtrace_id` identifies your exact failing request in Meta's logs and is the first thing they ask for; without it there is nothing for them to look up. Every Meta write path returns them, so it doesn't matter which call failed. An error that Meta sends without identifiers still reads as plainly as it did before — there's no reference line to add. ### Creative fatigue detection not working The tool needs at least 14 days of data per ad. If your ads are newer, it can't detect fatigue yet. Wait until ads have run for 2+ weeks. ## FAQ > **Can I manage Instagram ads separately from Facebook?** > > No. Meta treats Facebook and Instagram as placement options within the same campaign. When you create a Meta campaign through Adspirer, you choose placements (Feed, Stories, Reels, etc.) that span both platforms. You can't create Instagram-only campaigns through the API. > **Does Adspirer generate ad creatives?** > > No. Adspirer manages campaigns, not creative production. You provide image/video URLs. For AI-generated creatives, use tools like Midjourney, DALL-E, or Runway, then upload to Google Drive/Dropbox and provide the link. > **Can I A/B test creatives?** > > Yes. Create multiple ad sets with different creatives (different image URLs) but the same targeting and budget. After 7 days, use `analyze_meta_ad_performance` to see which creative wins, then pause the losers and scale the winner. > **What's the difference between Meta and Google Ads?** > > **Meta Ads:** Best for demand generation (reaching people who don't know you exist) and visual products. Interest-based targeting. Lower intent but cheaper clicks. > > **[Google Ads](/docs/ad-platforms/google-ads):** Best for demand capture (reaching people actively searching for solutions). Keyword-based targeting. Higher intent but more expensive clicks. > **Do I need to build a product feed to run Catalog / dynamic product ads?** > > You build the **catalog** once in Meta Commerce Manager — or sync it automatically from Shopify, WooCommerce, or another store platform — and Adspirer manages the **ads** on top of it. Adspirer reads your catalogs and product sets, checks whether your pixel data can support retargeting (`validate_catalog_readiness`), and creates/optimizes Advantage+ Catalog campaigns. It doesn't edit the product feed itself. Once the catalog exists, you can run everything else — prospecting, retargeting, product-set testing, per-SKU performance — from your AI assistant. > **How much does Adspirer cost for Meta Ads?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical Meta campaign creation uses 4-6 tool calls. See [full pricing](https://www.adspirer.com/pricing). ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [Meta Ads + AI Integration](https://www.adspirer.com/integrations/meta-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your Meta account (\$39 one-time) # TikTok Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/tiktok-ads Create and manage TikTok ad campaigns with AI — 37 tools for In-Feed video, Spark Ads, pixel and video discovery, targeting, and performance analytics. # TikTok Ads Integration Reach TikTok's billion-plus users with AI-powered campaign management. Create In-Feed video and Spark ads, manage campaigns at every level, and analyze performance with 37 specialized tools. Includes rich targeting (interests, behavioral keywords, device, carrier, language), Layer-1 validity checks that catch errors before they reach TikTok's API, and atomic rollback on creation failures. ## Prerequisites > [!NOTE] > > * TikTok Ads Manager account ([create one here](https://ads.tiktok.com)) > * A TikTok Business Center account with billing enabled > * Admin access to the ad account you want to manage > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting TikTok Ads Once you've set up Adspirer with your AI client, connect TikTok: 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my TikTok Ads account" 3. Adspirer opens your browser for OAuth authorization 4. Sign in to TikTok Business Center and select the ad account you want to manage 5. Approve permissions (read campaign data, create ads, manage budgets) Verify the connection: ``` Check my connected ad platforms ``` You should see your TikTok ad account listed with advertiser name, account ID, and active status. ## What You Can Do (37 Tools) ### Planning & Objective Selection * `explain_tiktok_objective` -- Given your goal (leads, sales, traffic, app installs, video views), returns the correct TikTok campaign objective, recommended ad format, and compatibility constraints. Run this first if you're unsure which objective to use. ### Performance Analysis * `get_tiktok_campaign_performance` -- Campaign summary with TikTok-specific video and engagement metrics * `get_tiktok_ad_performance` -- Ad-level analysis with hook rate, video completion, and engagement * `analyze_tiktok_wasted_spend` -- Waste detection graded on ROAS or cost per lead, depending on the campaign's objective, with campaign status awareness * `optimize_tiktok_budget` -- Budget allocation recommendations based on performance * `detect_tiktok_creative_fatigue` -- Hook rate decline as the primary fatigue signal * `explain_tiktok_anomaly` -- Diagnose sudden changes in TikTok campaign performance * `get_tiktok_audience_insights` -- Age/gender breakdown with CPA ranking * `analyze_tiktok_geo_performance` -- Country-level performance analysis #### Lead-gen campaigns and unrated rows Waste detection chooses its yardstick from the **campaign's objective**. A lead generation campaign is measured on cost per lead, so it no longer falls through to the ROAS branch and gets reported as losing money at `0.00x` because one stray conversion value landed against it. App-install campaigns stay in the non-conversion bucket, where a ROAS verdict was never meaningful. A lead campaign with zero recorded leads is still reported as a loss, with the Severity column reading `unrated — no leads recorded` and the suggested step being to confirm lead tracking rather than to pause. Where there genuinely isn't enough data to grade a campaign, the column says `unrated (not enough data)` -- it used to print Adspirer's internal `insufficient_signal` marker there, which read like a severity level. ### Creative & Pixel Discovery * `list_tiktok_ad_videos` -- List the videos already in your TikTok library with the `video_id` for each, so a second ad from the same video doesn't mean a second upload * `list_tiktok_pixels` -- List your TikTok Pixels with the **numeric** `pixel_id` TikTok requires and the exact `optimization_event` values each pixel supports. Pixels with no events configured are flagged as unusable for conversion optimization. * `list_tiktok_lead_pages` -- List your TikTok Instant Forms with the `page_id` needed to attach one to a lead generation ad, and whether each form is `PUBLISHED`. Draft forms can't be used. * `discover_tiktok_assets` -- Browse the images in your TikTok Asset Library for reuse * `validate_and_prepare_tiktok_assets` -- Verify video files meet TikTok's requirements (9:16 vertical, 5-60 seconds, MP4/MOV) * `upload_tiktok_images` -- Upload images to TikTok Asset Library ### Campaign Creation * `create_tiktok_video_campaign` -- Launch an In-Feed video campaign (created PAUSED). Takes any of three creative sources: `video_url` (a public MP4/MOV that Adspirer uploads), `video_id` (a video already in your library), or `tiktok_item_id` (an organic post boosted as a Spark Ad). * `add_tiktok_ad_group` -- Add ad groups with full targeting to existing campaigns * `add_tiktok_ad` -- Add ads to existing ad groups (video, Spark Ads) ### Campaign Management * `list_tiktok_campaigns` -- List all campaigns with status, objective, and budget * `get_tiktok_campaign_details` -- Detailed campaign info * `update_tiktok_campaign` -- Update name, budget, budget mode * `pause_tiktok_campaign` / `resume_tiktok_campaign` -- Control campaign status * `list_tiktok_ad_groups` -- List ad groups, filter by campaign * `update_tiktok_ad_group` -- Update name, budget, targeting, schedule * `pause_tiktok_ad_group` / `resume_tiktok_ad_group` -- Control ad group status * `list_tiktok_ads` -- List ads, filter by ad group or campaign * `pause_tiktok_ad` / `resume_tiktok_ad` -- Control ad status ### Targeting & Research * `search_tiktok_targeting` -- Search interests, keywords, regions, languages, action categories, carriers, and device models. This returns the **IDs** you then target with — interest keywords, for example, are passed as `interest_keyword_ids` (numeric IDs from this search), not as plain keyword strings. ## Campaign Creation Workflow TikTok campaigns follow a 5-step workflow: ``` 1. get_connections_status ↓ (verify TikTok Ads is connected) 2. search_tiktok_targeting ↓ (find your target audience by interests, keywords, regions) 3. list_tiktok_ad_videos ↓ (reuse a video already in your library, or skip to upload a new one) 4. validate_and_prepare_tiktok_assets ↓ (verify video meets TikTok requirements: 9:16 vertical, 5-60 seconds) 5. create_tiktok_video_campaign ↓ (campaign created PAUSED — you review before launching) ``` Running a **conversions** campaign adds one step at the front: call `list_tiktok_pixels` to get the numeric `pixel_id` and a valid `optimization_event` for that pixel. There is no default event — the valid set is per-pixel, so Adspirer asks rather than guessing. ### Adding ads to existing campaigns ``` 1. list_tiktok_campaigns ↓ (find the campaign to add to) 2. add_tiktok_ad_group ↓ (create ad group with targeting) 3. add_tiktok_ad ↓ (add a video ad or a Spark Ad) ``` ## Example Prompts ### Check Performance TikTok campaign metrics with video completion analysis. Pull my TikTok Ads performance for the last 14 days. Show video views, engagement rate, conversions, and cost per conversion. Which campaigns have the best video completion rate? ### Create a Campaign TikTok In-Feed campaign with video validation. Create a TikTok campaign: * Product: Skincare brand targeting women 18-34 * Audience: Women interested in beauty, skincare, wellness * Budget: \$50/day * Creative: \[provide video URL] * Objective: Website conversions Validate the video first, then build the campaign. ### Upload and Validate Video Validate video specs for TikTok In-Feed ads. Validate this TikTok video creative: \[your video URL] Check if it meets TikTok's specs for In-Feed ads. ### Analyze What's Working Creative performance analysis with engagement metrics. Show me my TikTok campaign performance for the last 30 days. Which ad creatives have the highest engagement rate? What's my average cost per conversion across all campaigns? ## Creative Assets: What You Need to Know TikTok is a video-first platform. All campaigns require video creative. > [!WARNING] > > Adspirer does NOT generate videos. You provide video URLs from Google Drive, Dropbox, S3, or any publicly accessible link. The `validate_and_prepare_tiktok_assets` tool checks that your video meets TikTok's specifications before campaign creation. ### TikTok's Creative Requirements The `validate_and_prepare_tiktok_assets` tool checks these automatically: * **Aspect ratio:** 9:16 (vertical) -- 1080x1920px recommended * **Duration:** 5-60 seconds (9-15 seconds performs best for engagement) * **Format:** MP4 or MOV * **File size:** Under 500MB * **Resolution:** Minimum 720p (1280x720px), 1080p recommended ### Supported Asset Sources * Google Drive (public or shared links) * Dropbox (public links) * Amazon S3 (public URLs) * Any publicly accessible video URL ### Creative Best Practices * **Hook in the first 2 seconds:** TikTok users scroll fast. Grab attention immediately. * **Native look and feel:** Ads that look like organic TikTok content outperform polished commercials * **Vertical video only:** Horizontal or square videos perform significantly worse on TikTok * **Sound on:** Unlike other platforms, most TikTok users watch with sound on. Use music and voiceover. * **Short and punchy:** 9-15 seconds is the sweet spot for In-Feed ads ## Ad Formats ### In-Feed Ads TikTok In-Feed ads appear in users' For You feed and blend with organic content. They support: * **Traffic objective:** Drive users to your website or landing page * **Conversions objective:** Optimize for specific conversion events (requires a TikTok Pixel ID and `optimization_event`) * **App installs:** Drive mobile app downloads (APP\_PROMOTION objective) In-Feed ads auto-play with sound as users scroll through their feed. Users can like, comment, share, and follow directly from the ad. ### Spark Ads Boost existing TikTok organic posts as ads. Provide the `tiktok_item_id` of an organic post to promote it with paid reach while keeping all engagement (likes, comments, shares) on the original post. ### What TikTok doesn't allow Two formats you may expect can't be built through TikTok's API, so Adspirer refuses them up front rather than letting TikTok reject a half-built campaign: * **Image-only in-feed ads.** TikTok's in-feed placement requires a video creative. Images are supporting assets alongside one — `upload_tiktok_images` and `discover_tiktok_assets` produce `image_ids` you pass to a video ad. * **Carousel ads.** Build the carousel in TikTok Ads Manager, then boost that post here as a Spark Ad using its `tiktok_item_id`. ### Conversion tracking For campaigns with the `WEB_CONVERSIONS` objective (`CONVERSIONS` is still accepted as a legacy alias), you need a TikTok Pixel ID and an `optimization_event`. The `optimization_event` tells TikTok which conversion action to optimize for. Start with `list_tiktok_pixels`. It returns the **numeric** `pixel_id` — TikTok rejects the alphanumeric Pixel Code that appears in the Events Manager UI — along with the events that specific pixel actually supports. There is no default event, because the valid set differs per pixel. Common `optimization_event` values: | Value | Description | | - | - | | `COMPLETE_PAYMENT` | Purchase or payment completed | | `ON_WEB_CART` | Add to cart | | `ON_WEB_DETAIL` | View content / product page | | `ON_WEB_REGISTER` | Registration completed | | `FORM` | Form submission | | `CONVERSION_LEADS` | Lead generation | | `INITIATE_ORDER` | Checkout initiated | | `PAGE_VISIT` | Page view | | `CLICK_LANDING_PAGE` | Landing page click | | `ON_WEB_SUBSCRIBE` | Subscription signup | | `PHONE_CONNECT` | Phone call connected | | `CONSULT` | Consultation request | | `SEARCH` | Site search | | `SUBSCRIBE` | Subscribe action | | `DOWNLOAD_FINISH` | Download completed | Your pixel may not support all of these. `list_tiktok_pixels` is the authority for which ones it does. Example prompt: TikTok conversion campaign with pixel tracking. Which TikTok pixels do I have and what events does each support? Then create a TikTok campaign on the purchase pixel optimizing for add-to-cart. Budget: \$50/day, targeting women 18-34 interested in fashion. ### Lead generation There are two ways to capture leads on TikTok, and the one most campaigns use is not the one people ask for. **Website lead gen (the common path).** The ad sends people to your own landing page and a TikTok Pixel records the submission. Run `list_tiktok_pixels`, pick the pixel, and use `optimization_event=FORM`. Nothing else is required. **Instant Forms (native, hosted by TikTok).** The form opens inside TikTok, so there is no landing page and no site visit. Run `list_tiktok_lead_pages` to get the `page_id` for each form and to see which are `PUBLISHED` — TikTok refuses a draft form on a live ad. > [!NOTE] > > A lead generation ad carries **either** a landing page URL **or** an Instant Form `page_id`, never both. With an Instant Form, the form is the destination; TikTok rejects an ad that also carries a URL. TikTok also requires three things of a lead generation ad group that it will not tell you about — it reports every one of them as the same *"There was an error with the Lead Generation advertising objective"*. Adspirer sets all three for you: the ad group is promoted as lead generation rather than as a website visit, it carries a custom bid (TikTok refuses its no-bid strategy on this objective), and its placements are named explicitly rather than left automatic. Launch a TikTok lead generation campaign on an Instant Form. What TikTok Instant Forms do I have, and which are published? Then build a lead generation campaign on the published one, \$40/day, targeting the US. ### Campaign Budget Optimization (CBO) TikTok campaigns support campaign-level budget optimization via the `budget_optimize_on` parameter. CBO is on by default — set to `false` to manage budgets per ad group manually. ## Targeting Options When creating TikTok campaigns through Adspirer, you can target by: ### Demographics * **Age:** 13-17, 18-24, 25-34, 35-44, 45-54, 55+ * **Gender:** Male, Female, All * **Location:** Country, state/region, city-level targeting ### Interests & Behaviors * **Interests:** Beauty, Fashion, Food & Beverage, Technology, Fitness, Gaming, and 20+ categories * **Behavioral signals:** Video interaction patterns, content engagement history * **Device:** iOS, Android, specific device models ## Budget Guidelines * **Minimum:** \$20/day per campaign (TikTok's requirement for campaign-level budgets) * **Ad group minimum:** \$20/day * **Recommended:** \$50+/day for meaningful data collection * **Testing:** Start with \$50/day on a single ad group to gauge performance before scaling * **CPC range:** Expect \$0.50-2.00 per click (varies by industry and targeting) * **CPM range:** \$6-10 per thousand impressions ## Best Use Cases for TikTok Ads * **E-commerce:** Products that photograph/film well (fashion, beauty, gadgets, food) * **Brand awareness:** Reaching younger demographics (Gen Z and Millennials) at scale * **Product launches:** New product reveals with authentic, native-feeling video content * **App installs:** Mobile-first audience with high app download intent * **Direct-to-consumer brands:** Brands that can create authentic, engaging short-form video **Not ideal for:** B2B lead generation (use [LinkedIn Ads](/docs/ad-platforms/linkedin-ads)), high-intent search capture (use [Google Ads](/docs/ad-platforms/google-ads)), audiences over 45 (limited reach on TikTok). ## Troubleshooting ### "Ad account not connected" error Re-authenticate your TikTok Business Center account: ``` Connect my TikTok Ads account ``` Make sure you select the correct advertiser account during OAuth. If you manage multiple accounts in TikTok Business Center, you may need to reconnect and select the right one. ### "Asset validation failed" error Common causes: * Video is not in 9:16 vertical format (horizontal or square videos are rejected) * Video duration is outside 5-60 second range * File too large (over 500MB) * Unsupported format (use MP4 or MOV) * Video URL is private or not publicly accessible Run validation separately to diagnose: ``` Validate this TikTok video creative: [your URL] ``` ### "Invalid media format" or TikTok page URL error If you pass a TikTok page URL (e.g., `https://tiktok.com/@user/video/123`) as a video URL, the tool returns an error because that's a web page, not a downloadable video file. Two options: * **Spark Ads:** Use the `tiktok_item_id` parameter instead to boost the organic post as a Spark Ad * **Video ad:** Provide a direct link to the video file (MP4 or MOV) from Google Drive, Dropbox, S3, or any publicly accessible URL ### "Campaign creation failed" error Most common reason: skipping the asset validation step. TikTok campaigns require `validate_and_prepare_tiktok_assets` before `create_tiktok_video_campaign`. The validation tool uploads and processes the video in TikTok's system. On a conversions campaign, the other common cause is a pixel or an `optimization_event` TikTok won't accept. Run `list_tiktok_pixels` — it returns the numeric pixel ID and the events that pixel supports, which is usually the mismatch. If you're using [agent skills](/docs/agent-skills/overview), the AI enforces the correct workflow automatically. ### Low video completion rates Your creative may not be engaging enough for TikTok's audience. Common fixes: * Stronger hook in the first 2 seconds * Use trending sounds or music * Make it feel organic, not like a traditional ad * Shorter duration (try 9-12 seconds instead of 30+) * Test multiple video variations to find what resonates ## FAQ > **Can I create image ads on TikTok through Adspirer?** > > Not as standalone ads — that's a TikTok rule, not an Adspirer limit. TikTok's in-feed placement requires a video creative and rejects an image-only ad outright. Images work as supporting assets alongside a video: upload them with `upload_tiktok_images` (or find existing ones with `discover_tiktok_assets`) and pass the image IDs to `add_tiktok_ad` together with a `video_url` or `video_id`. > > Carousel ads have the same answer. They can't be built through TikTok's API, so build the carousel in TikTok Ads Manager and boost that post here as a Spark Ad with its `tiktok_item_id`. > **Does Adspirer generate TikTok video content?** > > No. Adspirer manages campaigns, not video production. You create videos using your preferred tools (CapCut, Canva, Adobe Premiere, or even your phone) and provide the video URL. For AI-generated video, tools like Runway, Pika, or HeyGen can help. Upload the result to Google Drive or Dropbox and provide the link to Adspirer. > **What's the difference between TikTok Ads and Meta Ads?** > > **TikTok Ads:** Video-first platform with a younger audience (Gen Z, Millennials). Content feels native and authentic. Strong for brand discovery and impulse purchases. Lower CPM but requires video creative. > > **[Meta Ads](/docs/ad-platforms/meta-ads):** Supports image, video, and carousel formats. Broader age demographics. More advanced targeting and retargeting options. Better for retargeting and full-funnel campaigns. > > Many advertisers run both: TikTok for awareness and discovery, Meta for retargeting and conversion optimization. > **Can I boost existing TikTok organic posts?** > > Yes. Spark Ads let you promote existing organic TikTok posts as paid ads. Provide the `tiktok_item_id` of the organic post when creating an ad with `add_tiktok_ad` or `create_tiktok_video_campaign`. All engagement (likes, comments, shares) stays on the original post. > **How much does Adspirer cost for TikTok Ads?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical TikTok campaign creation uses 4-6 tool calls. See [full pricing](https://www.adspirer.com/pricing). > **Is my TikTok advertising data secure?** > > Yes. Adspirer uses OAuth 2.1 authentication -- your TikTok credentials are never stored on Adspirer's servers. All connections are HTTPS-encrypted with strict security protocols. You can revoke access at any time from your TikTok Business Center. ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) * [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) * [ChatGPT Ads Integration](/docs/ad-platforms/chatgpt-ads) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [TikTok Ads + AI Integration](https://www.adspirer.com/integrations/tiktok-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your TikTok Ads account (\$39 one-time) # YouTube Ads Integration | Adspirer Source: https://www.adspirer.com/docs/ad-platforms/youtube-ads Create and manage YouTube video ad campaigns with AI: video validation, In-Feed, In-Stream, and Shorts placements, plus performance tracking. # YouTube Ads Integration Run video ads across YouTube's 2+ billion monthly users. Create campaigns that show on In-Feed, In-Stream, and Shorts placements — all managed through natural language. ## Prerequisites > [!NOTE] > > * Google Ads account with an active YouTube channel ([create one here](https://ads.google.com)) > * At least one YouTube video (public or unlisted) to use as ad creative > * Admin or Standard access to the Google Ads account > * Adspirer account connected via [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or any [supported AI client](https://www.adspirer.com/integrations) ## Connecting YouTube Ads YouTube Ads runs through Google Ads — if you've already connected Google Ads, you're ready. No separate connection needed. 1. Open your AI assistant (ChatGPT, Claude, Claude Code, etc.) 2. Say: "Connect my Google Ads account" 3. Adspirer opens your browser for OAuth authorization 4. Sign in to your Google account and select the ad account 5. Approve permissions Verify the connection: ``` Check my connected ad platforms ``` You should see your Google Ads account listed. YouTube campaign tools are available through the same connection. ## What You Can Do ### Video Validation * `validate_video` — Verify your YouTube video meets campaign requirements (privacy, duration, embeddable status) ### Campaign Creation * `create_youtube_campaign` — Create YouTube video campaigns with In-Feed, In-Stream, and Shorts placements (created PAUSED) * `select_google_campaign_type` — Choose between Search, PMax, or YouTube when the campaign type isn't specified ### Asset Management * `discover_existing_assets` — Find existing logos and images in your Google Ads account for reuse * `validate_and_prepare_assets` — Upload and validate new logo images for your campaign ### Performance & Optimization * `get_campaign_performance` — Pull metrics for YouTube campaigns (views, engagement, conversions, cost) * `list_campaigns` — View all campaigns including YouTube * `add_sitelinks` / `add_callout_extensions` / `add_structured_snippets` — Add extensions after campaign creation ## Campaign Placements YouTube campaigns use Google Ads **Demand Gen** format with YouTube-only channel controls: | Placement | Where It Shows | Format | | - | - | - | | **In-Feed** | YouTube search results and related videos sidebar | Thumbnail + text, plays on click | | **In-Stream** | Before, during, or after YouTube videos | Skippable after 5 seconds | | **Shorts** | YouTube Shorts feed | Full-screen vertical video | > [!NOTE] > > Gmail, Discover, and Display placements are **disabled** for YouTube campaigns. Your ads only show on YouTube. ## Campaign Creation Workflow YouTube campaigns follow a 6-step workflow: ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[validate_video] -->|Verify video is public/unlisted| B[discover_existing_assets] B -->|Check for existing logos| C{Logo found?} C -->|Yes| D[Use existing logo] C -->|No| E[validate_and_prepare_assets] E -->|Upload new logo| D D --> F[create_youtube_campaign] F -->|Campaign created PAUSED| G[Add extensions] G --> H[add_sitelinks + add_callout_extensions + add_structured_snippets] ``` ``` 1. validate_video -> (verify YouTube video is public/unlisted and meets requirements) 2. discover_existing_assets -> (check for existing logos in your Google Ads account) 3. validate_and_prepare_assets (if no logo found) -> (upload a square logo image) 4. create_youtube_campaign -> (campaign created PAUSED — you review before launching) 5. add_sitelinks + add_callout_extensions + add_structured_snippets -> (extensions increase ad visibility by 15-25%) 6. list_campaign_extensions -> (verify all extensions are attached) ``` ## Example Prompts ### Create a YouTube Campaign YouTube video campaign with asset discovery and extensions. Create a YouTube Ads campaign: * Product: Online cooking course, \$79 one-time purchase * YouTube video: [https://youtu.be/YOUR\_VIDEO\_ID](https://youtu.be/YOUR_VIDEO_ID) * Landing page: [https://example.com/cooking-course](https://example.com/cooking-course) * Budget: \$50/day * Target: Foodies and home cooks in the US, ages 25-54 * Validate the video first, then create the campaign with extensions ### Brand Awareness Campaign YouTube awareness campaign targeting broad audience with multiple videos. Set up a YouTube video campaign for brand awareness: * Brand: Sustainable clothing company * Primary video: [https://youtu.be/VIDEO\_ID\_1](https://youtu.be/VIDEO_ID_1) * Additional videos: [https://youtu.be/VIDEO\_ID\_2](https://youtu.be/VIDEO_ID_2), [https://youtu.be/VIDEO\_ID\_3](https://youtu.be/VIDEO_ID_3) * Budget: \$100/day * Target: Eco-conscious consumers, ages 18-44, United States and Canada * Bidding: Maximize clicks * Write compelling headlines and descriptions ### Check Performance YouTube campaign performance with engagement metrics. Pull my YouTube campaign performance for the last 30 days. Show video views, engagement rate, conversions, cost per conversion, and CTR. Which campaigns have the best view-through rate? ### Validate a Video Validate a YouTube video before campaign creation. Validate this YouTube video for a campaign: [https://youtu.be/YOUR\_VIDEO\_ID](https://youtu.be/YOUR_VIDEO_ID) Check if it meets all requirements for YouTube ads. ## Video Requirements YouTube campaigns require video creative hosted on YouTube. > [!WARNING] > > Adspirer does NOT generate videos. You provide your own YouTube video (public or unlisted). The `validate_video` tool checks that your video meets all requirements before campaign creation. ### Video Specifications The `validate_video` tool checks these automatically: | Requirement | Details | | - | - | | **Hosting** | Must be on YouTube (not Vimeo, Google Drive, etc.) | | **Privacy** | Public or Unlisted (NOT Private) | | **Duration** | Minimum 10 seconds (no maximum) | | **Embeddable** | Must be enabled in YouTube video settings | | **Maximum** | Up to 5 videos per campaign (1 primary + 4 additional) | ### Accepted URL Formats * `https://youtube.com/watch?v=dQw4w9WgXcQ` * `https://youtu.be/dQw4w9WgXcQ` * `https://youtube.com/shorts/dQw4w9WgXcQ` * Direct video ID: `dQw4w9WgXcQ` (11 characters) ## Ad Copy Requirements YouTube campaigns require headlines, descriptions, and a logo. | Element | Limit | Required | | - | :-: | :-: | | **Headlines** | 40 characters max | 1-5 required | | **Descriptions** | 90 characters max | 1-5 required | | **Long headlines** | 90 characters max | Optional (1-5) | | **Business name** | 25 characters max | Required | | **Logo** | Square (1:1) image | Required | | **Call-to-action** | Predefined options | Optional (defaults to "Learn More") | ### Call-to-Action Options `LEARN_MORE` (default), `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`, `DOWNLOAD`, `BOOK_NOW`, `CONTACT_US`, `GET_QUOTE`, `APPLY_NOW`, `WATCH_NOW`, `ORDER_NOW`, `BUY_NOW`, `SEE_MORE`, `START_NOW`, `VISIT_SITE`, `REGISTER` ## Bidding Strategies | Strategy | Best For | Requires Conversion Tracking | | - | - | :-: | | **Maximize Clicks** (default) | Most campaigns, driving traffic | No | | **Maximize Conversions** | Optimizing for signups/purchases | Yes | | **Target CPA** | Controlling cost per acquisition | Yes | ## Budget Guidelines * **Minimum:** \$15/day (YouTube campaign requirement) * **Recommended:** \$50+/day for meaningful data collection * **Testing:** Start with \$50/day on a single video to gauge performance before scaling * **CPV range:** \$0.01-0.30 per view (varies by targeting and competition) * **CPM range:** \$4-10 per thousand impressions ## Best Use Cases for YouTube Ads * **Product demos:** Show your product in action with explainer or tutorial videos * **Brand storytelling:** Build brand awareness with longer-form video content * **Retargeting:** Re-engage website visitors with video ads on YouTube (pair with [Google Display Ads](/docs/ad-platforms/google-display-ads) for cross-web retargeting) * **App installs:** Drive mobile app downloads with video creative * **Course/SaaS promotion:** Showcase features and benefits with walkthrough videos * **E-commerce:** Product showcases, unboxings, and customer testimonials **Not ideal for:** High-intent search capture (use [Google Search Ads](/docs/ad-platforms/google-ads)), B2B lead generation with precise targeting (use [LinkedIn Ads](/docs/ad-platforms/linkedin-ads)), short-form social engagement (use [TikTok Ads](/docs/ad-platforms/tiktok-ads)). ## YouTube vs Other Platforms | Feature | YouTube Ads | TikTok Ads | Meta Video Ads | | - | :-: | :-: | :-: | | Audience size | 2B+ monthly users | 1B+ monthly users | 3B+ monthly users | | Video format | Any length (10s+) | 5-60 seconds | Any length | | Best for | Demos, tutorials, brand | Viral, native, impulse | Retargeting, full-funnel | | Targeting | Google Ads targeting | Interest-based | Custom audiences, lookalikes | | Placements | In-Feed, In-Stream, Shorts | In-Feed only | Feed, Stories, Reels | | Skippable | Yes (after 5s for In-Stream) | No (swipe to skip) | No (scroll to skip) | ## Troubleshooting ### "Video validation failed" error Common causes: * Video is set to **Private** — change to Public or Unlisted in YouTube Studio * Video is shorter than 10 seconds — YouTube campaigns require minimum 10s duration * Embedding is disabled — enable embedding in YouTube video settings * Invalid URL format — use a standard YouTube URL or 11-character video ID Run validation separately to diagnose: ``` Validate this YouTube video for ads: [your YouTube URL] ``` ### "Logo required" error YouTube campaigns require a square logo image. Solutions: 1. Run `discover_existing_assets` to check if your Google Ads account already has logos 2. If no logos found, provide a square logo image URL and run `validate_and_prepare_assets` 3. Logo must be 1:1 aspect ratio (square) ### "Campaign creation failed" error Most common reasons: * Skipping video validation — always run `validate_video` before `create_youtube_campaign` * Headlines exceeding 40 characters — character limits are strictly enforced * Budget below \$15/day minimum * Landing page domain not verified in Google Ads If you're using [agent skills](/docs/agent-skills/overview), the workflow handles validation automatically. ### Low view rates Your video may not be engaging enough. Common fixes: * Stronger hook in the first 5 seconds (before users can skip) * Clear value proposition early in the video * Professional audio quality (viewers skip videos with poor sound) * Add captions — many viewers watch without sound * Test different video lengths (15s, 30s, 60s) to find what works ## FAQ > **What's the difference between YouTube Ads and Performance Max?** > > **YouTube Ads** show exclusively on YouTube (In-Feed, In-Stream, Shorts). You control the placements and the campaign focuses on video engagement. > > **[Performance Max](/docs/ad-platforms/google-ads)** runs across all Google channels including YouTube, Search, Display, Gmail, Maps, and Discover. Google's AI decides where to show your ads. PMax is broader; YouTube Ads are more targeted. > > If you want maximum reach, use PMax. If you want YouTube-specific control, use YouTube Ads. > **Can I use the same video for YouTube Ads and TikTok Ads?** > > YouTube Ads require the video to be hosted on YouTube (public or unlisted). [TikTok Ads](/docs/ad-platforms/tiktok-ads) require a separate video file hosted on Google Drive, Dropbox, or S3. > > You can use the same video content, but it needs to be uploaded to both platforms separately. Also note that TikTok prefers 9:16 vertical video (5-60 seconds), while YouTube supports any aspect ratio (minimum 10 seconds). > **Does Adspirer create YouTube videos?** > > No. Adspirer manages campaigns, not video production. You create videos using your preferred tools (CapCut, Canva, Adobe Premiere, Descript, or your phone) and upload them to YouTube. Then provide the YouTube URL to Adspirer for campaign creation. > **Can I run YouTube Shorts ads?** > > Yes. YouTube campaigns created through Adspirer automatically include Shorts placements alongside In-Feed and In-Stream. Vertical videos (9:16) perform best in the Shorts feed, but any video format will serve across all placements. > **How much does Adspirer cost for YouTube Ads?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. A typical YouTube campaign creation uses 5-8 tool calls (validate video + discover assets + create campaign + add extensions). See [full pricing](https://www.adspirer.com/pricing). ## Related Documentation * [Google Ads Integration](/docs/ad-platforms/google-ads) * [TikTok Ads Integration](/docs/ad-platforms/tiktok-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) * [ChatGPT Ads Integration](/docs/ad-platforms/chatgpt-ads) * [Campaign Creation Workflows](/docs/agent-skills/workflows) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your Google Ads account (YouTube included) (\$39 one-time) # Add Adspirer to Your AI Agent in One Command Source: https://www.adspirer.com/docs/add-to-your-agent Installation instructions for Adspirer in Claude, ChatGPT, Cursor, Grok Bot, Claude Code, Codex, and other AI agents. Adspirer is an official, reviewed listing in Claude, ChatGPT, Cursor, and Grok Bot — search for it and add it, no custom connector. Share this page with your agent. This page is the installation instructions for Adspirer — for **Claude** (web, desktop, and Cowork), **ChatGPT**, **Cursor**, **Grok Bot**, **Claude Code**, **Codex**, and other AI agents. Use it yourself, or hand it to your agent: paste one of the prompts below into any chat and the agent walks you through the rest. > [!NOTE] > > **AI agents:** if a user shared this page with you, they're looking for help installing Adspirer. The [section below](#instructions-for-ai-agents) is reference material for you — what Adspirer is, how to verify it, and the exact install steps for each client — so you can brief your user and guide them through their client's path. ## Instructions for AI Agents A user who shares this page wants help setting up Adspirer in this chat. If their message asks for the install, guide them through it; if they shared the link without context, confirm in one line — *"Want me to walk you through installing Adspirer?"* — and go from there. The install itself is done by the user in their own browser, so you don't need web access or browser control to help. **What to tell your user about Adspirer** — brief them first; informed users make faster decisions: * Adspirer is a **third-party service** (not built by Anthropic or OpenAI) for managing ad campaigns — Google, Meta, Amazon, LinkedIn, TikTok, and ChatGPT Ads — from chat. * It's an official, reviewed listing on four platforms: an **Anthropic-verified** [Claude connector](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent) (plus a [plugin in Anthropic's directory](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory)), an OpenAI-reviewed [ChatGPT plugin](https://chatgpt.com/plugins/plugin_asdk_app_69461dc91ee48191ae4a14eb9bde1c21) (having issues right now, so ChatGPT users connect a custom MCP server instead), a **Verified by Cursor** [Cursor plugin](https://cursor.com/marketplace/adspirer), and the same listing as [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239). The install artifacts are open source at [github.com/amekala/ads-mcp](https://github.com/amekala/ads-mcp), so anyone can read exactly what installs. * Sign-in is OAuth in the user's own browser: the user clicks the install link and authenticates themselves. You never see or handle their credentials. * Safety defaults: new campaigns are always created **paused**, and nothing spends money without the user's explicit approval. Details on data handling: [Security](/docs/knowledge-base/security). * The free tier is [15 tool calls/month](https://www.adspirer.com/pricing) — no credit card required to start. **Open with a visual overview — show, don't just tell.** Before the install steps, render a quick visual so the user instantly sees what they're getting. Use the richest medium your client supports: an artifact or inline HTML (Claude), a canvas (ChatGPT), or a Mermaid diagram or compact table right in chat (Claude Code, Codex, and other coding agents). Cover four things: * **What it can do** — analyze cross-platform performance, find wasted ad spend, write brand-voice ad copy, research keywords, and create campaigns (always paused) — all in plain English. * **How it works** — you chat with your agent; the agent calls Adspirer over MCP (authorized via OAuth); Adspirer talks to the ad platform APIs; reports and drafts flow back into the chat. * **Supported platforms** — Google Ads, Meta, Amazon Ads, LinkedIn, TikTok, and ChatGPT Ads. * **Pricing at a glance** — Free: 15 tool calls/month, $0, no card · Plus: 150/month, $49 · Pro: 600/month, $99 · Max: 3,000/month, $199 — [full details](https://www.adspirer.com/pricing). Here's a canonical how-it-works diagram to reuse or adapt: ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR Y["You — plain English"] --> AG["Your AI agent"] AG <-->|"MCP over OAuth"| AD["Adspirer"] AD <--> P["Google Ads · Meta · Amazon Ads
LinkedIn · TikTok · ChatGPT Ads"] ``` **Never recommend a custom connector in Claude, Cursor, or Grok Bot.** Adspirer is listed in each of those apps' own directories, and the listing includes the connector, skills, and agent. Don't tell users to use **Add custom connector**, paste `https://mcp.adspirer.com/mcp`, or edit `mcp.json` there. The search-and-add path is the supported one, it's always current, and a manual copy duplicates every tool. The platforms call these listings *connectors*, *plugins*, *apps*, or *marketplace listings*. It's the same install whatever the word. > [!NOTE] > > **Adspirer is an official, reviewed listing in Claude, Cursor, and Grok Bot.** Search for **Adspirer** in the app's own directory and add it. There's no server URL to paste, no config file, and no API key. ChatGPT is the exception for now: its plugin is having issues, so add Adspirer there as a custom MCP server. Each app uses its own word for it (*connector*, *plugin*, *app*, or *marketplace listing*), but in every case it's the same one-click install. | App | Official listing | Reviewed by | How to add | | - | - | - | - | | **Claude** | [Adspirer Ads & Performance Marketing Agent](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent) | Anthropic (verified) | **Customize → Connectors** → search "Adspirer" → **Connect to Claude** | | **Claude** (Cowork, or chat with skills) | [Adspirer plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory) | Anthropic Directory | **Customize → Plugins** → search "Adspirer" → **Add** | | **ChatGPT** | Custom MCP server (the [plugin](https://chatgpt.com/plugins/plugin_asdk_app_69461dc91ee48191ae4a14eb9bde1c21) is having issues) | — | **Plugins → Add → Add custom MCP server** → `https://mcp.adspirer.com/mcp`, OAuth → **Create as a plugin** ([steps](/docs/ai-clients/chatgpt)) | | **Cursor** | [Adspirer](https://cursor.com/marketplace/adspirer) | Cursor (Verified by Cursor) | **Customize** → search "adspirer" → **Install**, or `/add-plugin adspirer` | | **Grok Bot** | [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) | Cursor (same listing) | **Marketplace** → search "adspirer", or **Add to Grok Bot** on the listing | **Don't set up a custom connector in Claude, Cursor, or Grok Bot.** The listing already includes the connector, the skills, and the agent. A manual server URL only applies in two cases: ChatGPT, where the plugin is having issues and users add a custom MCP server ([ChatGPT setup](/docs/ai-clients/chatgpt)), and Codex or other MCP clients that have no listing. **Install steps by client** — give your user the one path for the client you're running in: * **Claude** (claude.ai, desktop, or mobile) — send the user the [Adspirer Ads & Performance Marketing Agent connector](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent), or have them open **Customize → Connectors** and search **Adspirer**. It's Anthropic verified. They click **Connect to Claude**, then sign in with Google or email. Requires Claude Pro, Max, Team, or Enterprise. * **Claude Cowork** (or Claude chat with skills and slash commands) — send the user the [Adspirer plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory) from Anthropic's directory, or have them search **Adspirer** under **Customize → Plugins**. They click **Add**. It installs the same verified connector plus 15 skills, 5 commands, and an agent. * **ChatGPT** (web, desktop, or mobile) — don't send the Adspirer plugin; it's having issues right now. Walk the user through adding a custom MCP server: **Plugins** in the sidebar → **Add** → **Add custom MCP server**. Name `Adspirer-Custom`, Connection **Server URL** `https://mcp.adspirer.com/mcp`, Authentication **OAuth**. They tick **I understand and want to continue**, click **Create as a plugin**, then **Try in chat** → **Connect Adspirer-Custom**, sign in with Google or email, and click **Authorize** ([steps with screenshots](/docs/ai-clients/chatgpt)). Works on every ChatGPT plan, including Free. ChatGPT is the only chat app where a custom connection is needed. * **Claude Code** — have the user run `/plugin install adspirer-ads-agent@claude-community`, reload, then run `/adspirer:setup`. * **Codex** — have the user run `bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh)`, restart Codex, then run `codex mcp login adspirer`. * **Codex Desktop** (Codex inside the ChatGPT desktop app) — have the user send three chat messages in a Codex chat: `codex plugin marketplace add amekala/ads-mcp`, then `install plugin`, then `help me oauth it`. * **Cursor** — send the user the [Adspirer plugin](https://cursor.com/marketplace/adspirer), which is Verified by Cursor, or have them open **Customize**, search **adspirer**, and select **Install**. They can also run `/add-plugin adspirer` in chat. Sign-in runs on the first tool call. * **Grok Bot** — send the user [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) and have them click **Add to Grok Bot**, or open **Marketplace** at the bottom of the sidebar and search **adspirer**. Then they complete **Authorize** in the browser. * **Gemini CLI, Windsurf, or any other MCP client with no Adspirer listing** — add the remote MCP server `https://mcp.adspirer.com/mcp` (OAuth). Per-client walkthroughs are under [AI Clients](/docs/ai-clients/claude). **Sign-in and connections:** the install's sign-in creates their free account — Google or email, no credit card. Then they connect their ad platforms at [adspirer.ai/connections](https://adspirer.ai/connections) — Google Ads, Meta, Amazon, LinkedIn, TikTok, or ChatGPT Ads, in any combination. **Verify and hand off:** when the user says they're done, check the connection — call `get_connections_status` if you have Adspirer tools, otherwise have them say *"Check my connected ad platforms."* Confirm their connected accounts back to them. In ChatGPT, if verification returns **"Link not found"**, have them reconnect via **Settings → Plugins → Adspirer**, then verify again. **How to write your reply to the user** — one short, friendly message, not a menu of options: * Lead with the visual overview described above — diagram or artifact first, so they see what Adspirer does before reading a single step. * One line on what they're installing: Adspirer, a third-party tool for managing their ad campaigns from this chat. * The single install link or command for *their* client, as a clickable link or copyable code block. * The steps as a numbered list: install → sign in with Google or email (creates a free account, no credit card) → connect ad platforms at [adspirer.ai/connections](https://adspirer.ai/connections). * Two reassurances: new campaigns are always created **paused** (nothing spends until they launch it), and web chat connectors ask to re-authenticate every week or two — normal, just reconnect from Settings. * Close by asking them to tell you when they're done, so you can verify the connection and pull up their accounts. Prefer to install it yourself? Three paths, fastest first. ## One Tap — Chat Apps Adspirer is an official, reviewed listing in each app's own directory. Install straight from the listing: > **[Claude — Anthropic verified](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent)** > > Click **Connect to Claude**, sign in with Google or email, done. Want skills and commands too? Add the [plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory). > **[ChatGPT — custom MCP server](/docs/ai-clients/chatgpt)** > > **Plugins → Add → Add custom MCP server**, paste `https://mcp.adspirer.com/mcp`, sign in. Works on every plan, including Free. > **[Cursor — Verified by Cursor](https://cursor.com/marketplace/adspirer)** > > Click **Add to Cursor**, or type `/add-plugin adspirer` in any Cursor chat. > **[Grok Bot](https://x.ai/bot/plugin/66672239)** > > Click **Add to Grok Bot**, then **Authorize**. Same Verified by Cursor listing. ## One Prompt No terminal needed — paste a prompt and your assistant takes it from there. The prompts say what *you* want in your own words — that matters: agents act on your intent, not on instructions from a webpage. **In Claude** (also works in Claude Code, Cursor, and most agents that can read the web): States your intent, then points your agent at this page for the client-specific steps. I want to install Adspirer, a third-party tool for managing my ad campaigns from this chat. Read [https://www.adspirer.com/docs/add-to-your-agent](https://www.adspirer.com/docs/add-to-your-agent) and walk me through installing it in this app. **In ChatGPT** (ChatGPT doesn't follow fetched pages by design — ask it to act for you instead): ChatGPT walks you through adding Adspirer as a custom MCP server. Help me add Adspirer to ChatGPT as a custom MCP server so I can manage my ad campaigns from this chat. Walk me through Plugins → Add → Add custom MCP server with the server URL [https://mcp.adspirer.com/mcp](https://mcp.adspirer.com/mcp) and OAuth, then connecting and signing in. **Agent can't browse the web?** Paste the self-contained version — everything it needs is inline: No web access needed — the per-client steps travel inside the prompt. Help me install Adspirer, a third-party tool I want for managing my ad campaigns from this chat. First show me a quick visual overview (a diagram, artifact, or compact table — whatever this app supports) of what it does: cross-platform campaign management for Google Ads, Meta, Amazon Ads, LinkedIn, TikTok, and ChatGPT Ads — performance analysis, wasted-spend detection, ad copy, campaign creation (always created paused); free tier is 15 tool calls/month with no card, paid plans at [https://www.adspirer.com/pricing](https://www.adspirer.com/pricing). Then figure out which app you're running in and give me the matching steps: In Claude, give me this link to Adspirer's Anthropic-verified connector and tell me to click Connect to Claude: [https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent) (in Cowork, use the Adspirer plugin instead: [https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory)). In ChatGPT, walk me through Plugins → Add → Add custom MCP server: name Adspirer-Custom, Connection Server URL [https://mcp.adspirer.com/mcp](https://mcp.adspirer.com/mcp), Authentication OAuth, tick I understand and want to continue, click Create as a plugin, then Try in chat and Connect. In Cursor, run /add-plugin adspirer or use [https://cursor.com/marketplace/adspirer](https://cursor.com/marketplace/adspirer). In Grok Bot, give me [https://x.ai/bot/plugin/66672239](https://x.ai/bot/plugin/66672239) and tell me to click Add to Grok Bot. Don't suggest a custom connector or MCP URL in Claude, Cursor, or Grok Bot. In Claude Code, run /plugin install adspirer-ads-agent\@claude-community, then /adspirer:setup. In Codex, run: bash -c "\$(curl -fsSL [https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh](https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh))" then codex mcp login adspirer. In any other MCP client with no Adspirer listing, add the remote MCP server [https://mcp.adspirer.com/mcp](https://mcp.adspirer.com/mcp). After install I'll sign in with Google or email (creates a free account), then connect my ad platforms at [https://adspirer.ai/connections](https://adspirer.ai/connections). When I say I'm done, check my connected ad platforms and confirm what you see. ## One Command — Terminal Installs the **get-started skill** and drops you straight into setup — if Claude Code is installed, it launches automatically with the setup prompt: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/scripts/install-skill.sh | bash ``` Using npm instead? This installs the skill for Claude Code, Cursor, Codex, and other agents, then starts setup: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx skills add amekala/ads-mcp --skill adspirer-get-started -g && claude "set up adspirer" ``` > [!NOTE] > > The skill lives in the open-source [amekala/ads-mcp](https://github.com/amekala/ads-mcp) repo — you can read exactly what it does before installing. To install without auto-launching setup, prefix the curl command's `bash` with `ADSPIRER_NO_LAUNCH=1`. ## What Happens Next Whichever path you pick, your agent runs the same flow: **1. Detects your environment** Chat app (ChatGPT, Claude, Cowork) or coding agent (Claude Code, Cursor, Codex, Gemini CLI) — and picks the right install: the official listing (Claude, ChatGPT, Cursor, Grok Bot), a plugin command (Claude Code, Codex), or MCP config only for clients with no listing. **2. Signs you up through OAuth** The connection prompt opens Adspirer's sign-in — Google or email. No pre-existing account needed; this creates your free account ([15 tool calls/month](https://www.adspirer.com/pricing), no credit card). **3. Connects your ad platforms** Link Google Ads, Meta, Amazon, LinkedIn, TikTok, or ChatGPT Ads at [adspirer.ai/connections](https://adspirer.ai/connections) — any combination, add more later. **4. Verifies and hands off** The agent checks your connections, then opens your personalized getting-started guide — or in Claude Code, bootstraps a full brand workspace with `/adspirer:setup`. > [!TIP] > > Done when your agent shows your connected ad accounts. Try: *"How are my campaigns doing this month?"* ## Troubleshooting > **My agent is cautious about following instructions from a webpage** > > That's your agent being appropriately careful — pages shouldn't be able to command agents. Tell it what you want in your own words: *"I'm asking you myself: help me install Adspirer using the steps on that page."* Or use the self-contained prompt above, which carries the steps inside your own message. > **I pasted this page into my agent and it asked what I want to do** > > Say: *"Install Adspirer — walk me through the steps for this app."* Your intent is the instruction; the page just supplies the details. > **ChatGPT says "Link not found" when checking the connection** > > The plugin's authorization link is stale. Open **Settings → Plugins → Adspirer** and reconnect, complete the sign-in, and connect at least one ad platform. Then ask your agent to verify again. > **My agent lists setup options instead of doing the setup** > > Say: *"Just do it — start with the install for this app."* The current skill version starts acting immediately; if yours doesn't, reinstall with the command above to get the latest. > **The connector disconnects after a week or two** > > Normal for web chat apps (Claude and ChatGPT both do this). Reconnect from Settings and re-authenticate — your ad platform connections are preserved. ## Related Documentation * [Quickstart](/docs/quickstart) — the classic 5-minute manual setup * [Claude Setup](/docs/ai-clients/claude) · [ChatGPT Setup](/docs/ai-clients/chatgpt) · [Cursor Setup](/docs/ai-clients/cursor) · [Grok Bot Setup](/docs/ai-clients/grok) · [Claude Code Setup](/docs/ai-clients/claude-code) · [Codex Terminal Setup](/docs/ai-clients/codex) · [Codex Desktop Setup](/docs/ai-clients/codex-desktop) * [Skill Reference](/docs/agent-skills/skills) — all 13 skills the full plugin ships * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Autonomous Ad Ops Agents | Adspirer Source: https://www.adspirer.com/docs/agent-skills/ad-ops-agents Give Adspirer a plain-English goal and a cadence. An autonomous Ad Ops agent monitors your accounts and proposes every change to an approval queue — nothing spends or changes without your sign-off. Autonomous **Ad Ops agents** turn Adspirer from a tool you drive into a teammate that works on a schedule. You describe a goal in plain English, pick how often it should run, and the agent monitors your accounts, does the analysis, and **proposes every change to an approval queue**. You stay in control — nothing spends money or changes a live campaign until you approve it. > [!NOTE] > > Available on **Plus, Pro, and Max** plans. Agent runs count against your monthly tool-call quota, just like the tools they use. See [pricing](https://www.adspirer.com/pricing). ## How it works **1. Describe the goal** In plain English: "Keep my Google Search CPA under \$40 and cut wasted spend," or "Watch all my accounts for broken conversion tracking." The builder compiles your goal into a concrete operating plan you can review. **2. Set guardrails** Choose the cadence (daily, weekly, or manual), a target metric, and hard limits: maximum budget change per run, maximum number of proposals, and any **protected campaigns** the agent must never touch. Widening scope or enabling money-moving actions requires an explicit high-risk confirmation. **3. The agent runs on schedule** On each run the agent pulls fresh performance data, analyzes it, and decides what to change — find winners to scale, search terms to add as negatives, budgets to rebalance, CPA/ROAS drift to correct, or broken tracking to flag. **4. You approve every change** Each proposed write lands in your **Approvals inbox** with the reasoning and the expected impact. Approve or reject from the agent card. Rejections take a one-tap reason chip that teaches the agent why — so it proposes better next time. Approved changes replay exactly once against your account. **5. The agent measures its own impact** After a change is approved, the **Impact** tab checks whether it actually helped, using your own account data — and feeds that verdict back into the next run. Verdicts only make a causal claim when your data supports it, so you won't see a misleading "+54% worse" call off a tiny sample. ## What an agent can do * **Find and scale winners** — identify high-ROAS campaigns and propose capped budget increases * **Cut wasted spend** — surface search terms with spend and no conversions, propose them as negative keywords * **Rebalance budgets** — shift spend toward what's working * **Guard CPA / ROAS** — catch drift against your target and propose corrections * **Flag broken conversion tracking** — so you're never optimizing blind * **Recommendations tab** — a running list of prioritized, ad-focused suggestions even before you turn on autonomy > [!NOTE] > > **The agent proposes; you dispose.** Adspirer's autonomous agents never change your account or spend your budget without your approval. Every write is parked as a proposal until you approve it. This is a hard, server-side gate — not a setting you can accidentally disable. ## Cross-platform agents A single agent can reason and act across **Google, Meta, TikTok, LinkedIn, and Amazon** from one goal. For example: One cross-platform goal spanning three platforms. Create an Ad Ops agent that keeps my total monthly spend under 10,000 CAD across Meta, Google, and LinkedIn, rebalancing toward whichever platform is delivering the best cost per conversion. Run it daily and send every change to me for approval. ## Teach your agent Upload your own context — brand rules, target CPAs, seasonal calendars, standard operating procedures — and every run grounds its decisions in your documents instead of generic best practices. Your agent proposes changes the way *you* would. ## Community playbooks A **playbook** is an agent's decision logic — its goal brief, rules, and guardrails — with **no account data, budgets, or credentials attached**. You can: * **Share** a playbook you've tuned so other advertisers can use your approach * **Fork** someone else's proven playbook onto your own account in one step Only the strategy travels; your accounts and spend never do. Install counts show which playbooks the community trusts. > [!NOTE] > > Community playbooks (shareable agent strategies) are different from [Community Plugins](/docs/agent-skills/community-plugins), which are open-source analysis *tools* that extend Adspirer's capabilities. ## Notifications & approvals Proposals appear in your in-app **Approvals inbox**, and the agent can email you when it has something waiting. Every notification states the real change and, if a run failed, the real reason — grounded in what actually happened, not a canned template. Money-moving actions always route back to an explicit in-product approval. ## FAQ > **Can an agent spend my budget without asking?** > > No. Every write — budget change, pause, new keyword, new campaign — is parked as a proposal and only executes after you approve it in the Approvals inbox. This is enforced on the server, not just in the UI. > **What's the difference between an Ad Ops agent and Agent Skills?** > > [Agent Skills](/docs/agent-skills/overview) teach your AI client the right *workflow* when you're actively chatting with it. An **Ad Ops agent** runs on its own schedule in the background, without you in the chat, and queues its proposals for later approval. Skills make your live sessions expert; agents keep working when you're away. > **Which plans include Ad Ops agents?** > > Plus, Pro, and Max. Agent runs use your monthly tool-call quota. Higher tiers get more quota for more frequent runs across more accounts. > **Can I run one agent across multiple ad platforms?** > > Yes. A single agent can reason and propose changes across Google, Meta, TikTok, LinkedIn, and Amazon from one goal — for example, capping total spend across three platforms at once. ## Related > **[Community Plugins](/docs/agent-skills/community-plugins)** > > Extend Adspirer with open-source, read-only community analysis tools. > **[Agent Skills Overview](/docs/agent-skills/overview)** > > Teach your AI client proven ad-management workflows. > **[Core Workflows](/docs/agent-skills/workflows)** > > Step-by-step sequences for campaign creation and optimization. > **[Pricing & Plans](https://www.adspirer.com/pricing)** > > Quota by tier for agent runs. # Adspirer Performance Marketing Agent for AI Clients Source: https://www.adspirer.com/docs/agent-skills/agent The performance marketing agent orchestrates skills, maintains brand knowledge, and manages campaigns across Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads. The performance marketing agent is an expert advertising manager that sits on top of Adspirer's 400+ tools. It knows your brand, remembers past decisions, follows your strategy, and uses proven workflows to manage campaigns across all platforms. ## How It Works ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[You] -->|"Create a campaign" / "How's performance?"| B[Performance Marketing Agent] B --> C[Brand Context] B --> D[STRATEGY.md] B --> E[MEMORY.md] C --> F{Pick the right skill} D --> F E --> F F --> G[Skill Workflow] G --> H[Adspirer MCP Tools] H --> I[Google Ads] H --> J[Meta Ads] H --> K[Amazon Ads] H --> L[ChatGPT Ads] H --> M[LinkedIn Ads] H --> N[TikTok Ads] G -->|"Results + recommendations"| A ``` The agent reads your brand context, strategy directives, and past decisions before choosing the right skill and tools for your request. Every action goes through the same pipeline — whether you're analyzing performance, creating campaigns, or writing ad copy. ## Where It Runs The agent is available across 3 IDEs: | Feature | Claude Code | Cursor | Codex | | - | - | - | - | | Agent type | Claude Code agent | Cursor subagent | Codex agent config | | Agent file | `agents/performance-marketing-agent.md` | `.cursor/agents/performance-marketing-agent.md` | `agents/performance-marketing-agent.toml` | | Brand context | `CLAUDE.md` | `BRAND.md` | `AGENTS.md` | | Strategy file | `STRATEGY.md` | `STRATEGY.md` | `STRATEGY.md` | | Memory | `MEMORY.md` | `.cursor/memory/.../MEMORY.md` | -- | | Rules | -- | `.cursor/rules/*.mdc` | `rules/campaign-safety.rules` | | Skills | 1 (ad-campaign-management) | 5 (adspirer-\*) | 5 (adspirer-\*) | | Web research | `WebSearch` + `WebFetch` | `WebSearch` + `WebFetch` | -- | > [!NOTE] > > The agent is installed automatically with the plugin or one-command installer. See the [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), or [Codex](/docs/ai-clients/codex) setup guides. *** ## Brand Workspace When you first run setup (`/adspirer:setup` in Claude Code, `/adspirer-setup` in Cursor, `$adspirer-setup` in Codex), the agent creates a **brand workspace** — a set of local files that give it context about your business, strategy, and past decisions. ### What Setup Creates ``` ~/Clients/YourBrand/ ├── CLAUDE.md # Brand context (Claude Code) │ └── or BRAND.md # Brand context (Cursor) │ └── or AGENTS.md # Brand context (Codex) ├── STRATEGY.md # Strategy directives (all IDEs) └── MEMORY.md # Past decisions (Claude Code + Cursor) ``` ### Brand Context File The brand context file is the foundation. It contains everything the agent needs to make brand-aware decisions: | Section | Source | Content | | - | - | - | | Brand Overview | Your docs + Adspirer | What you sell, who you sell to, industry | | Brand Voice | Your docs | Tone, language style, prohibited words | | Target Audiences | Your docs + campaigns | Audience segments with targeting parameters | | Active Platforms | Adspirer | Connected platforms and campaign counts | | Budget & Guardrails | Your docs + campaigns | Monthly budget, CPC caps, CPA targets, ROAS minimums | | KPI Targets | Your docs | Primary goals and target metrics | | Performance Snapshot | Adspirer | Last 30 days across all platforms | | Key Findings | Adspirer | Top campaigns, wasted spend, opportunities | | Competitors | Your docs | Known competitors | | Strategy | STRATEGY.md | Pointer to strategy directives | > [!TIP] > > The more brand docs you drop into your folder before running setup, the better the agent's ad copy and recommendations. Brand guidelines, media plans, competitor analyses, and audience research all improve output quality. *** ## Strategy Playbook `STRATEGY.md` is where strategic decisions persist across sessions. When you analyze competitors, review performance, or make strategic decisions, the agent saves confirmed directives to this file. All skills read it before executing. ### Why This Matters Without strategy persistence, each session starts fresh. You might spend 30 minutes analyzing your competitive landscape, concluding "don't bid on broad match competitor terms — they're too expensive." Then when you create a campaign, the skill does its own keyword research and recommends those exact terms. With `STRATEGY.md`, the analysis produces directives that are saved and enforced: ``` BEFORE (without strategy persistence): Strategy analysis → conclusions stay in chat → next session starts fresh → contradicts strategy AFTER (with STRATEGY.md): Strategy analysis → directives saved to STRATEGY.md → skills read directives → keyword research filtered → conflicts flagged → campaign follows your strategy ``` ### Directive Types | Type | Format | Example | | - | - | - | | **AVOID** | `AVOID: [what] — [reason]` | `AVOID: broad match "plumbing services" — competitor-dominated, $12+ CPC` | | **PREFER** | `PREFER: [what] — [reason]` | `PREFER: long-tail "emergency plumber near me" — high intent, lower CPC` | | **CONSTRAINT** | `CONSTRAINT: [rule] — [reason]` | `CONSTRAINT: max CPC $8 for non-brand terms — budget protection` | | **REQUIRE** | `REQUIRE: [action] — [reason]` | `REQUIRE: sitelinks on all Search campaigns — Quality Score boost` | ### What Triggers Saving Not every conversation produces directives. The agent classifies conversations before persisting: | Conversation Type | Examples | Action | | - | - | - | | Exploratory | "What if we tried...", brainstorming | Does NOT save directives | | Research | "Analyze competitors", "How's performance?" | Presents findings, asks if any should become directives | | Explicit decision | "Don't bid on X", "Focus on long-tail" | Proposes directives, asks you to confirm | | Confirmed analysis | You agree with the agent's conclusions | Proposes directives, asks you to confirm | > [!NOTE] > > Directives are **only saved after you explicitly confirm them.** The agent proposes, you approve. Nothing is saved automatically from casual conversation. ### How Skills Use Strategy Every skill reads `STRATEGY.md` before executing: 1. **Campaign creation** — loads directives at Step 0, uses them as context for keyword research, bidding, targeting, and ad copy. Flags conflicts between research results and directives. 2. **Keyword research** — after getting results, cross-references against AVOID/PREFER directives. Deprioritizes matching AVOID terms and highlights PREFER terms. 3. **Ad copy** — checks Creative Direction and Competitive Positioning directives for messaging guidance. 4. **Performance review** — flags campaigns that violate active directives as "Strategy Drift" items. 5. **Wasted spend** — flags campaigns violating directives as priority waste sources. ### STRATEGY.md Structure ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} # [Brand Name] — Strategy Playbook ## Active Directives ### Cross-Platform Strategy PREFER: long-tail keywords with clear purchase intent — higher conversion rates ### Google Ads AVOID: broad match "plumbing services" — competitor-dominated auction, $12+ CPC PREFER: exact match "emergency plumber [city]" — high intent, $4-6 CPC CONSTRAINT: max CPC $8 for non-brand terms — budget protection ### Meta Ads [No active directives] ### Amazon Ads [No active directives] ### ChatGPT Ads [No active directives] ### LinkedIn Ads PREFER: target IT Directors at 200-1000 employee companies — best conversion rate from Q1 data ### TikTok Ads [No active directives] ### Budget Allocation CONSTRAINT: 60% Google, 25% LinkedIn, 15% Meta — based on Q1 ROAS data --- ## Decision Log ### 2026-02-15 — Competitive analysis Analyzed top 5 competitors. Key finding: broad match terms are dominated by national chains with 10x our budget. Pivoting to long-tail exact match strategy. --- ## Archived Directives [Previous directives that were superseded or removed] ``` *** ## Memory `MEMORY.md` tracks past decisions, learnings, and your preferences across sessions. Available in Claude Code and Cursor. **What gets saved to memory:** * Campaign actions taken (what was created, modified, or paused) * Optimization results (what worked, what didn't) * Your preferences (reporting format, approval style, platform priorities) * Key learnings (which audiences convert best, seasonal patterns) **What doesn't get saved:** * Raw performance data (always pulled fresh from Adspirer) * In-progress work or temporary analysis * Unconfirmed conclusions The agent reads memory at the start of each session and when analyzing performance, providing continuity across conversations. *** ## Rules Rules are IDE-specific safety and workflow enforcement files. They complement skills by auto-triggering behavior based on context. ### Cursor Rules Cursor supports `.mdc` rule files that apply automatically when relevant. Adspirer ships two: **`brand-workspace.mdc`** — Auto-loads brand context on every advertising task: * Reads `BRAND.md` and `MEMORY.md` at session start * Reads `STRATEGY.md` for active directives * Bootstraps new workspaces if `BRAND.md` doesn't exist * Updates context files when significant changes happen **`use-adspirer.mdc`** — Enforces workflow safety: * Always checks connections first * Read-before-write enforcement * User confirmation before spend-affecting actions * Campaign creation in PAUSED status * Strategy directive checks before campaign creation and keyword operations * Mandatory ad extensions for Google Ads campaigns * Verification before reporting success #### Rules in Action **Without rules:** You say "create a Google Ads campaign" and Cursor jumps straight to `create_search_campaign` — which fails because there's no keyword research, no asset validation, and no strategy check. **With rules:** The same prompt triggers a full workflow — connection check, strategy load, keyword research, asset validation, user confirmation, campaign creation (PAUSED), ad extensions, and post-creation verification. ### Codex Safety Rules Codex uses `campaign-safety.rules` to block direct API calls to ad platforms: ``` prefix_rule( pattern = ["curl", "https://ads.google.com"], decision = "forbidden", justification = "Google Ads API calls must go through Adspirer MCP" ) ``` This ensures all ad platform operations go through Adspirer's authenticated, auditable pipeline — not raw API calls. *** ## IDE Feature Comparison | Capability | Claude Code | Cursor | Codex | | - | :-: | :-: | :-: | | Performance marketing agent | Yes | Yes (subagent) | Yes (agent config) | | 400+ Adspirer tools | Yes | Yes | Yes | | Skills (workflow enforcement) | 1 skill | 14 skills | 5 skills | | Slash commands | 5 commands | 14 skills | 5 dollar commands | | Brand context file | CLAUDE.md | BRAND.md | AGENTS.md | | Strategy persistence | STRATEGY.md | STRATEGY.md | STRATEGY.md | | Memory (cross-session) | MEMORY.md | MEMORY.md | Not available | | Rules (auto-trigger) | Not available | 2 rule files | Safety rules | | Web research (competitors) | WebSearch + WebFetch | WebSearch + WebFetch | Not available | *** ## FAQ > **Do I need the agent to use Adspirer?** > > No. You can connect Adspirer MCP directly and use the 400+ tools without the agent. But the agent adds brand awareness, strategy persistence, memory, and workflow orchestration — turning raw tools into a managed advertising system. > **Can the agent create campaigns without my approval?** > > No. All campaigns are created in **PAUSED** status. The agent always asks for your confirmation before any action that affects spend. This is enforced by both skills and rules. > **How does the agent handle multiple ad accounts?** > > The agent uses `switch_primary_account` to manage different accounts. Each brand folder has its own context file, strategy, and memory — so you can manage multiple clients by working in different folders. > **Does the agent work with ChatGPT?** > > Not yet. ChatGPT supports MCP connectors (tools) but not agent files, skills, or rules. You get the full 400+ tools but without workflow enforcement or brand awareness. [Perplexity](/docs/ai-clients/perplexity) supports skill uploads (SKILL.md) for workflow guidance. The [Claude](/docs/ai-clients/claude), [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), and [Codex](/docs/ai-clients/codex) integrations support the full agent experience. > **What happens if STRATEGY.md gets stale?** > > Strategy directives are guidance, not rigid rules. Skills use them to inform research — not bypass it. If a directive conflicts with fresh data, the agent flags the conflict and asks you. You can archive or update directives anytime. The Decision Log includes dates so you can see when directives were last validated. > **Can I edit the agent prompt?** > > Yes. The agent prompt is a markdown file. Edit it to change default behaviors, add custom workflows, or modify how the agent interacts with you. The source is in the [ads-mcp repository](https://github.com/amekala/ads-mcp/tree/main/shared/agents). > **The agent can't connect to Adspirer. How do I fix it?** > > If the agent can't reach the MCP server (all tools fail, not just one platform), follow these steps: > > 1. **Check tool permissions** — read tools should be set to **Always allow**, write tools to **Custom** (ask each time). Blocked tools prevent the agent from executing anything. > 2. **Disconnect and reconnect** the Adspirer connector in your AI client settings, then complete the OAuth flow again. > 3. **Refresh your Adspirer session** — log out of [adspirer.ai](https://adspirer.ai), log back in, then return to your AI client. > > **Claude and ChatGPT web users:** Connectors may disconnect every 1–2 weeks. This is normal behavior for web-based clients — just re-enable and re-authenticate. > > **Important:** If some platforms work but one doesn't (e.g., Google works but LinkedIn fails), that's a platform-specific issue, not a connection problem. Reconnect just that platform at [adspirer.ai/connections](https://adspirer.ai/connections). > > See [Troubleshooting FAQ](/docs/knowledge-base/faq#troubleshooting) for more details. ## Related Documentation * [Skill Reference](/docs/agent-skills/skills) — The 5 skills with invocation details and examples * [Skills Overview](/docs/agent-skills/overview) — What skills are and how to install them * [Core Workflows](/docs/agent-skills/workflows) — Step-by-step tool sequences * [Tool Catalog](/docs/agent-skills/tools) — All 400+ Adspirer tools * [Autonomous Ad Ops Agents](/docs/agent-skills/ad-ops-agents) — Give a plain-English goal and cadence; the agent proposes every change to an approval queue for your review * [Community Plugins](/docs/agent-skills/community-plugins) — Open-source, read-only community analysis tools * [Claude Code Setup](/docs/ai-clients/claude-code) — Plugin install with agent * [Cursor Setup](/docs/ai-clients/cursor) — Subagent + skills + rules install * [Codex Setup](/docs/ai-clients/codex) — Agent config + skills install * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Run the Adspirer Marketing Agent in Claude Code Source: https://www.adspirer.com/docs/agent-skills/claude-code-agent How the Adspirer performance marketing agent runs inside Claude Code: subagent architecture, skills, slash commands, memory, and the agent loop. Your AI advertising manager inside the terminal. The performance marketing agent runs as a Claude Code subagent — it has its own prompt, memory, and tools, and returns results back to your main session. ## How It Works Claude Code uses an **agentic loop**: you describe a task, it reasons about what to do, calls tools, reads results, reasons again, and repeats until done. When your task involves advertising, Claude Code spawns the Adspirer agent to handle it. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[You] -->|"How are my Google Ads doing?"| B[Claude Code] B -->|Spawns subagent| C[Performance Marketing Agent] C -->|Reads| D[CLAUDE.md + STRATEGY.md + MEMORY.md] C -->|Calls| E[Adspirer MCP Tools] E -->|OAuth| F[Google / Meta / LinkedIn / TikTok] C -->|Returns results| B B -->|Presents to you| A ``` ### What Happens When You Ask About Ads You say: *"Create a Google Search campaign for my SaaS product"* 1. Claude Code recognizes this as an advertising task 2. Spawns the performance marketing agent as a subagent 3. Agent reads `CLAUDE.md` (brand context), `STRATEGY.md` (directives), `MEMORY.md` (past decisions) 4. Follows the skill workflow: connection check → competitive research → keyword research → asset validation → campaign creation → ad extensions → verification 5. Each step calls Adspirer MCP tools (`research_keywords`, `create_search_campaign`, etc.) 6. Agent asks for your confirmation before spending 7. Results return to your main Claude Code session > [!TIP] > > The agent runs as a subagent with its own context — long advertising workflows don't bloat your main session. *** ## What Gets Installed The Adspirer plugin gives Claude Code everything it needs: | Component | File | Purpose | | - | - | - | | **MCP Server** | `https://mcp.adspirer.com/mcp` | 400+ advertising tools via OAuth | | **Agent** | `~/.claude/agents/performance-marketing-agent.md` | Agent prompt with brand awareness and workflows | | **Skill** | `~/.claude/skills/ad-campaign-management/SKILL.md` | Proven workflows for all platforms | | **Commands** | `~/.claude/commands/*.md` | 5 slash commands for common tasks | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin install adspirer-ads-agent@claude-community ``` Available on the official Anthropic marketplace — no custom marketplace setup needed. Or type `/plugin`, open the **Discover** tab, and search `adspirer`. Installs everything in one step. Run `/reload-plugins` after installing. *** ## Skills & Slash Commands Skills are instruction files that teach Claude Code the *right* workflow for using Adspirer's 400+ tools. Without skills, the AI guesses which tools to call and in what order. With skills, it follows proven advertising workflows with safety rules baked in. ### How Skills Load 1. **Skill descriptions** are always in context — Claude Code knows what's available 2. **Full skill content** loads when invoked (by you or automatically) 3. **The agent preloads the skill** when spawned, so it starts with complete workflow instructions ### One Comprehensive Skill Claude Code uses **1 skill** (`ad-campaign-management`) covering all platforms and workflows. This differs from Cursor and Codex which split into 5 separate skills — Claude Code consolidates because its plugin system handles slash commands separately. The skill includes: * Workflow routing: maps your request to the right tool sequence * Platform-specific campaign creation flows (Google, Meta, Amazon, ChatGPT Ads, LinkedIn, TikTok) * Keyword research with strategy directive filtering * Cross-platform performance analysis * Budget optimization and wasted spend detection * Ad extension workflows (sitelinks, callouts, structured snippets) * Competitive intelligence using web research * Safety rules: confirmation gates, PAUSED creation, read-before-write ### Slash Commands | Command | What It Does | | - | - | | `/adspirer:setup` | Bootstrap a brand workspace — connect accounts, scan docs, pull data | | `/adspirer:ad-campaign-management` | Full campaign management — all platforms, all workflows | | `/adspirer:performance-review` | Cross-platform performance scorecard | | `/adspirer:write-ad-copy` | Brand-voice ad copy from real performance data | | `/adspirer:wasted-spend` | Find and fix wasted ad spend | You don't need to memorize these. Just describe what you want — Claude Code matches the right skill automatically. Cross-platform performance review with strategy alignment. Run a performance review for the last 30 days across all platforms. Compare against my KPI targets and flag any campaigns that conflict with my strategy. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=agent-cta\&utm_content=claude-code-agent)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. *** ## Context Files The agent uses three persistent files to maintain brand awareness across sessions. ### CLAUDE.md — Brand Context Created by `/adspirer:setup`. Claude Code reads this automatically at session start. | Section | What It Contains | | - | - | | Brand Overview | What you sell, who you sell to, industry | | Brand Voice | Tone, language style, prohibited words | | Target Audiences | Segments with platform-specific targeting | | Active Platforms | Connected platforms and campaign counts | | Budget & Guardrails | Monthly budget, CPC caps, CPA targets, ROAS minimums | | KPI Targets | Primary goals and target metrics | | Performance Snapshot | Last 30 days across all platforms | | Key Findings | Top campaigns, wasted spend, opportunities | ### STRATEGY.md — Strategic Decisions Persists directives across sessions. Every skill reads this before executing. ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} ### Google Ads AVOID: broad match "plumbing services" — competitor-dominated, $12+ CPC PREFER: exact match "emergency plumber [city]" — high intent, $4-6 CPC CONSTRAINT: max CPC $8 for non-brand terms — budget protection ``` Directives are **only saved after you explicitly confirm them.** The agent proposes, you approve. ### MEMORY.md — Past Decisions Tracks campaign actions, optimization results, your preferences, and key learnings. The agent reads memory at session start and cross-references it during analysis. *** ## The Agent Loop: Step by Step Here's exactly what happens when you run `/adspirer:performance-review`: **1. Agent spawns** Claude Code creates a subagent with the performance marketing agent prompt and skill preloaded. **2. Context loads** Agent reads `CLAUDE.md`, `STRATEGY.md`, and `MEMORY.md`. **3. Connections check** Calls `get_connections_status` to identify which ad platforms are active. **4. Data pull** For each connected platform, calls performance and wasted spend tools in parallel. **5. Strategy check** Compares campaign data against `STRATEGY.md` directives. Flags "Strategy Drift" items. **6. Analysis & recommendations** Compares actuals vs KPI targets. Cross-references with `MEMORY.md`. Presents a unified scorecard with top 3 recommended actions. *** ## Web Research The Claude Code agent has access to `WebSearch` and `WebFetch` — it can research competitors, crawl websites, and gather market intelligence. This powers the **Campaign Research** workflow that runs before any campaign creation: 1. `WebFetch` crawls your website and competitor sites for positioning, pricing, value propositions 2. `WebSearch` finds competitors, comparison content, and market data 3. Combined with Adspirer data (search terms, keyword volumes), the agent creates a research brief before building your campaign The agent doesn't just create campaigns from your prompt — it researches your market first. *** ## Safety Rules | Rule | How It Works | | - | - | | User confirmation for spend | Agent always asks before creating campaigns or changing budgets | | Campaigns created PAUSED | All `create_*` tools default to PAUSED status | | Read-before-write | Connection check → research → validate → create | | Never retry on error | Reports the error instead of retrying campaign creation | | Budget guardrails | Checks `CLAUDE.md` budget limits before spend-affecting actions | | Strategy compliance | Reads `STRATEGY.md` and flags conflicts with active directives | | Post-creation verification | Verifies ad groups, keywords, ads, and extensions after creation | *** ## Comparison with Other Clients | Feature | Claude Code | Cursor | Codex | | - | :-: | :-: | :-: | | Agent type | Subagent | Subagent | Agent config | | Brand context file | `CLAUDE.md` | `BRAND.md` | `AGENTS.md` | | Skills | 1 comprehensive | 5 separate | 5 separate | | Slash commands | 5 (`/adspirer:*`) | 5 (`/adspirer-*`) | 5 (`$adspirer-*`) | | Memory | `MEMORY.md` | `MEMORY.md` | Not available | | Rules | -- | 2 rule files | Safety rules | | Web research | `WebSearch` + `WebFetch` | `WebSearch` + `WebFetch` | Not available | *** ## FAQ > **How is the agent different from just using MCP tools?** > > Without the agent, you have 400+ tools but no workflow guidance, no brand awareness, no strategy persistence, and no memory. The agent turns raw tools into a managed advertising system that knows your brand and follows proven workflows. > **Can I customize the agent prompt?** > > Yes. Edit `~/.claude/agents/performance-marketing-agent.md` to change behaviors, add workflows, or modify interaction style. The source is in the [ads-mcp repo](https://github.com/amekala/ads-mcp/tree/main/agents). > **Does the agent use my main context window?** > > No. The agent runs as a subagent with its own context. Results are summarized and returned. Long advertising workflows don't bloat your main session. > **Can I run the agent in the background?** > > Yes. Claude Code supports background agents. Spawn the agent for a long task (like a full cross-platform review) and continue working while it runs. > **What model does the agent use?** > > The agent uses the same model as your Claude Code session. You can override this in the agent file with the `model` field. ## Related Documentation * [Cursor Agent](/docs/agent-skills/cursor-agent) — How Adspirer works in Cursor * [Codex Agent](/docs/agent-skills/codex-agent) — How Adspirer works in Codex * [Performance Marketing Agent](/docs/agent-skills/agent) — Architecture overview * [Skill Reference](/docs/agent-skills/skills) — All 5 skills with invocation details * [Claude Code Setup](/docs/ai-clients/claude-code) — Installation guide * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Run the Adspirer Marketing Agent in OpenAI Codex Source: https://www.adspirer.com/docs/agent-skills/codex-agent How the Adspirer performance marketing agent runs in OpenAI Codex CLI: agent config, 5 skills, safety rules, AGENTS.md, and the plan-execute-verify loop. Your AI advertising manager in Codex CLI. The performance marketing agent runs as a **Codex agent config** with 5 dedicated skills and safety rules that prevent direct API calls to ad platforms. ## How It Works Codex CLI uses a **plan-execute-verify loop**: it explains its plan, you approve, it executes, then verifies results. When your task involves advertising, Codex loads the Adspirer agent config and skills to follow proven workflows. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[You] -->|"Research keywords for my SaaS"| B[Codex CLI] B -->|Loads agent config| C[Performance Marketing Agent] C -->|Reads| D[AGENTS.md + STRATEGY.md] C -->|Calls| E[Adspirer MCP Tools] E -->|OAuth| F[Google / Meta / LinkedIn / TikTok] C -->|Returns results| B B -->|Presents to you| A ``` ### What Makes Codex Different Codex has some unique characteristics compared to Claude Code and Cursor: 1. **AGENTS.md** — Codex uses `AGENTS.md` (not `CLAUDE.md` or `BRAND.md`) for persistent context 2. **No memory file** — Codex doesn't support cross-session memory like Claude Code and Cursor 3. **No web research** — `WebSearch` and `WebFetch` are not available, so competitive research is done through ad platform data only 4. **Safety rules** — `.rules` files that block direct API calls to ad platforms, ensuring everything goes through Adspirer's authenticated pipeline 5. **Dollar-sign commands** — Skills are invoked with `$adspirer-*` syntax *** ## What Gets Installed The one-command installer sets up everything: | Component | File | Purpose | | - | - | - | | **MCP Server** | `~/.codex/config.toml` | 400+ advertising tools via OAuth | | **Agent config** | `~/.codex/agents/performance-marketing-agent.toml` | Agent prompt and behavior | | **5 Skills** | `~/.agents/skills/adspirer-*/SKILL.md` | Workflow instructions per task type | | **Safety rules** | `rules/campaign-safety.rules` | Block direct ad platform API calls | **Plugin Marketplace (Recommended)** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} codex plugin marketplace add amekala/ads-mcp ``` Then inside Codex, run `/plugins` → navigate to the **Adspirer** tab → select **Adspirer Ads Agent** → press **Enter to install**. OAuth runs automatically on first use. **Shell Installer** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh) ``` Installs MCP server, agent config, all 5 skills, and safety rules. Restart Codex after installing, then run `codex mcp login adspirer` to authenticate. **Manual Install** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} # Add MCP server codex mcp add adspirer --url https://mcp.adspirer.com/mcp # Clone and install skills + agent git clone https://github.com/amekala/ads-mcp.git /tmp/ads-mcp mkdir -p ~/.agents/skills cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-ads ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-setup ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-performance-review ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-write-ad-copy ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-wasted-spend ~/.agents/skills/ ``` *** ## The 5 Skills Codex uses the same **Agent Skills** standard as Claude Code. Each skill is a `SKILL.md` file with YAML frontmatter and workflow instructions. | Skill | Command | What It Does | | - | - | - | | **Ad Campaign Management** | `$adspirer-ads` | Full campaign management — all platforms, all workflows | | **Setup** | `$adspirer-setup` | Bootstrap a brand workspace | | **Performance Review** | `$adspirer-performance-review` | Cross-platform performance scorecard | | **Write Ad Copy** | `$adspirer-write-ad-copy` | Brand-voice ad copy from real data | | **Wasted Spend** | `$adspirer-wasted-spend` | Find and fix wasted ad spend | ### How Skills Work in Codex 1. Codex discovers skills from `~/.agents/skills/` automatically 2. **Progressive disclosure**: metadata loads first, full `SKILL.md` loads when the skill is needed 3. Invoke explicitly with `$adspirer-*` or let Codex match automatically from your description 4. Skills use generic verbs ("Search", "Crawl") instead of tool-specific names since Codex doesn't have `WebSearch`/`WebFetch` Run a performance review across all connected platforms. \$adspirer-performance-review Run a performance review for the last 30 days across all platforms. Compare against my KPI targets and flag any strategy drift. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=agent-cta\&utm_content=codex-agent)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. ### Codex-Specific Adaptations The Codex versions of Adspirer skills are adapted from the same source templates as Claude Code and Cursor, with these differences: | Feature | Claude Code / Cursor | Codex | | - | - | - | | Context file | `CLAUDE.md` / `BRAND.md` | `AGENTS.md` | | Web research | `WebFetch` / `WebSearch` | Not available — uses ad platform data only | | Memory | `MEMORY.md` | Not available | | Auth troubleshooting | Reconnect via settings | `codex mcp login adspirer` | *** ## Safety Rules Codex uses `.rules` files to enforce safety at a deeper level than skills. The `campaign-safety.rules` file blocks direct API calls to ad platforms: ``` prefix_rule( pattern = ["curl", "https://ads.google.com"], decision = "forbidden", justification = "Google Ads API calls must go through Adspirer MCP" ) ``` This ensures all ad platform operations go through Adspirer's authenticated, auditable pipeline — never through raw API calls or `curl` commands. ### Full Safety Stack | Rule | How It Works | | - | - | | User confirmation for spend | Agent asks before creating campaigns or changing budgets | | Campaigns created PAUSED | All `create_*` tools default to PAUSED status | | Read-before-write | Connection check → research → validate → create | | Never retry on error | Reports errors instead of retrying campaign creation | | Direct API blocked | `.rules` files block `curl` to ad platform APIs | | Post-creation verification | Verifies ad groups, keywords, ads after creation | | Build integrity check | Flags campaigns with zero ads or zero keywords before optimization | *** ## Context Files Codex uses two persistent files (no memory file). ### AGENTS.md — Brand Context Created by `$adspirer-setup`. This is Codex's equivalent of `CLAUDE.md` (Claude Code) and `BRAND.md` (Cursor). Codex uses a hierarchical `AGENTS.md` loading system: 1. **Global:** `~/.codex/AGENTS.md` (applies to all projects) 2. **Project:** Walks from git root to current directory, merging each level 3. Maximum combined size: 32 KiB | Section | What It Contains | | - | - | | Brand Overview | What you sell, who you sell to, industry | | Brand Voice | Tone, language style, prohibited words | | Active Platforms | Connected platforms and campaign counts | | Budget & Guardrails | Monthly budget, CPC caps, CPA targets | | Performance Snapshot | Last 30 days from Adspirer | ### STRATEGY.md — Strategic Decisions Same as Claude Code and Cursor. Persists directives across sessions: ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} ### Google Ads AVOID: broad match "plumbing services" — competitor-dominated, $12+ CPC PREFER: exact match "emergency plumber [city]" — high intent, $4-6 CPC ``` > [!NOTE] > > Since Codex doesn't have a memory file, `STRATEGY.md` and `AGENTS.md` are the primary ways to persist context across sessions. Put anything you want the agent to remember in these files. *** ## The Agent Loop When you invoke `$adspirer-performance-review` in Codex: **1. Skill loads** Codex discovers and loads the performance review skill via progressive disclosure. **2. Context loads** Reads `AGENTS.md` for brand context and KPI targets. Reads `STRATEGY.md` for active directives. **3. Connections check** Calls `get_connections_status` to identify connected ad platforms. **4. Data pull** For each connected platform, calls performance tools via Adspirer MCP. **5. Strategy check** Compares campaign data against `STRATEGY.md`. Flags "Strategy Drift" items. **6. Results** Presents a unified scorecard with recommendations and top 3 actions. *** ## Approval Modes Codex has 3 approval modes that affect how the agent interacts: | Mode | File Access | Tool Calls | Best For | | - | - | - | - | | **Read-only** | Read only | Approval needed | Reviewing performance, auditing spend | | **Auto** (default) | Read + edit in working dir | Auto-approved in scope | Campaign creation, keyword management | | **Full Access** | Read anywhere + network | Auto-approved | Bulk operations across accounts | For advertising tasks, **Auto mode** works well — you get automatic approvals for read operations and prompted for spend-affecting actions. *** ## Comparison with Other Clients | Feature | Codex | Claude Code | Cursor | | - | :-: | :-: | :-: | | Agent type | Agent config | Subagent | Subagent | | Brand context file | `AGENTS.md` | `CLAUDE.md` | `BRAND.md` | | Skills | 5 separate | 1 comprehensive | 5 separate | | Commands | `$adspirer-*` | `/adspirer:*` | `/adspirer-*` | | Memory | Not available | `MEMORY.md` | `MEMORY.md` | | Rules | Safety rules (`.rules`) | -- | Cursor Rules (`.mdc`) | | Web research | Not available | `WebSearch` + `WebFetch` | `WebSearch` + `WebFetch` | | Direct API blocking | Yes (`.rules`) | No | No | *** ## FAQ > **Why doesn't Codex have memory?** > > Codex CLI doesn't support a persistent memory file like Claude Code's `MEMORY.md`. Use `AGENTS.md` and `STRATEGY.md` to persist important context. The agent will record decisions and findings in `STRATEGY.md` when you confirm them. > **Can the agent do competitive research without WebSearch?** > > The Codex agent can't crawl websites or search the web. It relies on Adspirer's ad platform data (search terms, keyword volumes, campaign performance, benchmarks) for insights. For competitive research, use Claude Code or Cursor instead. > **What are safety rules?** > > Codex `.rules` files block specific command patterns. Adspirer's `campaign-safety.rules` prevents direct `curl` or API calls to Google Ads, Meta, LinkedIn, and TikTok APIs. This ensures all operations go through Adspirer's authenticated pipeline with proper OAuth, audit logging, and safety checks. > **Can I use Codex as an MCP server for other agents?** > > Yes. Codex CLI can expose itself as an MCP server for the OpenAI Agents SDK. This means you can build higher-level agents that delegate advertising tasks to Codex + Adspirer. See the [Codex Agents SDK guide](https://developers.openai.com/codex/guides/agents-sdk/). ## Related Documentation * [Claude Code Agent](/docs/agent-skills/claude-code-agent) — How Adspirer works in Claude Code * [Cursor Agent](/docs/agent-skills/cursor-agent) — How Adspirer works in Cursor * [Performance Marketing Agent](/docs/agent-skills/agent) — Architecture overview * [Skill Reference](/docs/agent-skills/skills) — All 5 skills with invocation details * [Codex Setup](/docs/ai-clients/codex) — Installation guide * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Community Plugins | Adspirer Source: https://www.adspirer.com/docs/agent-skills/community-plugins Extend Adspirer with open-source, community-contributed analysis tools. Community plugins are read-only to your ad accounts and run in a sandboxed, credential-free environment. **Community Plugins** let the Adspirer community extend the product with extra analysis and insight tools that show up right alongside the built-in ones. They're open source, they're read-only to your ad accounts, and they run in a locked-down sandbox — so you get more capability without new risk. Your AI client reaches them through a single `community_plugins` router tool: it calls `action: "list_tools"` to see what's available, then `action: "execute"` to run one. ## What they are * **Open source.** Every plugin lives in the public [`Adspirer/adspirer-mcp-community`](https://github.com/Adspirer/adspirer-mcp-community) repository (Apache-2.0). Anyone can read the code, contribute a plugin, or fork one. * **Analysis, not automation.** Plugins cluster, score, rank, format, and recommend on top of your ad data. A first example is a **keyword clusterer** (`cluster_keywords`) that groups your search terms into themed clusters. * **Reviewed and pinned.** A plugin only becomes available after an Adspirer maintainer reviews and merges it, and the server loads it from a **pinned commit** — so the code you run is the exact code that was reviewed. ## Why they're safe > [!NOTE] > > Community plugins are **read-only** to your ad accounts (v1). They can analyze and recommend, but they **cannot create, edit, pause, or delete** anything in your campaigns. * **Credential-free & sandboxed.** Plugins run in a separate, egress-locked sub-server. They never see your OAuth tokens or credentials. * **Read-only broker.** They reach your data only through a narrow read-only interface (list campaigns, get performance, analyze search terms, check connection status) — never a write path. * **Import-gated.** A load-time check rejects any plugin that tries to import something outside the allowed set. * **Separately metered.** Community-plugin calls draw on their own allowance, distinct from your core tool-call quota, so experimenting with them doesn't eat into your campaign-management budget. ## Using a plugin Discover and run a community analysis plugin. List the available Adspirer community plugins, then use the keyword clusterer to group my Google Ads search terms from the last 30 days into themed clusters and show me the biggest ones. ## Contributing a plugin Community plugins are a great way for agencies and power users to package the analysis they run over and over. Add a Python MCP analysis tool to the [public repository](https://github.com/Adspirer/adspirer-mcp-community), following the contribution guide; once a maintainer reviews and merges it and the commit is pinned, it appears for everyone. ## FAQ > **Can a community plugin change my campaigns or spend money?** > > No. Community plugins are read-only to your ad accounts in v1 — they analyze and recommend only. They run in a sandbox with no credentials and no write path, so there is no way for a plugin to alter a campaign or spend budget. > **How is this different from community playbooks?** > > **Community plugins** are open-source *tools* (extra analysis capabilities) shared through a public repo. [Community playbooks](/docs/agent-skills/ad-ops-agents#community-playbooks) are shareable *agent strategies* — the goal, rules, and guardrails of an [Ad Ops agent](/docs/agent-skills/ad-ops-agents), with no account data attached. Plugins add capabilities; playbooks add strategy. > **Do I have to install anything?** > > No. Approved community plugins are available through the `community_plugins` tool on the hosted server — your AI client discovers them automatically. There's nothing to install locally. ## Related > **[Autonomous Ad Ops Agents](/docs/agent-skills/ad-ops-agents)** > > Background agents that propose changes to an approval queue. > **[Tool Catalog](/docs/agent-skills/tools)** > > The full 400+ built-in tool reference. # Run the Adspirer Marketing Agent in Cursor Source: https://www.adspirer.com/docs/agent-skills/cursor-agent How the Adspirer performance marketing agent runs inside Cursor: the marketplace plugin, subagent architecture, 14 skills, 2 rules, memory, and the agent loop. Your AI advertising manager inside Cursor. One marketplace install gives you a **Cursor subagent** with 14 skills and 2 rules that auto-trigger the right workflow for every advertising task. ## How It Works Cursor's agent mode uses an agentic loop: you describe a task, it reasons, calls tools, reads results, and repeats. When your task involves advertising, Cursor delegates to the Adspirer subagent — which has its own prompt, memory, skills, and MCP tools. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[You] -->|"Create a LinkedIn campaign"| B[Cursor Agent] B -->|Spawns subagent| C[Performance Marketing Agent] C -->|Reads| D[BRAND.md + STRATEGY.md + MEMORY.md] C -->|Calls| E[Adspirer MCP Tools] E -->|OAuth| F[Google / Meta / LinkedIn / TikTok] C -->|Returns results| B B -->|Presents to you| A ``` ### What Makes Cursor Different Two things no other client gives Adspirer: 1. **Rules** (`.mdc` files) — they fire on context, not on a command. Mention a campaign and the brand context and safety workflow load themselves. 2. **14 separate skills** — one per platform and one per workflow, so the agent loads the TikTok pixel rules when you're on TikTok and nothing else. *** ## Install **1. Open Customize and install Adspirer** In Cursor, open **Customize** in the sidebar, search **adspirer**, select **Install**, and choose **user** scope (every project) or **project** scope (this folder only). From chat, `/add-plugin adspirer` does the same thing. **2. Sign in** The first tool call opens Adspirer's sign-in page. Sign in, authorize, and connect your ad accounts at [adspirer.com/connections](https://www.adspirer.com/connections). Full walkthrough with screenshots: [Cursor setup](/docs/ai-clients/cursor). The same listing installs into [Grok Bot](/docs/ai-clients/grok). ## What Gets Installed | Component | Count | Where it lands | Purpose | | - | - | - | - | | **MCP server** | 1 | Customize → MCP | 400+ advertising tools via OAuth | | **Subagent** | 1 | `performance-marketing-agent` | Agent prompt with brand awareness | | **Skills** | 14 | Customize → Agent Decides | Workflow instructions per platform and task | | **Rules** | 2 | Customize → Rules | Auto-load brand context, enforce the safety workflow | ![Cursor Marketplace listing for Adspirer showing 1 subagent, 14 skills, 2 rules, and 1 MCP server](https://mintcdn.com/adspirer/ktXbAHkqPipEy1iB/images/cursor/plugin-contents.png?fit=max\&auto=format\&n=ktXbAHkqPipEy1iB\&q=85\&s=ab886f0d17f74a6fd7a44234a179cf86) The Adspirer plugin on the Cursor Marketplace — 1 subagent, 14 skills, 2 rules, 1 MCP server > [!NOTE] > > Nothing is copied into `~/.cursor/` by hand any more. The old `install.sh` script is retired — if you ran it, delete the `adspirer-*` folders it left in `~/.cursor/skills/`, `~/.cursor/agents/`, and `~/.cursor/rules/` so they don't shadow the plugin. *** ## The 14 Skills Skills appear under **Agent Decides** in Customize. Cursor matches them from what you ask; the `/` command forces one. ### Behavior and contract | Skill | Command | What it does | | - | - | - | | **Agent** | `/adspirer-agent` | Sets agent behavior and the safety rules, then routes to the right skill below | | **MCP contract** | `/adspirer-mcp` | How to call the Adspirer hub — tool discovery, per-platform account IDs, quota, and the budget unit (account currency as a decimal, never cents) | ### Workflows | Skill | Command | Steps it follows | | - | - | - | | **Setup** | `/adspirer-setup` | Check connections → scan folder → pull live data → create `BRAND.md` + `STRATEGY.md` → present summary | | **Launch** | `/adspirer-launch` | Pick the channel for the goal → split the budget → research → build paused → confirm | | **Optimize** | `/adspirer-optimize` | Find waste per platform → negatives, exclusions, pacing → propose reallocation → ask before moving money | | **Performance review** | `/adspirer-performance-review` | Read context and strategy → pull every platform → unified scorecard → top 3 actions. Read-only | | **Creative** | `/adspirer-creative` | Read brand voice → pull converting search terms → write to each platform's character limits → diagnose creative fatigue | ### Platforms | Skill | Command | What it covers | | - | - | - | | **Google Ads** | `/adspirer-google-ads` | Search, PMax, Demand Gen, YouTube, Display, keywords, quality score, bid strategies, sitelinks and extensions, PMax asset groups | | **Meta Ads** | `/adspirer-meta-ads` | Facebook and Instagram — image, video, carousel, lead gen, ad sets, audiences, pixels, creative fatigue | | **Amazon Ads** | `/adspirer-amazon-ads` | Sponsored Products, Brands, Display — ASIN targeting, search-term reports, ACoS, bid optimization | | **LinkedIn Ads** | `/adspirer-linkedin-ads` | Sponsored content, single image, video, carousel, text ads, lead-gen forms, B2B targeting | | **TikTok Ads** | `/adspirer-tiktok-ads` | In-feed video, Spark Ads, carousel, app promotion, conversions | | **ChatGPT Ads** | `/adspirer-chatgpt-ads` | Chat-card ads inside ChatGPT responses, the one-shot launch tool, irreversible archiving | | **Docs** | `/adspirer-docs` | Questions about Adspirer itself — pricing, quota, supported platforms and clients, troubleshooting | Each platform skill carries the traps that account for most failures on that platform: TikTok's pixel-placement rule and the unsupported single-image ad, Meta's required Facebook page ID, LinkedIn's mandatory campaign group, Google's asset-bundle expiry and ad-group-ID mismatch. ### How Skills Work in Cursor 1. **Skill descriptions** are always in context — Cursor knows what's available 2. **Full skill content** loads when you invoke it or Cursor matches it automatically 3. You can invoke directly with `/adspirer-*` or just describe what you want Cross-platform wasted spend audit with savings estimate. Find wasted spend across all my platforms. Show me which keywords have spend but zero conversions, which Meta ads are fatigued, and how much I could save per month. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=agent-cta\&utm_content=cursor-agent)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. *** ## The Two Rules Rules are `.mdc` files that fire on context instead of on a command. You can toggle each between **Always**, **Agent Decides**, and **Manual** under **Customize → Rules**. ### brand-workspace Auto-loads brand context on every advertising task: * Reads `BRAND.md` before answering any advertising question * Reads `STRATEGY.md` for active directives, and treats them as binding * Reads past decisions from `.cursor/memory/performance-marketing-agent/MEMORY.md` * Bootstraps a new workspace when `BRAND.md` doesn't exist * Pulls fresh data rather than answering performance questions from memory * Updates context files when something significant changes ### use-adspirer Enforces workflow safety automatically: * Always checks connections first * Read-before-write enforcement * User confirmation before spend-affecting actions * Campaign creation in PAUSED status * Strategy directive checks before campaign creation * Mandatory ad extensions for Google Ads campaigns * Post-creation verification before reporting success ### Rules vs Skills | | Rules | Skills | | - | - | - | | **Trigger** | Automatically based on context | Manually via `/command` or AI-matched | | **Purpose** | Safety enforcement, context loading | Workflow instructions, tool sequences | | **Format** | `.mdc` files | `SKILL.md` files with frontmatter | | **What they do** | "Always check connections first" | "To create a campaign, follow these 12 steps" | Rules and skills work together. The rule ensures safety; the skill provides the detailed workflow. > [!NOTE] > > Without rules, you say "create a Google Ads campaign" and Cursor might jump straight to `create_search_campaign` — which fails because there's no keyword research, no asset validation, no strategy check. > > With rules, the same prompt triggers the full workflow automatically: connection check → strategy load → keyword research → asset validation → confirmation → creation → extensions → verification. *** ## Context Files The agent uses three persistent files. Cursor's is `BRAND.md` (vs Claude Code's `CLAUDE.md`). ### BRAND.md — Brand Context Created by `/adspirer-setup`. Contains brand overview, voice, audiences, connected platforms, budgets, KPI targets, and performance snapshot. | Section | Source | | - | - | | Brand Overview | Your docs + Adspirer data | | Brand Voice | Your docs (tone, style, prohibited words) | | Active Platforms | `get_connections_status` | | Budget & Guardrails | Your docs + campaign data | | Performance Snapshot | Last 30 days from Adspirer | If you already have a `BRAND.md` that isn't an Adspirer workspace — a software project's instructions, say — the agent leaves it untouched and tells you so, rather than writing over it. ### STRATEGY.md — Strategic Decisions Persists directives across sessions: ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} ### Google Ads AVOID: broad match "plumbing services" — competitor-dominated, $12+ CPC PREFER: exact match "emergency plumber [city]" — high intent, $4-6 CPC ``` ### MEMORY.md — Past Decisions Located at `.cursor/memory/performance-marketing-agent/MEMORY.md`. Tracks campaign actions, optimization results, and learnings. *** ## The Agent Loop When you invoke `/adspirer-performance-review` in Cursor: **1. Rule activates** `brand-workspace` fires, loading `BRAND.md` and `STRATEGY.md` into context. **2. Skill loads** Cursor matches the performance review skill and loads its full workflow instructions. **3. Agent spawns** The performance marketing subagent starts with brand context, strategy, and memory. **4. Data pull** For each connected platform, calls performance and wasted spend tools via Adspirer MCP. **5. Strategy check** Compares campaign data against `STRATEGY.md`. Flags "Strategy Drift" items. **6. Results** Presents a unified scorecard with recommendations and top 3 actions. *** ## Web Research Cursor's agent has access to `WebSearch` and `WebFetch` for competitive research. Before creating any campaign, the agent: 1. Crawls your website for positioning, pricing, and value propositions 2. Searches for and crawls competitor websites 3. Combines web data with Adspirer data (search terms, keyword volumes) 4. Presents a research brief before building your campaign *** ## Safety Rules | Rule | How It Works | | - | - | | User confirmation for spend | Agent always asks before creating campaigns or changing budgets | | Campaigns created PAUSED | All `create_*` tools default to PAUSED status | | Read-before-write | Connection check → research → validate → create | | Never retry on error | Reports the error instead of retrying | | Budget guardrails | Checks `BRAND.md` budget limits before spend-affecting actions | | Strategy compliance | Reads `STRATEGY.md` and flags conflicts | | Post-creation verification | Verifies ad groups, keywords, ads, and extensions | | Rules enforcement | `use-adspirer` auto-triggers safety checks | | No credentials in the plugin | OAuth 2.1 with PKCE; the marketplace build ships no hooks or executables and talks only to `https://mcp.adspirer.com/mcp` | *** ## Comparison with Other Clients | Feature | Cursor | Grok Bot | Claude Code | Codex | | - | :-: | :-: | :-: | :-: | | Install from | Customize | Plugins | `/plugin install` | `codex plugin` | | Agent type | Subagent | Bot description | Subagent | Agent config | | Brand context | `BRAND.md` | Bot description | `CLAUDE.md` | `AGENTS.md` | | Skills | 14 | 14 | 1 comprehensive | 5 separate | | Commands | `/adspirer-*` | -- | `/adspirer:*` | `$adspirer-*` | | Memory | `MEMORY.md` | -- | `MEMORY.md` | Not available | | Rules (auto-trigger) | 2 rule files | -- | -- | Safety rules | | Scheduling | Adspirer tools | Routines | Adspirer tools | Adspirer tools | | Web research | `WebSearch` + `WebFetch` | Built in | `WebSearch` + `WebFetch` | Not available | *** ## FAQ > **Do I need the rules to use Adspirer?** > > No, but they make everything smoother. Without rules, you need to be more explicit ("first check my connections, then research keywords"). With rules, safety checks and context loading happen automatically. > **Can I edit the rules and skills?** > > The plugin's copies update with the plugin, so edit them by adding your own alongside. Put project rules in `.cursor/rules/` and personal skills in `~/.cursor/skills/` — yours load next to Adspirer's. To change a default outright, fork [the plugin repo](https://github.com/Adspirer/adspirer-cursor-plugin) and load it from `~/.cursor/plugins/local`. > **What's the difference between the subagent and Composer?** > > Cursor's Composer is the main agent mode for coding tasks. The Adspirer subagent is a specialized agent that Composer delegates to when advertising tasks come up. The subagent has its own context, so ad workflows don't bloat your coding session. > **Can I use Adspirer in Cursor without the agent?** > > Yes. The agent is one part of the plugin, and the 400+ tools work from any Cursor chat whether or not the subagent is invoked. Install the plugin from the Cursor Marketplace either way. It's **Verified by Cursor**, and it's the supported way to connect. Don't add the MCP server by hand. You'd lose brand awareness, workflow enforcement, strategy persistence, and memory, and a second copy of the server duplicates every tool. > **Is the plugin open source?** > > Yes — [Adspirer/adspirer-cursor-plugin](https://github.com/Adspirer/adspirer-cursor-plugin), MIT licensed. Cursor requires marketplace plugins to be open source and reviews every update before it ships. ## Related Documentation * [Cursor Setup](/docs/ai-clients/cursor) — installation guide with screenshots * [Grok Bot Setup](/docs/ai-clients/grok) — the same plugin, running in the cloud * [Claude Code Agent](/docs/agent-skills/claude-code-agent) — How Adspirer works in Claude Code * [Codex Agent](/docs/agent-skills/codex-agent) — How Adspirer works in Codex * [Performance Marketing Agent](/docs/agent-skills/agent) — Architecture overview * [Skill Reference](/docs/agent-skills/skills) — All skills with invocation details * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Diagnostic & Helper Tools | Adspirer Source: https://www.adspirer.com/docs/agent-skills/diagnostic-helper-tools Adspirer's free, read-only get-started, pre-flight, and diagnostic tools — validate a campaign draft, explain platform errors, and confirm a campaign is live. Quota-free on every plan. Adspirer ships a group of **9 read-only "get unstuck" tools** that help you start, pre-flight, and troubleshoot — without touching a single campaign. They cover the moments around the work: figuring out the best next step, checking a campaign draft against the platform's rules before you create it, turning a cryptic platform error into a plain-language fix, and confirming a campaign actually went live. > [!NOTE] > > **These tools are quota-free.** Calling any Diagnostic & Helper tool never counts against your monthly tool-call limit, and they're available on **every plan, including Free**. They're also all **Read** tools — they never create, edit, or pause anything. Any actual fix is something your assistant does afterward with the normal platform tools, with your confirmation. Your AI assistant discovers and calls these automatically — you don't need to memorize names. Ask things like *"what should I do first?"*, *"will this campaign draft be accepted?"*, *"why did that fail?"*, or *"is my campaign actually running?"* and the right tool runs. ## Getting started The fastest way to go from "connected" to "doing something useful." Each tool reads your real connected accounts and data, so the suggestions name your business and platforms — not generic advice. | Tool | What it does | | - | - | | `start_here` | The single best next step for your exact state — not connected yet, connected but no data, or already running campaigns — with a worked example prompt. | | `suggest_next_action` | Ranks the highest-value things you can do right now from your live data: analyze, find wasted spend, set a monitor, optimize, or launch. | | `list_what_i_can_do` | A personalized capability menu organized by goal (Analyze & Report, Monitor & Alert, Manage & Optimize, Create & Launch), filtered to your connected platforms. | Personalized first step based on your connected accounts. I just connected Adspirer — what should I do first? ## Before launching a campaign Catch the problems that cause "campaign creation failed" *before* anything reaches the ad platform. These work across Google Ads, Meta, TikTok, and LinkedIn. | Tool | What it does | | - | - | | `get_campaign_spec` | Returns the exact required fields, character limits, asset requirements, and allowed values for a given campaign type, so a create satisfies every constraint. | | `validate_campaign_draft` | Dry-run validates a fully assembled campaign draft against the platform's spec (no write) and returns per-field issues — character limits, item counts, missing required fields. | Check a campaign draft against the platform's rules before creating it. Before you create anything, show me the spec for a Meta conversions campaign and dry-run my draft against it. ## When something fails Turn an opaque ad-platform error into a clear cause and next step — and confirm a fix actually worked. | Tool | What it does | | - | - | | `explain_platform_error` | Translates a raw ad-platform error message into a plain-language cause and the exact step to fix it. | | `why_did_this_fail` | Summarizes your recent failed actions and the errors behind them, so the issue can be corrected and retried. | | `verify_campaign_is_live` | After you create a campaign, checks it actually exists and is serving (not paused, not on a \$0 budget) with a **real live check against the platform** — Google Ads, Meta, TikTok, or LinkedIn. | > [!TIP] > > `why_did_this_fail` is the one to reach for when you're not sure *where* a problem is. It names the real error behind each of your recent failed calls, which is usually enough to tell an expired **AI-client connection** (your ChatGPT/Claude link to Adspirer) apart from an **ad-platform sign-in** — two different connections that customers regularly confuse. See [Authentication](/docs/knowledge-base/security) for how the two layers differ, and [Support](/docs/knowledge-base/support) for the reconnect steps. Find the real error behind a failed action. My Google Ads data isn't loading. Show me why my recent calls failed and what the actual error was. ## See your value What your plan has actually delivered this period. | Tool | What it does | | - | - | | `usage_value_summary` | Your plan as value delivered: tool calls used vs. included this period and what those calls accomplished. | For "what moved since last week", ask for performance directly — your assistant reads it from the platform tools on [Google Ads](/docs/ad-platforms/google-ads), [Meta](/docs/ad-platforms/meta-ads), [TikTok](/docs/ad-platforms/tiktok-ads), [LinkedIn](/docs/ad-platforms/linkedin-ads), or [Amazon](/docs/ad-platforms/amazon-ads), which cover a date range you choose rather than a fixed window. See what your plan delivered this period, then what moved. Summarize what my Adspirer usage delivered this period, then show me what changed across my ad accounts in the last 7 days. ## Interactive cards in ChatGPT & Claude In **ChatGPT** and **Claude**, these tools render as branded, interactive cards instead of plain text — a setup checklist, a usage meter, an account switcher. The cards adapt to light and dark themes, and the buttons can kick off the next step. On any client that doesn't render widgets (and in terminal clients like [Claude Code](/docs/ai-clients/claude-code) or [Cursor](/docs/ai-clients/cursor)), the same answer falls back to clean text — nothing is lost, it just isn't a card. > [!NOTE] > > Interactive cards are built on the open **MCP-Apps** standard (SEP-1865) that ChatGPT and Claude both support. They render entirely from the tool's own data — no external page loads — and any link (upgrade, connect a platform) opens through your client to [adspirer.ai](https://adspirer.ai). ## Availability | | | | - | - | | **Plans** | All, including **Free** | | **Quota** | Quota-free — never counts against your tool-call limit | | **Tool type** | Read-only (no campaign changes) | | **Clients** | Every connected AI client; interactive cards render in ChatGPT and Claude | | **Platforms** | Google Ads, Meta, TikTok, LinkedIn | ## Recently withdrawn Four tools were pulled from this group on **August 24, 2026**: `diagnose_my_setup`, `preflight_campaign`, `whats_changed_since_last_visit`, and `weekly_opportunities`. They misread which ad platform you meant — saying "meta" could fail to match the account's canonical `meta_ads` name and produce a "no account connected" answer on an account that was connected and working. Your assistant no longer sees them, so treat them as gone rather than waiting for them to come back. The nine tools above are unaffected. For the job `diagnose_my_setup` used to do, ask *"why did that fail?"* — see the [Tip](#when-something-fails) above. ## Related Documentation * [Tool Catalog](/docs/agent-skills/tools) — every Adspirer tool by platform * [Agent Skills Overview](/docs/agent-skills/overview) — how skills enforce the right workflow * [Authentication & Security](/docs/knowledge-base/security) — the difference between your AI-client connection and ad-platform sign-in * [Multi-Account](/docs/knowledge-base/multi-account) — switching active accounts from chat * [Support](/docs/knowledge-base/support) — when to escalate beyond self-diagnosis * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Your free paid media skill Source: https://www.adspirer.com/docs/agent-skills/free-paid-media-skill Download your free paid media skill, add it to Claude, ChatGPT, or a coding agent, and try eight starter prompts for your ads. > **A free skill for your agent** > > Agent instructions and eight ready-to-use prompts in one file. Keep it, customize it, or share this page with a friend. ## Add to your agent Download the file, choose your agent below, then try a starter prompt. The prompts are also at the top of the skill document, ready to copy and paste. **Claude** **1. Open Skills** Open **Settings → Customize → Skills**, then choose **Upload skill**. **2. Upload your download** Choose **SKILL.md** and click **Save**. You can upload the Markdown file directly. ![Claude Upload skill screen showing support for Markdown files with a YAML skill name and description](https://mintcdn.com/adspirer/M0GNQwpJ_SUIcx_O/images/free-skill/claude-upload-skill.png?fit=max\&auto=format\&n=M0GNQwpJ_SUIcx_O\&q=85\&s=7d7b55ad4e9de7044ac5a1740871490d) Upload the Markdown file in Claude's Skills settings. **3. Try a prompt** Open a conversation and paste one of the [starter prompts below](#try-a-starter-prompt). **ChatGPT** **1. Open Skills** Open **Plugins → Skills**, then click **+**. **2. Upload your download** Choose **Upload from your computer** and select **SKILL.md**. Complete the save flow shown in your workspace. If you downloaded an earlier copy, rename it to exactly **SKILL.md** before uploading. ![ChatGPT Plugins and Skills page with Upload from your computer selected in the plus menu](https://mintcdn.com/adspirer/M0GNQwpJ_SUIcx_O/images/free-skill/chatgpt-skills.png?fit=max\&auto=format\&n=M0GNQwpJ_SUIcx_O\&q=85\&s=11b7b2daa2a9f2e6f60804bdd5b35b84) Use the + menu on ChatGPT's Skills tab to upload your skill. **3. Try a prompt** Open a conversation and paste one of the [starter prompts below](#try-a-starter-prompt). **Coding agent** **1. Open your repository** Open the local repository where you want to use the skill in Claude Code, Codex, Cursor, or your preferred coding agent. **2. Attach the file and ask your agent to install it** Attach **SKILL.md**, then copy this message: Install the free skill in your local repository Read the attached paid media skill and add it to this local repository using your supported skills format. Keep the included starter prompts. Preserve existing repository instructions, avoid duplicate installations, and tell me where you saved the skill. **3. Try a prompt** Once your agent confirms where it saved the skill, paste one of the [starter prompts below](#try-a-starter-prompt). > [!NOTE] > > Skills availability and menu labels can vary by client and workspace. This file provides instructions; live account analysis also needs Adspirer connected in your agent. If you still need to connect, follow the [client setup guide](/docs/add-to-your-agent). ## Try a starter prompt These are the same eight prompts included in your download. Pick one and paste it into your agent after adding the skill. They ask for analysis or drafts; they do not ask your agent to change live ads. > **Understand performance** > > Starter prompt 1 > > Using Adspirer, review the last 30 complete days for one connected ad account. Show spend, conversions, and cost per conversion, then give me the three most useful things to investigate. Ask which account if needed. > > Starter prompt 2 > > Using Adspirer, compare the last 7 complete days with the previous 7 for one connected ad account. What changed most, and what evidence could explain it? Separate observed changes from possible causes. > **Reduce wasted spend** > > Starter prompt 3 > > Using Adspirer, find the strongest signs of wasted spend in one connected ad account over the last 30 complete days. Rank up to three opportunities by evidence and spend affected. Recommend changes for review; do not apply them. > > Starter prompt 4 > > Using Adspirer, review how budget is split across campaigns in one connected ad account. Ask for my goal and target if needed, then propose a reallocation within the current total budget. Show tradeoffs; do not change anything. > **Plan a campaign** > > Starter prompt 5 > > Help me plan a campaign using Adspirer. Ask for my offer, audience, location, goal, and budget, then recommend a suitable connected platform and a campaign structure. Keep this as a draft for review. > > Starter prompt 6 > > Help me review a campaign idea before launch. Check the offer, landing page, audience, creative, budget, and measurement plan. Use Adspirer data where available, identify what is missing, and give me a launch checklist. Do not create or activate anything. > **Improve creative** > > Starter prompt 7 > > Help me write three ad-copy directions for my offer and chosen platform. Use Adspirer to review existing ads if available; ask for the offer and brand voice if needed. Explain what each direction tests and keep all copy as drafts. > > Starter prompt 8 > > Using Adspirer, check whether creative fatigue could explain weaker performance in one connected ad account. Use the metrics available on that platform, explain the limits of the evidence, and suggest a creative test. Do not change any ads. ## Want a starting point tailored to your account? > **[Explore the Agent Playbook](/docs/agent-skills/prompt-engineering-playbook)** > > The free skill is generic. The Agent Playbook adds account-specific agent instructions, an AGENTS.md, 24 prompts tailored from live account data, and tailored skills. # Run the Adspirer Marketing Agent in OpenClaw Source: https://www.adspirer.com/docs/agent-skills/openclaw-agent How the Adspirer advertising agent runs inside OpenClaw: bundled SKILL.md file, zero-config setup, claw.json manifest, tool groups, and safety model. Your AI advertising manager in OpenClaw. The Adspirer plugin ships a **14KB SKILL.md** instruction file that turns OpenClaw into a specialized advertising agent — pre-configured, pre-trained, ready to run campaigns. ## How It Works OpenClaw discovers the SKILL.md file bundled with the plugin and loads it when your request matches advertising keywords. The skill file teaches OpenClaw the right tool sequences, safety rules, and platform-specific nuances. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[You] -->|"Create a Google Search campaign"| B[OpenClaw] B -->|Loads SKILL.md| C[Adspirer Ads Agent] C -->|Calls| D[Adspirer MCP Tools] D -->|OAuth| E[Google / Meta / LinkedIn / TikTok] C -->|Returns results| B B -->|Presents to you| A ``` ### What Makes OpenClaw Different OpenClaw has some unique characteristics compared to Claude Code, Cursor, and Codex: 1. **Bundled skill** — The 14KB SKILL.md ships inside the plugin. No separate skill or agent installation. 2. **No context files** — OpenClaw doesn't use `CLAUDE.md`, `BRAND.md`, or `AGENTS.md`. It relies on the SKILL.md and your prompts for context. 3. **No memory or strategy** — No `MEMORY.md` or `STRATEGY.md`. Each session starts fresh. 4. **Tool groups** — You can enable/disable entire platforms or cherry-pick individual tools. 5. **claw\.json manifest** — Defines plugin metadata, permissions, and network access. *** ## What Gets Installed One command installs everything: | Component | File | Purpose | | - | - | - | | **MCP Server** | Plugin config | 400+ advertising tools via OAuth | | **Skill file** | `SKILL.md` (bundled) | Complete workflow instructions for all platforms | | **Manifest** | `claw.json` | Plugin metadata, permissions, network access | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins install openclaw-adspirer ``` No separate agent, skill, or rules installation needed. Restart OpenClaw after installing. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=agent-cta\&utm_content=openclaw-agent)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. *** ## The Skill File Most MCP integrations give you raw tool access. OpenClaw gives you a 14,400-character instruction manual that covers: * **400+ tools documented** — every parameter, every edge case * **6 complete workflows** — performance analysis, keyword research, campaign creation (per platform), budget optimization, account management, automation * **Platform quick reference** — when to use each platform, minimum budgets, best use cases * **Safety rules** — what to always check first, what requires user confirmation, what never to retry * **Troubleshooting guide** — common errors and how to fix them This isn't configuration. It's training. OpenClaw reads the SKILL.md file and knows how to behave like an expert advertising manager. ### How the Skill Loads 1. OpenClaw discovers the SKILL.md from the plugin's `claw.json` manifest (`"entry": "SKILL.md"`) 2. When your request matches advertising keywords (PPC, ad campaign, ROAS, keyword research, etc.), the skill activates 3. OpenClaw follows the workflow instructions in the skill file — not guessing tool order 4. Safety rules from the skill enforce confirmation gates and PAUSED campaign creation *** ## Tool Groups The plugin organizes tools into platform groups you can enable or disable: | Group | Platform | Tools | | - | - | :-: | | `google_ads` | Google Ads | 39 | | `meta_ads` | Meta Ads | 20 | | `linkedin_ads` | LinkedIn Ads | 28 | | `tiktok_ads` | TikTok Ads | 4 | | `manus` | Automation | 8 | | `system` | Cross-Platform | 4 | ### Filtering by Platform Enable only the platforms you use: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} config: enabledGroups: ["google_ads", "meta_ads"] ``` Or cherry-pick individual tools: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} config: enabledTools: ["get_campaign_performance", "research_keywords", "analyze_wasted_spend"] ``` *** ## Example Prompts Google Search campaign with keyword research and negative keywords. Create a Google Ads search campaign for my consulting firm: * Service: fractional CFO services for startups * Target: startup founders and CEOs at Series A-B companies * Budget: \$80/day * Research keywords with real CPC data * Add negative keywords for "jobs", "salary", "free" Cross-platform performance report with wasted spend analysis. Generate a full performance report for the last 30 days. Pull data from all connected platforms. Include per-platform metrics (spend, conversions, CPA, ROAS), wasted spend analysis, and top 5 recommendations for next month. *** ## The claw\.json Manifest The plugin includes a manifest that defines metadata and permissions: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "adspirer-ads-agent", "version": "1.2.1", "displayName": "Adspirer Ads Agent", "category": "marketing", "entry": "SKILL.md", "permissions": { "network": ["mcp.adspirer.com", "www.adspirer.com"] } } ``` The `entry` field points to the SKILL.md — this is how OpenClaw knows which file contains the agent's instructions. Network permissions restrict the plugin to Adspirer's servers only. *** ## Safety Rules The skill file includes safety rules that OpenClaw enforces automatically: | Rule | How It Works | | - | - | | User confirmation for spend | Agent asks before creating campaigns or changing budgets | | Campaigns created PAUSED | All `create_*` tools default to PAUSED status | | Read-before-write | Connection check → research → validate → create | | Never retry on error | Reports errors instead of retrying campaign creation | | Platform minimums enforced | Google/LinkedIn \$10/day, Meta no minimum | | Post-creation verification | Verifies ad groups, keywords, ads after creation | *** ## Comparison with Other Clients | Feature | OpenClaw | Claude Code | Cursor | Codex | | - | :-: | :-: | :-: | :-: | | Agent type | Bundled skill | Subagent | Subagent | Agent config | | Brand context file | None | `CLAUDE.md` | `BRAND.md` | `AGENTS.md` | | Skills | 1 bundled | 1 comprehensive | 5 separate | 5 separate | | Memory | Not available | `MEMORY.md` | `MEMORY.md` | Not available | | Strategy | Not available | `STRATEGY.md` | `STRATEGY.md` | `STRATEGY.md` | | Web research | Not available | `WebSearch` + `WebFetch` | `WebSearch` + `WebFetch` | Not available | | Tool filtering | Group + individual | -- | -- | -- | | Setup | 1 command | Plugin install | Bash installer | Bash installer | *** ## FAQ > **What's the difference between OpenClaw and other MCP clients?** > > Other clients give you access to Adspirer's tools and require separate agent/skill installation. OpenClaw bundles everything in one plugin — the SKILL.md instruction file ships inside the plugin itself. Less setup, more intelligence out of the box. > **Can I edit the skill file?** > > Yes. The SKILL.md is in the plugin directory. Edit it to change default behaviors, add custom workflows, or modify safety rules. Changes take effect on the next OpenClaw restart. > **Why doesn't OpenClaw have memory or strategy files?** > > OpenClaw doesn't have a persistent memory system like Claude Code or Cursor. Each session starts fresh. If you need cross-session persistence, use Claude Code or Cursor instead. > **Can I use only Google Ads tools?** > > Yes. Set `enabledGroups: ["google_ads"]` in your config to disable all other platforms. Or use `enabledTools` to cherry-pick specific tools. ## Related Documentation * [Claude Code Agent](/docs/agent-skills/claude-code-agent) — How Adspirer works in Claude Code * [Cursor Agent](/docs/agent-skills/cursor-agent) — How Adspirer works in Cursor * [Codex Agent](/docs/agent-skills/codex-agent) — How Adspirer works in Codex * [Performance Marketing Agent](/docs/agent-skills/agent) — Architecture overview * [Skill Reference](/docs/agent-skills/skills) — All 5 skills with invocation details * [OpenClaw Setup](/docs/ai-clients/openclaw) — Installation guide * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Agent Skills: AI Workflows for Ad Campaigns Source: https://www.adspirer.com/docs/agent-skills/overview Turn your AI assistant into an expert ad manager. Skills teach the right workflow for Adspirer's 400+ tools: research, validate, then launch safely. [Analyze Campaign Performance Directly from Claude with Adspirer](https://www.youtube.com/embed/kdUbQ7dvdXU) Analyze Campaign Performance Directly from Claude ## The Problem Skills Solve When you connect an AI assistant to Adspirer, it gains access to 400+ advertising tools. That's powerful. It's also overwhelming. Without guidance, the AI sees a list of tools and has to guess which order to use them. Should it research keywords before creating a Google Search campaign? Should it validate creative assets before launching a Meta campaign? Should it check connection status before pulling performance data? The AI doesn't know. So it guesses. Sometimes it guesses right. Sometimes it tries to create a campaign without keyword research, fails validation, and wastes your time. Sometimes it retries a failed campaign creation five times, burning through your tool call quota. Skills fix this. ## What Skills Are Skills are instruction files (SKILL.md) that teach AI assistants the *right way* to use Adspirer's tools. Think of them as a training manual for advertising best practices. A skill file contains: * **Workflows:** Step-by-step sequences for common tasks ("to create a Google Search campaign, first research keywords, then validate assets, then create") * **Safety rules:** Critical guidelines ("always get user confirmation before spending money," "campaigns are created PAUSED," "never retry campaign creation on error") * **Tool reference:** Descriptions of all 400+ tools with parameters and use cases * **Platform guidance:** When to use each ad platform, minimum budgets, best practices * **Troubleshooting:** Common errors and how to handle them ## Before vs. After Skills ### Without Skills **You:** "Create a Google Ads campaign for my SaaS product" **AI:** Immediately calls `create_search_campaign` **Result:** Error: "No keywords provided" **AI:** Retries with generic keywords **Result:** Error: "No validated assets" **AI:** Gives up or suggests manual intervention ### With Skills **You:** "Create a Google Ads campaign for my SaaS product" **AI:** Follows the workflow: 1. Calls `get_connections_status` (verify you're managing the right account) 2. Calls `research_keywords` with your product description 3. Shows you keyword suggestions with real CPC data 4. Calls `discover_existing_assets` (check if you have images/headlines already) 5. Calls `suggest_ad_content` if you need new headlines/descriptions 6. Calls `validate_and_prepare_assets` 7. Calls `create_search_campaign` with all validated data 8. Asks for your confirmation before creating the campaign 9. Campaign created PAUSED, ready for your review Skills turn a vague prompt into a complete, validated workflow. ## Supported AI Clients | AI Client | Skills Support | Install Location | | - | - | - | | [Claude Code](/docs/ai-clients/claude-code) | Full + Slash Commands | `~/.claude/skills/` (via plugin) | | [Cursor](/docs/ai-clients/cursor) | Full + Subagent + Rules | Verified by Cursor marketplace plugin | | [Grok Bot](/docs/ai-clients/grok) | Full (all 14 skills) | Official Adspirer for Grok Bot plugin | | [Codex](/docs/ai-clients/codex) | Full + Agent Config | `~/.agents/skills/` + `~/.codex/agents/` | | [OpenClaw](/docs/ai-clients/openclaw) | Bundled (14.4KB SKILL.md) | Auto-installed with plugin | | [Windsurf](/docs/ai-clients/windsurf) | Coming soon | -- | | [Claude](/docs/ai-clients/claude) (Web/Desktop/Cowork) | Full (15 skills) + Slash Commands | Adspirer plugin from Anthropic's directory (**Customize → Plugins**) | | [ChatGPT](/docs/ai-clients/chatgpt) | Plugin | Built into the Adspirer plugin | | [Perplexity](/docs/ai-clients/perplexity) | Supported | Upload via **Computer → Skills** | | [Manus](/docs/ai-clients/manus) | Skills (GitHub import) | Import via **Settings → Skills** | ## How to Install Skills Installation varies by client. All skills are available in the [ads-mcp GitHub repository](https://github.com/amekala/ads-mcp). ### Claude (Web / Desktop) Nothing to upload. Add the [Adspirer plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory) from **Customize → Plugins** (search "Adspirer" and click **Add**). It installs 15 skills, 5 slash commands, and an agent together with the Anthropic-verified **Adspirer Ads & Performance Marketing Agent** connector. See the [Claude Setup Guide](/docs/ai-clients/claude#setup-2-minutes). ### Claude Code One command installs the MCP server, skills, slash commands, and agent together. Available on the official Anthropic marketplace, no setup needed: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin install adspirer-ads-agent@claude-community ``` ### Cursor and Grok Bot Adspirer is on the [Cursor Marketplace](https://cursor.com/marketplace/adspirer), marked **Verified by Cursor**. One install brings the MCP server, the performance marketing subagent, all 14 skills, and 2 rules. In Cursor, open **Customize** in the sidebar, search **adspirer**, and select **Install** — or run this in chat: ``` /add-plugin adspirer ``` In [Grok Bot](/docs/ai-clients/grok), open [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) and click **Add to Grok Bot**, or add it from **Marketplace** at the bottom of the sidebar. Same listing, separate install. Cursor's rules are the part no other client has: `.mdc` files that fire on context rather than on a command, so brand context loads and the safety workflow runs without you asking. ([Full setup](/docs/ai-clients/cursor)) ### Codex **Option A: One-command installer (recommended)** — installs MCP server, agent config, and all 5 skills: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh) ``` **Option B: Manual skill install:** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git clone https://github.com/amekala/ads-mcp.git /tmp/ads-mcp mkdir -p ~/.agents/skills cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-ads ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-setup ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-performance-review ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-write-ad-copy ~/.agents/skills/ cp -r /tmp/ads-mcp/plugins/codex/adspirer/skills/adspirer-wasted-spend ~/.agents/skills/ ``` ### Perplexity Computer 1. Download the [SKILL.md file](https://github.com/amekala/ads-mcp/raw/main/shared/skills/adspirer-ads/SKILL.md) from GitHub 2. In Perplexity Computer, click **Skills** in the left sidebar 3. Click **+ Create skill** → drag and drop the `SKILL.md` file 4. The skill appears as **adspirer-ads** — Perplexity applies it automatically when you ask about advertising See the [Perplexity Setup Guide](/docs/ai-clients/perplexity) for screenshots. ### OpenClaw Skills are bundled with the plugin. No separate installation needed: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins install openclaw-adspirer ``` ## What Skills Include ### 1. Core Workflows Six proven workflows for common advertising tasks: * **Performance Analysis:** Cross-platform reporting, anomaly detection, wasted spend audits * **Keyword Research:** Google Ads keyword discovery with real CPC data * **Campaign Creation:** Platform-specific flows for Google, Meta, Amazon, ChatGPT Ads, LinkedIn, TikTok * **Budget Optimization:** Reallocate spend based on ROAS or CPA * **Account Management:** Switch accounts, check usage, manage connections * **Automation:** Schedule briefs, create monitors, generate reports See [detailed workflow documentation](/docs/agent-skills/workflows). ### 2. Safety Rules Critical guardrails to prevent expensive mistakes: * **Always check connections first:** Run `get_connections_status` before using platform-specific tools * **User confirmation required:** Ask before any action that affects spend (campaign creation, budget changes) * **Campaigns created PAUSED:** Never launch campaigns live -- user reviews first * **Read-before-write:** Research keywords before creating Google Search campaigns, validate assets before launching * **Never retry campaign creation:** If it fails, report the error and wait for user input * **Platform minimums:** Google $10/day, Meta $5/day, Amazon $1/day, ChatGPT Ads $1/day, LinkedIn $10/day, TikTok $20/day ### 3. Tool Catalog Complete reference of all 400+ tools with: * Tool name and category * Type (Read vs. Write) * Description and use cases * Required and optional parameters * Example calls See [full tool catalog](/docs/agent-skills/tools). ### 4. Platform Quick Reference | Platform | Best For | Min Budget | | - | - | - | | Google Ads | High-intent search traffic | \$10/day | | Meta Ads | Demand generation, visual products | \$5/day | | Amazon Ads | Retail purchase intent (Sponsored Products / Brands / Display) | \$1/day | | ChatGPT Ads | Pay-per-click chat-card ads inside ChatGPT | \$1/day | | LinkedIn Ads | B2B lead generation | \$10/day | | TikTok Ads | Gen Z/Millennial reach, viral creative | \$20/day | ### 5. Troubleshooting Guide Common errors and how to handle them: * "Connection not found" -- Run `get_connections_status` and reconnect the platform * "Asset validation failed" -- Check image dimensions, file size, URL accessibility * "Campaign creation failed" -- Verify all workflow steps were completed in order * "Budget below minimum" -- Increase to platform minimum ($10/day for Google/LinkedIn, $5/day for Meta, $1/day for Amazon/ChatGPT, $20/day for TikTok) ## Why Skills Matter Skills transform a tool connection into an advertising management *system*. ### Without Skills * The AI guesses tool order * Workflows fail mid-execution * You spend time debugging errors * Campaign creation takes 10+ prompts back-and-forth * Risk of expensive mistakes (wrong budget, skipped validation) ### With Skills * The AI follows proven workflows * Workflows complete successfully on first try * Safety rules prevent expensive mistakes * Campaign creation takes 1-2 prompts * You review and approve instead of troubleshooting ## FAQ > **Do I need skills to use Adspirer?** > > No. Skills are optional but highly recommended. Without skills, you'll need to be more explicit in your prompts ("first research keywords, then validate assets, then create the campaign"). With skills, the AI knows to do this automatically. > **Can I customize skills for my workflow?** > > Yes. Skills are plain markdown files. Edit them to change default behaviors, add custom workflows, or modify safety rules. Changes take effect immediately (or after restarting your AI client). > **Do skills work with ChatGPT and Claude web?** > > **Claude:** Yes. Go to **Customize → Skills** in Claude and upload the Adspirer skill. See the [Claude Setup Guide](/docs/ai-clients/claude#setup-2-minutes) for instructions. > > **ChatGPT:** No. ChatGPT doesn't support skills files. It uses Adspirer via MCP connectors, which have full tool access but no workflow enforcement. > **How big are skill files?** > > It varies by client: > > * **Claude Code / Cursor:** \~8KB SKILL.md > * **Codex:** \~8KB SKILL.md > * **OpenClaw:** 14.4KB SKILL.md (most comprehensive) > **Do skills slow down the AI?** > > No. The AI reads the skill file once when it starts, not on every prompt. There's no performance impact. ## Related Documentation * [Core Workflows](/docs/agent-skills/workflows) -- Step-by-step flows for campaign creation, optimization, and analysis * [Tool Catalog](/docs/agent-skills/tools) -- Full reference of all 400+ Adspirer tools * [Autonomous Ad Ops Agents](/docs/agent-skills/ad-ops-agents) -- Give a plain-English goal and cadence; every proposed change lands in an approval queue for your review * [Community Plugins](/docs/agent-skills/community-plugins) -- Open-source, read-only community analysis tools * [Claude Code Setup](/docs/ai-clients/claude-code) * [Cursor Setup](/docs/ai-clients/cursor) * [OpenClaw Setup](/docs/ai-clients/openclaw) * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Prompt Engineering Playbook: A Trained Agent for One Ad Account Source: https://www.adspirer.com/docs/agent-skills/prompt-engineering-playbook The Prompt Engineering Playbook is a one-time $39 add-on that generates a custom agent skill, an account dossier, a prompt book, and agent instructions from your own ad account — then hands you the files to install in Claude, ChatGPT, Claude Code, Cowork, Cursor, or Codex. The **Prompt Engineering Playbook** is a set of agent files generated from **one of your ad accounts** — its campaign structure, spend history, and current state — and handed to you as a download you install in your AI client. It answers the question people ask after connecting Adspirer: *"the tools work, but how do I actually get good at this?"* Instead of you learning prompt engineering, the playbook writes the prompts, the instructions, and the account briefing for you. > [!NOTE] > > **The single most important thing on this page: this is a one-time purchase, not a subscription.** > You pay **\$39 once** for a given ad account and nothing recurs — no monthly charge, no renewal, no > second bill. It is separate from your Adspirer plan, which continues to work exactly as before. The > files are yours to keep, and rebuilding them later is free and unlimited. ## What it is — and what it is not Adspirer ships **13 free [Agent Skills](/docs/agent-skills/skills)** that teach any assistant how to run ads in general: how to structure a Google Search campaign, what Meta needs before a launch, the safety rules. Every plan gets those, at no cost. The Prompt Engineering Playbook is the layer above that. It is not general advertising knowledge — it is **your account**, written down. | | Free Agent Skills | Prompt Engineering Playbook | | - | - | - | | **Scope** | Advertising in general | **One specific ad account** | | **Knows your campaigns** | No | **Yes** — read from the live account | | **Knows your spend and currency** | No | **Yes** | | **Cost** | Free on every plan | **\$39 once, per ad account** | | **Who writes it** | Adspirer, for everyone | Generated for you, from your data | You want both. The free skills are the grammar; the playbook is the briefing. ## What you get The download is a `.zip` laid out to the open [Agent Skills](https://agentskills.io) format, so the same folder works across clients. **One zip, one folder, flat inside** — only `references/` nests, because that's the spec's progressive-disclosure mechanism (those files load on demand instead of on every activation): ``` -expert-/ ├── SKILL.md # the operating doctrine, pinned to your account ├── AGENTS.md # your account's instructions, in the agents.md standard ├── PROMPTBOOK.md # the prompt book, organized by level and workflow ├── README.md # where each piece goes, per client └── references/ ├── account-profile.md # the dossier — your account's state and priorities └── working-with-adspirer.md # how the agent should call Adspirer's tools ``` | File | What it does | Where it goes | | - | - | - | | **`SKILL.md`** | The agent's operating doctrine for this account. Loads automatically when you ask about this account — you never invoke it by name. | Uploaded or dropped in as a skill | | **`AGENTS.md`** | The constitution — the account-pinned rules, in the [agents.md](https://agents.md/) standard. Read automatically by folder-based clients, and the text you paste into a chat client's instructions field. | Project root for coding agents; instructions field for chat clients | | **`PROMPTBOOK.md`** | The starting prompts — organized by level and workflow, written against *your* campaigns. | You read and copy these | | **`README.md`** | Says where each piece goes, per client, so the folder explains itself once unzipped. | You read this | | **`references/account-profile.md`** | A written dossier of the account: what state it's in, what to prioritize, what cadence to work on. | Read by the agent on demand | | **`references/working-with-adspirer.md`** | The tool-calling contract and guardrails: discovery loop, read-before-write, pause-don't-delete. | Read by the agent on demand | > [!NOTE] > > **There is one instructions file, and it's `AGENTS.md`.** Earlier kits also shipped a separate > `AGENT_INSTRUCTIONS.md` with identical text; it was dropped as a duplicate. Coding agents read > `AGENTS.md` from a project root automatically, and for chat clients the kit page has a one-click > **Copy instructions** button that puts the same text on your clipboard. Kits you downloaded before > this change still work — keep using the file you have. > [!TIP] > > `PROMPTBOOK.md` is a **menu, not a script.** Your agent is told to open it to suggest a sensible > next step or to find the right approach for something you asked for — then run only that one. It > will not work through it start to finish, because every prompt in it spends real tool calls. ## How it's built When you buy, Adspirer runs a five-stage build against the live account. It usually finishes in a few minutes, and the page shows each stage as it completes: **1. Reading account structure** Pulls the campaigns, ad groups, budgets, and settings that exist right now. **2. Classifying the account's state** Works out what kind of account this is — scaling, stalled, newly built, seasonal. **3. Writing the account dossier** Writes `account-profile.md`: the state read, the priorities, the working cadence. **4. Writing your prompt book** Writes `PROMPTBOOK.md` against your actual campaigns and currency. **5. Assembling the skill package** Builds the folder, validates it against the Agent Skills spec, and packages the `.zip`. If a build fails, the kit page shows it and offers a retry. A failed build costs you nothing extra. ## Price | | Price | Billing | Covers | | - | - | - | - | | **Prompt Engineering Playbook** | **\$39** | **One time — nothing recurs** | **One ad account** | * Priced **per ad account**, because it is generated from that account's data. Two accounts means two playbooks. * **Select every eligible account and 20% comes off the whole cart.** Tick them all in Expert Space — the cart bar has a **Select all** shortcut — and the bundle discount applies automatically at checkout. It needs **at least two** accounts, and it has to be *all* of the ones you can still buy; a partial selection pays full price per kit. The cart always shows the live discount before you pay. * Buying several is a **single checkout and a single charge**, not one payment per account. * **Annual plans include one playbook free.** If you're on an annual plan, claim it from Expert Space — there's no checkout step and no charge. * The add-on also appears as an optional **"Add to your order"** on plan checkouts. Adding it there charges the \$39 immediately, on the same invoice as your plan — which is why the line item reads **"One-time Agent Setup — 1 Ad Account"**. > [!WARNING] > > \*\*Seeing $39 next to your plan charge does not mean your plan went up.** If you took the add-on > during checkout, the $39 sits on the same invoice as your subscription, as a separate one-time line. > Your recurring plan price is unchanged, and the \$39 will not appear on next month's invoice. Your > [billing page](https://adspirer.ai/) shows the recurring amount on its own. Because each playbook is generated on demand from your account, it's **non-refundable once the build has completed and the files are available to download**. If a build failed, or you were charged for an account you can't access, [contact support](/docs/knowledge-base/support) — that's a different situation and we'll sort it out. ## How to get it **1. Open Expert Space** Go to [adspirer.ai/expert-space](https://adspirer.ai/expert-space). You'll see one card per connected ad account, grouped by platform. **2. Pick the account** Cards show what the playbook will be built from — campaign count, months of history, currency. Accounts that aren't active show **Inactive**; activate them in [Connections](https://adspirer.ai/connections) first. **3. Preview, then buy** **Preview Expert** shows sample prompts before you pay. Buy one account, or tick several and check out together. **4. Wait for the build** A few minutes. You can close the tab — the kit keeps building. **5. Download the .zip** From the kit page: **Download**. You can also hit **Copy instructions** to put the agent instructions straight on your clipboard, read the prompt book in the browser, or download the prompt book on its own as a `.md` file — handy for pasting into a doc or dropping beside a project without unzipping the whole kit. > [!TIP] > > Lost the link? Everything you've bought is always at > [adspirer.ai/expert-space](https://adspirer.ai/expert-space) — owned accounts show an **Open Kit** > button. The purchase email also carries a direct link, but you never need it. ## Install it in your AI client There are three install shapes. Which one you use depends on the client, not on the playbook. | Shape | What you do | Clients | | - | - | - | | **Upload** | Upload the kit `.zip` into the client's Skills UI | Claude, Claude Cowork, ChatGPT *(Business/Enterprise/Edu only)* | | **Paste** | Paste the agent instructions into the project's instructions field, and attach the rest as project files | ChatGPT *(Free, Plus, Pro)*, Windsurf | | **Folder** | Copy the unzipped folder into the client's skills directory | Claude Code, Cursor, Codex, OpenClaw, Antigravity | The kit page's setup wizard shows the **literal install path** for whichever client you pick — `~/.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Cursor, OpenClaw, and Antigravity — so you don't have to go looking it up. > [!NOTE] > > The playbook assumes Adspirer is already connected in that client. It teaches the agent how to work > *your account*, not how to authenticate — connect first via [ChatGPT](/docs/ai-clients/chatgpt), > [Claude](/docs/ai-clients/claude), [Cowork](/docs/ai-clients/claude-cowork), > [Claude Code](/docs/ai-clients/claude-code), [Codex](/docs/ai-clients/codex), or [Codex Desktop](/docs/ai-clients/codex-desktop). ### Claude (web and desktop) **1. Turn on code execution** Skills need it. In Claude, go to **Settings → Capabilities** and turn on code execution. **2. Open Customize → Skills** Go to [Customize → Skills](https://claude.ai/customize/connectors) in Claude and open the **Skills** tab. **3. Upload the .zip as-is** Click **+ Create skill** and upload the kit `.zip` you downloaded — no unzipping first. The zip has the skill folder as its single root entry, which is exactly the shape Claude's uploader expects. Claude reads `SKILL.md` and the `references/` files together. **4. That's it — the skill is on your account** Skills are added at the **account** level, not per project, so your expert is available in every chat and every project, and activates on its own when you work on this account. Optionally, create a Project for this account and paste the agent instructions into its instructions field for extra focus — the kit page has a one-click **Copy instructions** button. Ask a normal question — *"how did we do last week?"* — and the skill loads on its own. You do not name it. See the [Claude setup guide](/docs/ai-clients/claude) for connector details. ### Claude Cowork Cowork supports skills the same way, from the **Customize** panel. **1. Open Customize** Click **Customize** in the left sidebar. You'll see **Skills**, **Connectors**, and **Plugins**. **2. Add the playbook under Skills** Add the unzipped folder as a skill. It sits alongside the 15 skills the Adspirer plugin installs — the free ones cover advertising in general, the playbook covers this account. **3. Use a brand folder** Open the brand folder for this account and drop `AGENTS.md` in it. Cowork picks it up as standing context for everything you do in that folder. See the [Cowork setup guide](/docs/ai-clients/claude-cowork) for the plugin install. ### ChatGPT Which path you take depends on your **ChatGPT plan**, because ChatGPT's Skills feature is not on every tier. > [!WARNING] > > **ChatGPT Skills are available on Business, Enterprise, Healthcare, and Edu — not on Free, Plus, or > Pro.** If you're on Plus or Pro (the tiers the [Adspirer ChatGPT plugin](/docs/ai-clients/chatgpt) requires), > use the **Project instructions** path below. It gives you the same behavior without the Skills > feature. On Enterprise and Edu, skills may also be switched off until a workspace admin enables them. **Plus and Pro — paste into Project instructions** **1. Create a Project for this ad account** One project per ad account keeps the agent from mixing them up. **2. Paste the agent instructions** Hit **Copy instructions** on the kit page — one click puts the whole thing on your clipboard — and paste it into the project's custom-instructions field. (The same text ships in the kit as `AGENTS.md` if you'd rather open the file.) **3. Upload the rest as project files** Add `PROMPTBOOK.md` and `references/account-profile.md` to the project's files so ChatGPT can read the dossier and the prompts on demand. **Business, Enterprise, Healthcare, Edu — upload it as a skill** **1. Open Skills** Go to **Skills** in ChatGPT and choose **Create → Upload from your computer**. **2. Upload the playbook folder** ChatGPT scans the upload before it becomes available — most are ready straight after the scan. The playbook follows the open Agent Skills standard, so it's the same folder you'd install anywhere else. **3. Still worth making a Project** Paste the agent instructions into a project for this account too. The skill carries the expertise; the project keeps every chat scoped to one ad account. See [Skills in ChatGPT](https://help.openai.com/en/articles/20001066-skills-in-chatgpt), [ChatGPT custom instructions](https://help.openai.com/en/articles/8096356-chatgpt-custom-instructions), and the [ChatGPT setup guide](/docs/ai-clients/chatgpt). ### Claude Code, Cursor, Codex, OpenClaw, Antigravity Folder-based clients read the files off disk. Unzip the playbook into the directory you work in: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} unzip google-ads-expert-acme-retail.zip # the folder contains SKILL.md, PROMPTBOOK.md, README.md, references/, # and the agent definition for your client ``` > [!TIP] > > **On Codex Desktop, skip the copying.** Attach the unzipped folder in a Codex chat and ask it to install the kit — Codex places the skill and agent definition itself. [Steps →](/docs/ai-clients/codex-desktop#install-your-expert-kit) Copy the whole folder into your client's skills directory, then put the agent definition in its agents directory: | Client | Skills directory | Agent definition | | - | - | - | | **Claude Code** | `.claude/skills/` | `.claude/agents/` (markdown) | | **Codex** | `.agents/skills/` | `.codex/agents/` (TOML) | | **Cursor** | `.agents/skills/` | `.cursor/agents/` (markdown) | | **Antigravity** | `.agents/skills/` | `.agents/agents/` (markdown) | | **OpenClaw** | `/.agents/skills/` | — | > [!WARNING] > > These paths are **project-scoped on purpose**. The `~/` home-directory equivalents load one > account's ads expert into every unrelated project you open — including work that has nothing to do > with advertising. * **`SKILL.md`** is what the skills directory picks up. See [Claude Code skills](https://code.claude.com/docs/en/skills), [Cursor skills](https://cursor.com/docs/context/skills), [Codex skills](https://learn.chatgpt.com/docs/build-skills), and [OpenClaw skills](https://docs.openclaw.ai/tools/skills). * **The agent definition** carries your account instructions as the agent's system prompt and points at the skill. It's a uniquely named new file, so it can't overwrite anything you already have — and uninstalling the kit is deleting it. * **On Claude Code, Codex and Antigravity the agent file declares `mcp.adspirer.com` itself**, so there's no connector step. **Cursor is the exception:** its subagents inherit tools from the parent and can't declare their own server, so add `https://mcp.adspirer.com/mcp` to `.cursor/mcp.json` yourself. > [!NOTE] > > Earlier versions of the kit told you to copy an `AGENTS.md` to your project root. **Don't** — that > is a single well-known filename, and doing so replaces whatever instructions were already there > with "work only on this ad account". The agent definition above does the same job without > touching your existing setup. If you followed the old instructions, check your project root. **Claude Code** watches these directories, so it picks the skill up **without a restart**. Claude loads it when a task matches, or you can invoke it directly as `/google-ads-expert-acme-retail`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p .claude/skills .claude/agents cp -r google-ads-expert-acme-retail .claude/skills/ ``` **Codex** discovers skills by their `SKILL.md` frontmatter and loads the full file only when a task matches, so you don't invoke it by name — though you can with `$` to force it. Run `/skills` to confirm it loaded. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p .agents/skills .codex/agents cp -r google-ads-expert-acme-retail .agents/skills/ ``` > [!TIP] > > The same skill folder works across all of these unchanged — one Agent Skills bundle, several > clients. Only the directory it goes in, and the format of the agent definition, differ. > [!NOTE] > > **Windsurf is no longer a supported client for the Expert Kit.** Cognition renamed it Devin > Desktop, it isn't on the Agent Skills client list, and nothing documents the desktop app loading a > local skill. Using Windsurf as an [MCP client](/docs/ai-clients/windsurf) is unaffected. Managing several accounts from one machine? Keep one folder per account and open the one you're working on — see [set up your project](/docs/guides/set-up-your-project) for the project-per-account and project-per-channel patterns. ## Set up the project, then run the prompts Installing the files is half of it. The playbook pays off when it lives inside a **project** — a persistent workspace scoped to that one ad account — so every chat starts already knowing the account. The pattern is the same in all three chat clients: **create a project → paste the agent instructions → add the dossier as knowledge → work through the prompt book.** **Claude** **1. Create the project** Go to [claude.ai/projects](https://claude.ai/projects) and click **+ New Project**. Name it for the ad account — *"Acme Retail — Google Ads"* — so you never wonder which account a chat is about. Projects are available on every plan, including free (free is capped at 5 projects). **2. Paste the agent instructions** On the right-hand side of the project, click **Set project instructions**. Paste the whole of the agent instructions — the kit page has a one-click **Copy instructions** button, and the same text is in the kit as `AGENTS.md` — then click **Save instructions**. This is the constitution: it pins the account ID, the currency, read-before-write, and create-paused. Every chat in the project inherits it. **3. Add the dossier as project knowledge** Still on the right, click **+** and upload `references/account-profile.md` and `PROMPTBOOK.md`. Claude uses them as context in every chat in the project. **4. Upload the skill (optional, but better)** Separately, upload the skill folder under [Customize → Skills](https://claude.ai/customize/connectors). Instructions are the rules, the skill is the expertise — keeping them in their own layers is what stops one from drowning out the other. **5. Run a prompt** Open a new chat **inside the project** and paste the first prompt from `PROMPTBOOK.md`. Work down the levels rather than cherry-picking — they're ordered so the agent builds context before it proposes changes. **Claude Cowork** Cowork projects are **desktop-only and stored locally**, which suits the playbook well — the folder you downloaded can *be* the project. **1. Create the project** Click **+** next to **Projects** in the left navigation. You get three options: start from scratch, import an existing Claude project, or **use an existing folder on your computer**. Pointing it at the unzipped playbook folder is the fastest route — the files are already laid out the way a project wants them. **2. Paste the agent instructions** Open the project's **Instructions** section — *"Add tone, formatting, or rules to help guide how Claude works on all tasks in the project"* — and paste the agent instructions (`AGENTS.md`, or the kit page's **Copy instructions** button) into it. **3. Add the account dossier to Context** Use the project's **Context** area to add the local playbook folder (or link the Claude chat project you already set up). That's where `account-profile.md` and `PROMPTBOOK.md` belong — data, not rules. **4. Add the skill** In **Customize → Skills**, add the playbook folder as a skill so it sits alongside the two skills the Adspirer plugin installs. **5. Run a prompt, then schedule one** Work through `PROMPTBOOK.md` in the project. Once a prompt is proving itself by hand, move it to the **Scheduled** panel — see [scheduled tasks](/docs/guides/scheduled-tasks) and [Cowork for Ad Ops](/docs/guides/claude-cowork-ad-ops) for the unattended safety model. **ChatGPT** **1. Create the project** Create a Project for this ad account. One project per account — the agent should never have two accounts in scope at once. **2. Paste the agent instructions** Paste the agent instructions into the project's custom-instructions field. On Business, Enterprise, Healthcare, or Edu you can *also* upload the skill under **Skills → Create → Upload from your computer**. On Free, Plus, and Pro the instructions field is the whole mechanism — see the plan note above. **3. Upload the dossier and prompt book as project files** Add `references/account-profile.md` and `PROMPTBOOK.md` to the project's files so ChatGPT can read them on demand. **4. Run a prompt** Start a chat in the project and paste the first prompt from `PROMPTBOOK.md`. > [!TIP] > > **The split that makes this work:** instructions are *rules*, the dossier is *data*. Paste > `AGENTS.md` into the instructions field and upload `account-profile.md` as knowledge — > never the other way round. [Set up your project](/docs/guides/set-up-your-project) explains why, and > covers memory, connectors, and scheduling around it. ## Keeping it current Ad accounts change. The playbook is a dated snapshot, and the agent is explicitly told that live data wins over anything written in the dossier. When the account has moved on, hit **Refresh** on the kit page. Adspirer rebuilds against current data and gives you a new version to download. > [!TIP] > > **Refreshes are free and unlimited.** Rebuilding is included in the original \$39 — there is no > charge for a new version, ever. ## FAQ > **Is this a subscription? Will I be charged \$39 every month?** > > No. It is a single one-time charge for one ad account, and nothing recurs. If you took it as an > add-on during plan checkout, it appears on the same invoice as your subscription as a separate > one-time line called **"One-time Agent Setup — 1 Ad Account"** — that is why the total looked > higher that month. Your recurring plan price is unchanged and the \$39 will not appear again. > **Does it cover all my ad accounts?** > > No — one playbook covers one ad account, because it is generated from that account's own > campaigns and history. If you run Google Ads and Meta for the same brand, those are two > accounts and two playbooks. Buying several is one checkout and one charge, and **selecting > every eligible account takes 20% off the whole cart** — minimum two accounts, and it must be > all of the ones you can still buy. > **Where do I download it?** > > [adspirer.ai/expert-space](https://adspirer.ai/expert-space) — accounts you own show **Open > Kit**, and the kit page has the **Download** button, a one-click copy for the agent > instructions, and the prompt book in a reader. The purchase email also links straight to it. > **Do I keep it if I cancel or downgrade my Adspirer plan?** > > The downloaded files are yours — they're on your machine. What changes is that the tools the > playbook drives run on your Adspirer plan, so the agent needs an active plan with quota to > actually do the work. > **Can I get a refund?** > > Each playbook is generated on demand from your account, so it is non-refundable once the build > has completed and the files are available to download. If the build failed, or you were charged > for an account you can't access, that's different — [contact support](/docs/knowledge-base/support). > **Does it set up the Adspirer connector for me?** > > No. Connecting Adspirer to your AI client is free and covered in the > [client setup guides](/docs/ai-clients/claude). The playbook starts after that: it teaches the agent > how to work *your* account well. > **I'm on an annual plan — do I still pay?** > > Annual plans include one playbook free. Claim it from > [Expert Space](https://adspirer.ai/expert-space); there's no checkout and no charge. Additional > accounts beyond the free one are \$39 each. > **What if my account data changes?** > > Hit **Refresh** on the kit page for a rebuild against current data. Refreshes are free and > unlimited. The agent is also instructed to always read live campaign data rather than trusting > the dossier's snapshot, so a slightly stale playbook still behaves correctly. > **Which AI clients does it work in?** > > All of them. The files follow the open Agent Skills and agents.md standards — Claude, Claude > Cowork, ChatGPT, Claude Code, Cursor, Codex, Windsurf, OpenClaw, and Antigravity. Only the > install shape differs: upload, paste, or drop the folder in. ## Related documentation > **[Agent Skills](/docs/agent-skills/skills)** > > The 13 free skills every plan gets. The playbook builds on top of these. > **[Set Up Your Project](/docs/guides/set-up-your-project)** > > Where the playbook's instructions and context belong in a project. > **[Pricing](/docs/knowledge-base/pricing)** > > Plans, tool calls, and where the one-time add-on sits. > **[Support](/docs/knowledge-base/support)** > > Billing questions, failed builds, and anything else. # Adspirer Skill Reference: 13 AI Ad Skills Source: https://www.adspirer.com/docs/agent-skills/skills Reference for all 13 Adspirer skills — the agent persona, the tool-call contract, six platform skills, four cross-platform workflows, and docs access. Adspirer ships **13 skills** — instruction files that teach an AI assistant how to run advertising campaigns properly. They follow the open [Agent Skills](https://agentskills.io) format, so the same files work in Claude, ChatGPT, Codex, Cursor, Gemini CLI, and OpenClaw. You don't invoke them by name. Describe what you want — "how are my Google Ads doing?", "launch a TikTok campaign" — and your assistant loads the right skill. > **[Get your free paid media skill](/docs/agent-skills/free-paid-media-skill)** > > Download one Markdown file with agent instructions and eight starter prompts for Claude, ChatGPT, or your coding agent. ## How the skills fit together Skills load on demand. Your assistant sees only each skill's name and description until a task matches, then reads the full instructions. Two skills underpin everything: * **`adspirer-agent`** sets the safety rules — campaigns are created paused, nothing spends without your explicit approval — and routes to the right skill. * **`adspirer-mcp`** carries the tool-call contract: how to reach each platform's tools, which account id each platform expects, and the budget units (Google's in dollars, Meta's in the ad account's own currency — not cents). Everything else builds on those two. A workflow skill like "launch a campaign" delegates to the platform skill for that platform's field rules, rather than duplicating them. ## Quick reference ### Foundational | Skill | What it does | | - | - | | **`adspirer-agent`** | Paid-media agent behavior. The safety contract and the routing table. | | **`adspirer-mcp`** | How to call the tools: the router two-step, account ids, budget units, quota. | ### Per platform | Skill | What it covers | | - | - | | **`adspirer-google-ads`** | Search, Performance Max, Demand Gen, YouTube, Display. Keywords, extensions, bidding. | | **`adspirer-meta-ads`** | Facebook and Instagram. Image, video, carousel, lead-gen. Audiences and creative fatigue. | | **`adspirer-tiktok-ads`** | In-feed video, Spark Ads, carousel, app promotion. The pixel and objective rules. | | **`adspirer-linkedin-ads`** | Sponsored content and lead-gen, with B2B job-title and company targeting. | | **`adspirer-amazon-ads`** | Sponsored Products, Brands, and Display. ASIN targeting and ACoS. | | **`adspirer-chatgpt-ads`** | Ads that appear inside ChatGPT responses. | ### Cross-platform workflows | Skill | What it does | | - | - | | **`adspirer-launch`** | Plan and launch a campaign. Picks the platform for the goal, splits budget, verifies the build. | | **`adspirer-performance-review`** | Cross-platform scorecard, plus a conversion-tracking audit. Read-only. | | **`adspirer-optimize`** | Find wasted spend, add negatives, exclude placements, reallocate budget, check pacing. | | **`adspirer-creative`** | Write headlines and ad copy. Diagnose and fix creative fatigue. | ### Product questions | Skill | What it does | | - | - | | **`adspirer-docs`** | Answers questions about Adspirer — plans, quota, connecting accounts — from these docs. | ### Workspace (local assistants only) | Skill | What it does | | - | - | | **`adspirer-setup`** | Bootstraps a brand workspace: scans your folder, pulls live campaign data, writes context files. | `adspirer-setup` needs a filesystem, so it ships to Claude Code, Cursor, Codex, and Gemini CLI — not to the ChatGPT plugin. *** ## What the skills guarantee Every skill inherits the same safety contract from `adspirer-agent`: > **Nothing spends without your approval** > > Campaigns are created **paused** on every platform. The agent never resumes a campaign, raises a > budget, or changes a bid strategy without you agreeing to that specific action first. * **Read before write.** The agent looks at what's actually in the account before proposing a change. * **Verify after write.** After creating or updating anything, it reads the object back and reports what exists — not what it asked for. * **Never invent a number.** If a tool fails, the agent says so. It does not estimate metrics. * **Destructive means destructive.** Deleting a creative or removing keywords is named as such, and confirmed, before it happens. *** ## Using your assistant's own features The skills know what the app they're running in can do, and offer it when it helps. ### Showing work In **Claude**, a scorecard, a set of ad-copy variants, or a campaign plan can be published as an **artifact** — a live page that updates as work continues, private to you by default. In **ChatGPT**, something you'll revisit or send to a client can be a hosted **Site**. The agent defaults to invitation-only, because these pages carry your spend and conversion data. ### Repeating work Ask for a weekly review or a pacing check and the agent offers to schedule it, using whatever your assistant calls it: | Assistant | What it's called | Runs when your computer is off? | | - | - | - | | ChatGPT | Scheduled tasks | Yes | | Codex | Scheduled tasks (automations) | Yes | | Claude Cowork | Scheduled tasks, via `/schedule` | Yes — they run remotely | | Claude Code | Routines — a *local* task or a *remote* routine | Local: no. Remote: yes | > [!WARNING] > > A Claude Code **local** scheduled task only runs while the desktop app is open and your computer is > awake. A laptop asleep at 9am skips the run. For budget pacing or spend alerts, the agent sets up a > **remote routine** instead. Every scheduled run calls Adspirer tools again, so it draws on your monthly tool-call quota exactly like a live conversation. The agent tells you what a cadence will cost before setting it up — weekly is the sensible default for a performance review. If your assistant has no scheduler, Adspirer's own monitoring tools cover the same ground server-side: threshold alerts on ROAS, CPA and spend, and scheduled reports delivered by email. *** ## Deeper reference material Some skills carry `references/` files that load only when the agent needs them — keeping the day-to-day context small: | Reference | Lives in | Why | | - | - | - | | Objective × pixel validity matrix | `adspirer-tiktok-ads` | TikTok rejects invalid combinations rather than correcting them. | | Creative specs and ODAX objectives | `adspirer-meta-ads` | Image ratios, carousel rules, character limits. | | Campaign types, bidding, PMax assets, extensions | `adspirer-google-ads` | Choosing the right campaign and bid strategy. | | Error catalog | `adspirer-mcp` | Known failures and their fixes, so the agent doesn't retry a call that cannot succeed. | | Docs map | `adspirer-docs` | Topic-to-URL index of this documentation. | *** ## Getting the skills > **[Claude Code & Cowork](/docs/ai-clients/claude-code)** > > Install the Adspirer plugin from the marketplace. > **[ChatGPT](/docs/ai-clients/chatgpt)** > > Skills ship with the Adspirer app. > **[Codex](/docs/ai-clients/codex)** > > Install the Adspirer plugin. > **[Cursor](/docs/ai-clients/cursor)** > > Install the Adspirer plugin from the Cursor Marketplace. > **[Grok Bot](/docs/ai-clients/grok)** > > Add the Adspirer plugin from the sidebar. Source lives in [github.com/amekala/ads-mcp](https://github.com/amekala/ads-mcp) under `shared/skills/`, and fans out to each client from there. ## Going further: a skill for your own account These 13 skills know advertising. They don't know *your* account — your campaigns, your spend, your currency, what state the account is in. The [**Prompt Engineering Playbook**](/docs/agent-skills/prompt-engineering-playbook) is the paid layer that does: a **one-time \$39 per ad account**, and Adspirer generates a custom skill, an account dossier, a prompt book, and paste-ready agent instructions from that account's real data. You download the files and install them alongside these free skills. | | These 13 skills | Prompt Engineering Playbook | | - | - | - | | **Scope** | Advertising in general | One specific ad account | | **Knows your campaigns** | No | Yes | | **Cost** | Free on every plan | \$39 once, per account (one free on annual) | You want both — the free skills are the grammar, the playbook is the briefing. Launch a Google Search campaign end to end. Create a Google Search campaign for my SaaS product: * Product: cloud inventory management for restaurants * Target: restaurant owners in Chicago * Budget: \$75/day Research keywords first, then create the campaign with sitelinks and callout extensions. See the [Tool Catalog](/docs/agent-skills/tools) for the tools these skills drive, and [Core Workflows](/docs/agent-skills/workflows) for the step-by-step patterns. # Adspirer Tool Catalog: 400+ MCP Tools by Platform Source: https://www.adspirer.com/docs/agent-skills/tools Complete reference of all 400+ Adspirer tools. Organized by platform (Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, TikTok Ads) with types, descriptions, and parameters. ## Tool Types * Read Safe to run anytime. Pulls data, analyzes performance, provides insights. No spending impact. * Write Requires user confirmation. Creates campaigns, updates budgets, modifies targeting. Affects spend. ## How the agent reaches these tools Adspirer exposes a small set of top-level tools. Most of the tools listed on this page sit **behind a platform router** — `google_ads`, `meta_ads`, `linkedin_ads`, `tiktok_ads`, `amazon_ads`, `chatgpt_ads`, `microsoft_ads` — and are reached in two steps: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} // 1. Discover. Always free — never counts against your quota. { "action": "list_tools" } // 2. Execute, using an exact tool name from step 1. { "action": "execute", "tool_name": "create_search_campaign", "arguments": { "...": "..." } } ``` > [!NOTE] > > Only these tools are callable directly by name: `start_here`, `search_tools`, `get_tool_schema`, > `get_connections_status`, `get_usage_status`, `switch_primary_account`, `get_campaign_performance`, > `get_meta_campaign_performance`, `audit_conversion_tracking`, `competitor_ads_research`, and > `echo_test`. > > Everything else in this catalog goes through its platform router. Calling a routed tool by name > returns "tool not found." `search_tools` finds the right tool from a plain-English description, and `get_tool_schema` returns its exact live signature. Both are top-level: call them directly by name. If your client's tool list was frozen when you installed it and doesn't include `get_tool_schema` — the ChatGPT plugin is the usual case — call it through any platform router instead: ``` google_ads(action: "execute", tool_name: "get_tool_schema", arguments: {"tool_names": [""]}) ``` Any router works, and the schema comes back identical to the direct call. Use this only when `get_tool_schema` is missing from your tool list; calling it directly by name is the normal path. `search_tools` is unaffected. The [`adspirer-mcp` skill](/docs/agent-skills/skills) teaches this contract to your assistant, along with the per-platform account ids and budget units. ## Google Ads Tools (156) **View all Google Ads tools** | Tool Name | Type | Description | | - | - | - | | `get_campaign_performance` | Read | Pull metrics for campaigns (spend, conversions, CPA, ROAS) | | `research_keywords` | Read | Find keywords with real CPC data from Google Keyword Planner | | `create_search_campaign` | Write | Launch Google Search campaign (created PAUSED) | | `create_pmax_campaign` | Write | Launch Performance Max campaign (created PAUSED) | | `analyze_wasted_spend` | Read | Find campaigns with wasted spend. Excludes learning-phase (\< 14 days) and insufficient-data (\< \$20 spend) campaigns from waste totals. | | `optimize_budget_allocation` | Read | Recommend budget shifts based on ROAS/CPA | | `analyze_search_terms` | Read | Review actual search queries triggering your ads | | `analyze_pmax_search_terms` | Read | Per-term search queries a Performance Max campaign matched — cost, clicks, impressions, conversions, conversion value, CTR, CPC. `analyze_search_terms` only covers Search and Shopping, so use this one for PMax. Sorted by cost, filterable, with a summary across the whole window | | `analyze_pmax_search_categories` | Read | The same PMax demand grouped into Google's search categories, with clicks, impressions, conversions, and conversion value per category | | `discover_existing_assets` | Read | Check if account has images/headlines/descriptions | | `suggest_ad_content` | Read | Generate ad headlines and descriptions (Google char limits) | | `validate_and_prepare_assets` | Read | Verify assets meet Google's requirements before campaign creation | | `pause_campaign` | Write | Stop campaigns or ad groups | | `resume_campaign` | Write | Restart paused campaigns | | `add_negative_keywords` | Write | Block irrelevant search terms | | `list_negative_keyword_lists` | Read | List the account's shared negative keyword lists, each with its keyword count and how many campaigns it's attached to | | `get_negative_keyword_list` | Read | Read the keywords and match types inside one shared list | | `create_negative_keyword_list` | Write | Create a new, empty shared negative keyword list | | `add_negative_keywords_to_list` | Write | Add negative keywords to a shared list — each `EXACT`, `PHRASE`, or `BROAD` (default `BROAD`) | | `attach_negative_keyword_list_to_campaign` | Write | Attach a shared negative keyword list to a campaign, so every term on the list blocks there | | `bulk_update_keyword_status` | Write | Pause or re-enable up to 300 keywords in one ad group in a single call. Reversible, and safe to re-run | | `bulk_update_ad_status` | Write | Pause or enable any number of ads in one ad group in a single call. Skips ads already in the target status, reports IDs not in that ad group, and reads the result back from Google so a change that didn't land can't report success | | `bulk_update_ad_group_status` | Write | Pause or enable any number of ad groups in a single call, on any campaign type. Optionally checks each ad group belongs to a named campaign. Reversible, never removes | | `bulk_update_campaign_status` | Write | Pause or enable any number of campaigns in a single call. Reversible, never removes — enabling can start real spend, so Adspirer confirms first | | `add_sitelinks` | Write | Add sitelink extensions (accepts `text`/`headline` + `url`/`link` field names) | | `remove_sitelinks` | Write | Remove sitelink extensions from a campaign | | `add_callout_extensions` | Write | Add callout extensions (short promotional blurbs) | | `remove_callouts` | Write | Remove callout extensions from a campaign | | `add_structured_snippets` | Write | Add structured snippet extensions (header + values) | | `remove_structured_snippets` | Write | Remove structured snippet extensions from a campaign | | `list_campaign_extensions` | Read | List everything attached at campaign level — sitelinks, callouts, structured snippets, call assets, business names, and images — each with its status | | `list_call_assets` | Read | List every phone number on a campaign with its country code, status, and the asset ID needed to pause or remove it | | `set_call_asset_status` | Write | Pause a phone number so it stops showing, or re-enable it, without unlinking it. Takes specific asset IDs, or changes every call asset on the campaign when none are named | | `remove_call_assets` | Write | Unlink phone numbers from a campaign. The asset stays in the Asset Library and can be re-linked elsewhere; omit the asset IDs to unlink all of them | | `update_bid_strategy` | Write | Change a campaign's bid strategy — Maximize Clicks, Maximize Conversions, Target CPA, Target ROAS, or Target Impression Share (page position + target share). Takes an optional `cpc_bid_ceiling` in the account's currency on Maximize Clicks and Target Impression Share — the two strategies with a max-CPC field — refuses it on the rest, leaves an existing ceiling alone when omitted, and reports the ceiling read back from Google rather than the value you sent. Detects shared portfolio strategies, surfaces Smart Bidding prerequisites, checks App campaigns against their App bidding goal, and reads the strategy back from Google after writing so a change that didn't apply can't report success | | `explain_performance_anomaly` | Read | Diagnose sudden CPA spikes or CTR drops | | `help_user_upload` | Read | Guide user through asset upload process | | `add_pmax_search_themes` | Write | Add search themes to a PMax campaign's asset group (max 50). Guides Google's automated targeting. | | `get_pmax_search_themes` | Read | View current search themes on a PMax campaign (max 50 per asset group) | | `remove_pmax_search_themes` | Write | Remove specific search themes from a PMax campaign | | `add_pmax_audience_signal` | Write | Add audience signal to PMax campaign. Combines in-market, affinity, custom audiences, and user lists. | | `get_pmax_audience_signals` | Read | View current audience signals on a PMax campaign | | `remove_pmax_audience_signal` | Write | Remove an audience signal from a PMax campaign | | `search_audiences` | Read | Search Google Ads audiences by keyword across in-market, affinity, and custom types | | `get_campaign_targeting` | Read | View location and language targeting on existing campaigns | | `pause_ad_group` | Write | Pause an individual ad group within a campaign | | `resume_ad_group` | Write | Resume a paused ad group | | `update_campaign` | Write | Update campaign settings: daily budget, language, locations, Search Partners, Display Expansion, audience targeting mode, AI Max. Google retires campaign-level language targeting for Search in late September 2026 (Performance Max keeps it) — after the cutover you get a plain explanation instead of a bare failure, and languages are never recorded as applied when they weren't | | `add_business_name_asset` | Write | Attach a business name asset to a Search campaign (max 25 characters). Idempotent — the same name already on the campaign isn't added twice, unless you pass `force=true` | | `add_call_asset` | Write | Attach a phone number call asset with optional call conversion tracking. Idempotent — the same number already on the campaign isn't added twice, unless you pass `force=true` | | `add_search_campaign_image` | Write | Attach image assets (logos, marketing images) to Search campaigns. Idempotent — the same image already linked under that field type isn't added twice, unless you pass `force=true` | | `list_conversion_actions` | Read | List all conversion actions in the account (purchases, form fills, calls) with status and tracking method | | `get_conversion_action_performance` | Read | Pull conversion volume, value, and CPA broken down by conversion action — see which actions drive results | | `update_conversion_action` | Write | Edit an existing conversion action by ID — name, category, status, value and currency, counting type, lookback windows, whether it counts in the Conversions column, primary-for-goal, attribution model. Only the fields you pass change; it never removes an action, and it fails rather than guessing if it can't read the current value settings first. "Counts in the Conversions column" is derived by Google and can't be set through the API — asking for it no longer blocks the rest of the update, it points you at the Google Ads UI or GA4 instead | | `get_ad_performance` | Read | Per-ad metrics (Search/Display/Demand Gen/YouTube) with head-to-head comparison and ad-strength | | `get_ad_creative` | Read | Export an ad's headlines, descriptions, images, YouTube videos, and carousel cards | | `link_merchant_center` | Write | Link a Google Merchant Center feed to enable Shopping | | `get_merchant_center_links` | Read | List linked Merchant Center accounts | | `create_shopping_campaign` | Write | Launch a Standard Shopping campaign from a Merchant Center feed (created PAUSED) | | `add_shopping_ad_group` | Write | Add an ad group to a Shopping campaign | | `add_shopping_product_ad` | Write | Add the product ad that surfaces feed items | | `add_product_group` | Write | Build the product partition tree (subdivide by brand/category/item and bid per partition) | | `create_app_campaign` | Write | Launch a Universal App campaign — installs, engagement, or pre-registration (created PAUSED) | | `create_demandgen_campaign` | Write | Launch a Demand Gen campaign across YouTube, Shorts, Discover, and Gmail (created PAUSED) | | `add_pmax_asset_group` | Write | Add an asset group to a Performance Max campaign | | `get_pmax_asset_performance` | Read | See which PMax assets Google rates Best / Good / Low | | `add_pmax_campaign_logo` | Write | Link a square logo (and optionally the business name) at the campaign level, as Brand Guidelines PMax campaigns require | | `get_pmax_conversion_goals` | Read | Read a campaign's conversion goals — category, origin, and whether each one is biddable | | `get_placement_performance` | Read | Where Display, Demand Gen, Video and Smart ads actually ran, with cost and conversions per placement | | `get_reach_frequency` | Read | Unique users reached and average impressions per user, per campaign | | `get_ad_policy_violations` | Read | Approval and review status of ads, with the policy topics behind a disapproval | | `add_placement_exclusions` | Write | Exclude websites, YouTube channels, videos or apps at campaign or ad group level | | `add_search_ad_group` / `create_ad` | Write | Add an ad group to an existing Search campaign; add a Responsive Search Ad to an existing ad group | | `get_ad_group_settings` / `update_ad_group_settings` | Read / Write | Read and change ad group name, status, bids, rotation, tracking and audience targeting mode | | `get_ad_group_demographics` / `update_ad_group_demographics` | Read / Write | Age, gender and income targeting on an ad group | | `get_ad_group_audiences` / `add_ad_group_audiences` | Read / Write | Read and add in-market, affinity, custom and customer-list audiences on an ad group | | `add_campaign_proximity` | Write | Radius targeting around an address | | `remove_campaign_proximity` | Write | Remove a radius target by Criterion ID (radius targets only) | | `update_location_targeting` | Write | Switch Presence vs Presence-or-Interest on an existing campaign | | `set_campaign_ad_schedule` | Write | Run ads only on chosen days and hours | | `set_campaign_device_bid_modifiers` / `set_ad_group_device_bid_modifiers` / `get_ad_group_device_bid_modifiers` | Write | Device bid adjustments at campaign and ad group level, and a read of the ad group values | | `update_pmax_audience_signal` | Write | Change a PMax audience signal's segments in place | | `get_campaign_dates` / `update_campaign_dates` | Read / Write | Read or set campaign start and end dates | | `get_campaign_frequency_caps` / `update_campaign_frequency_caps` | Read / Write | Read or replace a campaign's frequency caps | | `get_campaign_tracking` | Read | Tracking URL template, final URL suffix and custom parameters | | `list_labels`, `get_campaign_labels` | Read | Account labels and the labels on a campaign | | `create_label`, `add_campaign_label`, `remove_campaign_label` | Write | Create labels and attach or detach them on campaigns | | `create_conversion_action` | Write | Create a webpage conversion action for Smart Bidding | | `add_app_ad_asset` / `remove_app_ad_asset` | Write | Add or remove an image or video asset on an App campaign ad | | `remove_negative_keywords`, `remove_ad`, `remove_ad_group` | Write | Remove negative keywords, an ad, or an ad group | | `remove_campaign` | Write | Permanently delete a campaign. Cannot be re-enabled; use `pause_campaign` to stop one temporarily | | ...and more | | Shopping product partitions, App/UAC creative, Demand Gen audiences & channel controls, PMax asset-group management, ad-group device/schedule bid modifiers, campaign labels, frequency caps, geographic targeting, and additional Google Ads tools | ## LinkedIn Ads Tools (55) **View all LinkedIn Ads tools** | Tool Name | Type | Description | | - | - | - | | `get_linkedin_campaign_performance` | Read | Pull metrics for LinkedIn campaigns (spend, clicks, conversions, cost per lead) | | `get_linkedin_organizations` | Read | List user's LinkedIn company pages (required before campaign creation) | | `search_linkedin_targeting` | Read | Find B2B audiences by job title, industry, company size, seniority | | `research_business_for_linkedin_targeting` | Read | Input competitor name, get targeting suggestions | | `create_linkedin_image_campaign` | Write | Launch sponsored content campaign (created PAUSED). Supports campaign groups and creative naming. | | `add_linkedin_campaign_to_group` | Write | Add a campaign to an existing campaign group | | `add_linkedin_carousel_creative` | Write | Add carousel creative variations to campaigns | | `discover_linkedin_assets` | Read | Check existing creatives in LinkedIn (includes videos uploaded via Campaign Manager) | | `validate_and_prepare_linkedin_assets` | Read | Verify images meet LinkedIn requirements (1200x627px or 1200x1200px) | | `add_linkedin_creative` | Write | Add new sponsored posts to existing campaigns | | `analyze_linkedin_creative_performance` | Read | See which images/copy combinations perform best | | `optimize_linkedin_budget` | Read | Recommend budget reallocation based on cost per lead | | `update_linkedin_campaign` | Write | Change budgets, bids, or targeting | | `pause_linkedin_campaign` | Write | Stop campaigns or ad groups | | `explain_linkedin_anomaly` | Read | Diagnose sudden CTR, CPC, or conversion rate changes | | `manage_linkedin_conversions` | Write | Set up and track conversion events (form fills, downloads) | | `create_linkedin_video_campaign` | Write | Launch a video sponsored content campaign (created PAUSED) | | `create_linkedin_carousel_campaign` | Write | Launch a multi-card carousel campaign (created PAUSED) | | `create_linkedin_text_campaign` | Write | Launch a text ad campaign (created PAUSED) | | `create_linkedin_campaign_group` | Write | Create a campaign group with a shared budget/schedule | | `estimate_linkedin_audience_size` | Read | Estimate reachable audience size for a targeting spec before launch | | `forecast_linkedin_campaign_supply` | Read | Forecast impressions, clicks, and spend at a given budget | | `get_linkedin_audience_insights` | Read | See which job functions, industries, and seniorities engage | | `clone_linkedin_campaign` | Write | Duplicate a campaign with optional changes | | ...and more | | Video/text/carousel creatives, campaign-group batch operations, archive/reactivate/delete, engagement metrics, wasted-spend analysis, AI creative generation, and additional LinkedIn tools | ## Meta Ads Tools (60) **View all 60 Meta Ads tools** | Tool Name | Type | Description | | - | - | - | | `get_meta_campaign_performance` | Read | Pull metrics for Meta campaigns (Facebook + Instagram). Summary numbers state when they don't apply — ROAS reads "Not applicable" on traffic/awareness/engagement accounts, and your account's primary KPI is named | | `search_meta_targeting` | Read | Find audiences by interests, demographics, behaviors | | `select_meta_campaign_type` | Read | Choose: Image, Video, or Carousel based on creative assets | | `discover_meta_assets` | Read | Check existing creatives in Meta | | `list_meta_promotable_apps` | Read | List the mobile apps your ad account can promote, with the numeric Facebook App ID and store URLs an app-install campaign needs. Call before creating an app-promotion campaign | | `validate_and_prepare_meta_assets` | Read | Verify image/video URLs meet Meta requirements (dimensions, file size). Single images return an image hash for `existing_image_hash` | | `create_meta_image_campaign` | Write | Launch single-image campaign (created PAUSED) | | `create_meta_video_campaign` | Write | Launch video campaign (created PAUSED) | | `create_meta_carousel_campaign` | Write | Launch multi-card carousel campaign (created PAUSED) | | `analyze_meta_ad_performance` | Read | Deep analysis of ad-level performance with recommendations | | `analyze_meta_audiences` | Read | See which audience segments perform best (age, gender, interests). Reports the metric it ranked on, and excludes Meta's untargetable `Unknown` bucket from best/worst | | `detect_meta_creative_fatigue` | Read | Identify ads losing effectiveness over time (declining CTR after 14+ days) | | `optimize_meta_budget` | Read | Recommend budget reallocation based on ROAS/CPA | | `optimize_meta_placements` | Read | Shift spend to best-performing placements (Feed, Stories, Reels) | | `explain_meta_anomaly` | Read | Diagnose sudden CPA spikes or CTR drops | | `update_meta_campaign` | Write | Change budgets, bids, targeting, or the campaign's bid strategy (capped strategies need an ad-set bid cap first) | | `pause_meta_campaign` | Write | Stop campaigns or ad sets | | `browse_meta_targeting` | Read | Explore Meta's targeting categories | | `list_meta_custom_audiences` | Read | View custom audiences (database lists, lookalikes, website, engagement) | | `add_meta_ad_set` | Write | Add ad sets to existing campaigns (lifetime budgets, end dates, placements) | | `add_meta_ad` | Write | Add ads to existing ad sets | | `analyze_meta_wasted_spend` | Read | Identify campaigns with poor ROAS and recommend cuts | | `get_meta_audience_insights` | Read | Audience breakdown by age, gender, and interests | | `resume_meta_campaign` | Write | Restart paused campaigns | | `list_meta_campaigns` | Read | List all campaigns with status and budget, shown in the ad account's own currency | | `get_meta_campaign_details` | Read | Detailed campaign info — budgets, bids, and remaining spend in the account's own currency | | `list_meta_ad_sets` | Read | List ad sets in a campaign, with budgets in the account's own currency | | `list_meta_ads` | Read | List ads in an ad set | | `update_meta_ad_set` | Write | Update ad set budgets, targeting, or schedule | | `update_meta_ad` | Write | Update ad creative or status | | `get_meta_ad_creatives` | Read | View creative details for ads | | `create_meta_dco_ad` | Write | Create dynamic creative optimization ads | | `duplicate_meta_campaign` | Write | Duplicate an existing campaign | | `list_meta_lead_forms` | Read | View lead forms in your ad account | | `get_meta_lead_form_submissions` | Read | Pull lead submissions from a form | | `list_meta_pages` | Read | List every Facebook Page that can run ads on the ad account, with any linked Instagram account. Call this when a create or add tool reports the account has 2+ Pages and needs you to pick one | | `list_meta_instagram_accounts` | Read | View connected Instagram accounts | | `list_meta_pixels` | Read | View Meta Pixels in your ad account | | `get_meta_adset_performance` | Read | Pull spend, clicks, CTR, CPA, ROAS, and conversions broken down by ad set within a campaign — middle layer between campaign and ad performance | | `list_meta_catalogs` | Read | List product catalogs available to the ad account (Advantage+ Catalog / DPA) | | `list_meta_products` | Read | Browse products inside a catalog | | `list_meta_product_sets` | Read | View product sets (targetable subsets of a catalog) | | `create_meta_product_set` | Write | Create a product set with filter rules (e.g. "best sellers under \$50") | | `validate_catalog_readiness` | Read | Pre-flight check: is the catalog + pixel data ready for retargeting, limited retargeting, or prospecting only? | | `create_meta_catalog_campaign` | Write | Launch an Advantage+ Catalog (dynamic product ads) campaign (created PAUSED) | | `add_meta_catalog_ad_set` | Write | Add a catalog ad set (audience, budget, retargeting window) | | `add_meta_catalog_ad` | Write | Add a catalog ad (creative format + product set) | | `analyze_meta_catalog_performance` | Read | Product-level performance across the catalog | | `get_meta_product_performance` | Read | Per-product spend, sales, and ROAS | | `detect_meta_catalog_waste` | Read | Flag products burning budget with no return | | `diagnose_meta_catalog_funnel` | Read | Walk the catalog funnel (view → add-to-cart → purchase) to find leaks | | `compare_meta_catalog_product_sets` | Read | Compare performance across product sets | | `update_meta_catalog_campaign` | Write | Edit an existing catalog campaign — name, status, budget, spend cap, bid strategy, schedule, or swap the catalog | | `update_meta_catalog_ad_set` | Write | Edit a catalog ad set — budget, bidding, targeting, placements, schedule, or swap the product set, conversion event, or retargeting window | | `update_meta_catalog_ad` | Write | Edit a catalog ad — name, status, creative, copy, CTA, landing page, or product set | | `get_meta_pixel_stats` | Read | Check whether a pixel is firing and which events it records — confirm ViewContent / AddToCart / Purchase before building a retargeting catalog campaign | | `get_meta_app_summary` | Read | Account-level app-promotion performance: total installs and cost per install (CPI) | | `get_meta_app_campaigns` | Read | Installs and CPI per app campaign, each compared to your account average | | `get_meta_app_adsets` | Read | Installs and CPI per ad set — which audiences and placements deliver the cheapest installs | | `get_meta_app_creatives` | Read | Installs and CPI per creative, ranked cheapest first | ## TikTok Ads Tools (37) **View all TikTok Ads tools** | Tool Name | Type | Description | | - | - | - | | `get_tiktok_campaign_performance` | Read | Campaign summary with TikTok-specific video and engagement metrics | | `get_tiktok_ad_performance` | Read | Ad-level analysis with hook rate, video completion, and engagement | | `analyze_tiktok_wasted_spend` | Read | ROAS-based waste detection with campaign status awareness | | `optimize_tiktok_budget` | Read | Budget allocation recommendations based on performance | | `detect_tiktok_creative_fatigue` | Read | Hook rate decline as the primary fatigue signal | | `explain_tiktok_anomaly` | Read | Diagnose sudden changes in TikTok campaign performance | | `get_tiktok_audience_insights` | Read | Age/gender breakdown with CPA ranking | | `analyze_tiktok_geo_performance` | Read | Country-level performance analysis | | `list_tiktok_ad_videos` | Read | List videos already in your TikTok library with the `video_id` needed to reuse one | | `list_tiktok_pixels` | Read | List TikTok Pixels with the numeric `pixel_id` and the exact optimization events each supports | | `list_tiktok_lead_pages` | Read | List TikTok Instant Forms with the `page_id` needed to attach one to a lead generation ad, and whether each is published | | `discover_tiktok_assets` | Read | Browse existing images in the TikTok Asset Library | | `validate_and_prepare_tiktok_assets` | Read | Verify videos meet TikTok requirements (9:16 vertical, 5-60 seconds) | | `upload_tiktok_images` | Write | Upload images to TikTok Asset Library | | `create_tiktok_video_campaign` | Write | Launch an In-Feed video campaign from a video URL, an existing `video_id`, or an organic post (created PAUSED) | | `add_tiktok_ad_group` | Write | Add ad group with full targeting to existing campaign | | `add_tiktok_ad` | Write | Add ad to existing ad group (video or Spark Ad; images ride along as supporting assets) | | `search_tiktok_targeting` | Read | Search interests, keywords, regions, languages, action categories, carriers, device models | | `list_tiktok_campaigns` | Read | List all campaigns with status, objective, and budget | | `get_tiktok_campaign_details` | Read | Detailed campaign info | | `update_tiktok_campaign` | Write | Update campaign name, budget, budget mode | | `pause_tiktok_campaign` | Write | Pause a TikTok campaign | | `resume_tiktok_campaign` | Write | Resume a paused TikTok campaign | | `list_tiktok_ad_groups` | Read | List ad groups, filter by campaign | | `update_tiktok_ad_group` | Write | Update ad group name, budget, targeting, schedule | | `pause_tiktok_ad_group` | Write | Pause a TikTok ad group | | `resume_tiktok_ad_group` | Write | Resume a paused TikTok ad group | | `list_tiktok_ads` | Read | List ads, filter by ad group or campaign | | `pause_tiktok_ad` | Write | Pause a TikTok ad | | `resume_tiktok_ad` | Write | Resume a paused TikTok ad | | `explain_tiktok_objective` | Read | Given your goal (leads, sales, traffic, app installs), returns the correct TikTok campaign objective, recommended ad format, and compatibility constraints — eliminates trial-and-error objective selection | | ...and 7 more | | Campaign, ad-group and ad deletion, ad-group detail reads, saved and custom audience lists, and Business Center identities | ## Amazon Ads Tools (61) **View Amazon Ads tools** | Tool Name | Type | Description | | - | - | - | | `list_amazon_profiles` | Read | List advertiser profiles across NA, EU, and FE | | `list_amazon_brands` | Read | List Brand Registry entities on a profile with each `brandEntityId` (sellers need it for Sponsored Brands) | | `list_amazon_campaigns` | Read | List Sponsored Products / Brands / Display campaigns | | `create_amazon_sp_campaign` | Write | Create a Sponsored Products campaign (created PAUSED) | | `create_amazon_sb_campaign` | Write | Create a Sponsored Brands campaign (created PAUSED) | | `create_amazon_sd_campaign` | Write | Create a Sponsored Display campaign (created PAUSED) | | `update_amazon_campaigns` | Write | Update name, budget, or bidding across campaign types | | `pause_amazon_campaigns` / `resume_amazon_campaigns` | Write | Pause or resume campaigns | | `delete_amazon_campaigns` | Write | Archive campaigns | | `list_amazon_ad_groups` / `create_amazon_ad_groups` / `update_amazon_ad_groups` / `delete_amazon_ad_groups` | Write | Manage Sponsored Products ad groups | | `list_amazon_product_ads` / `add_amazon_product_ads` / `update_amazon_product_ads` / `delete_amazon_product_ads` | Write | Manage product ads (your ASINs/SKUs) | | `list_amazon_keywords` / `add_amazon_keywords` / `update_amazon_keywords` / `delete_amazon_keywords` | Write | Manage keywords for manual targeting | | `list_amazon_negative_keywords` / `add_amazon_negative_keywords` / `delete_amazon_negative_keywords` | Write | Block irrelevant search terms | | `list_amazon_targets` / `add_amazon_targets` / `update_amazon_targets` / `delete_amazon_targets` | Write | Manage product and category targeting | | `list_amazon_sb_ad_groups` | Read | List Sponsored Brands ad groups | | `create_amazon_sb_ad` / `list_amazon_sb_ads` / `update_amazon_sb_ads` | Write | Manage Sponsored Brands ads (all 7 ad types) | | `list_amazon_sb_creatives` / `update_amazon_sb_creative` | Write | Manage Sponsored Brands creative assets | | `list_amazon_sb_keywords` / `add_amazon_sb_keywords` / `update_amazon_sb_keywords` / `delete_amazon_sb_keywords` | Write | Manage Sponsored Brands keywords | | `add_amazon_sb_negative_keywords` | Write | Add negative keywords to Sponsored Brands | | `list_amazon_sb_targets` / `add_amazon_sb_targets` / `update_amazon_sb_targets` | Write | Manage Sponsored Brands targets | | `add_amazon_sb_themes` | Write | Add theme-based targets to Sponsored Brands | | `upload_amazon_asset` | Write | Upload a creative asset (e.g. a brand logo) | | `search_amazon_assets` | Read | Find existing assets in your Amazon library | | `get_amazon_moderation` | Read | Ad review status (APPROVED / IN\_PROGRESS / REJECTED / FAILED) per component, with the policy violation on a rejection | | `get_amazon_keyword_recommendations` / `get_amazon_bid_recommendations` | Read | Sponsored Products keyword & bid suggestions | | `get_amazon_sb_keyword_recommendations` / `get_amazon_sb_bid_recommendations` | Read | Sponsored Brands keyword & bid suggestions | | `get_amazon_budget_recommendations` / `get_amazon_budget_usage` | Read | Budget recommendations and consumption | | `get_amazon_campaign_performance` | Read | Impressions, clicks, spend, sales, ACOS, ROAS | | `get_amazon_search_terms` | Read | The search terms shoppers used to find your ads | | `get_amazon_report` | Read | Retrieve an async Amazon (Reporting v3) report by ID | | `analyze_amazon_wasted_spend` | Read | Find keywords/targets spending without converting | | `optimize_amazon_budget` | Read | Budget reallocation based on ACOS and ROAS | | `get_amazon_product_performance` | Read | Per-ASIN/SKU performance breakdown | | `analyze_amazon_placements` | Read | Compare performance across placements | | `analyze_amazon_targeting` | Read | Evaluate keyword and product targeting effectiveness | | `get_amazon_purchased_products` | Read | Cross-sell view of what shoppers actually bought | | `amazon_unified_api` | Write | Direct Amazon Advertising API access for advanced operations | ## ChatGPT Ads Tools (50) **View all 50 ChatGPT Ads tools** | Tool Name | Type | Description | | - | - | - | | `list_chatgpt_accounts` | Read | Connected ChatGPT Ads account(s) with `account_id`, currency, and review status. Connect one key per account; with two or more, name the account you mean and an ambiguous request returns the account list rather than a guess | | `list_chatgpt_campaigns` / `get_chatgpt_campaign` | Read | List campaigns or get one in detail. Every list tool takes a free-text search, status/type filter, sort, date range, and paging, and reports how many matched out of how many exist | | `create_chatgpt_campaign` | Write | Create a campaign (created PAUSED) with a budget in the account's currency, a `bidding_type` (`clicks` / `impressions` / `conversions`), and included or excluded locations | | `update_chatgpt_campaign` | Write | Change budget, bidding, schedule, landing-page query string, or targeting. Only the targeting side you name changes — the other four (locations in/out, audiences in/out, surfaces) are preserved — and any field OpenAI ignored is reported rather than claimed as applied | | `pause_chatgpt_campaign` / `resume_chatgpt_campaign` | Write | Stop serving, or resume to go live | | `archive_chatgpt_campaign` | Write | Archive a campaign. Permanent — OpenAI has no un-archive, so this asks you to confirm first | | `list_chatgpt_ad_groups` / `get_chatgpt_ad_group` | Read | List ad groups or get one | | `create_chatgpt_ad_group` | Write | Add an ad group with a bid strategy — `fixed_bid` (you set the bid), `maximize_clicks`, or `maximize_conversions` — plus targeting and per-audience bid multipliers from 0.1× to 10× | | `update_chatgpt_ad_group` | Write | Update bid, bid strategy, schedule, or targeting. Switching to a maximize strategy drops the manual bid; switching back to `fixed_bid` needs one | | `pause_chatgpt_ad_group` / `resume_chatgpt_ad_group` / `archive_chatgpt_ad_group` | Write | Control ad-group state. Archiving is permanent and asks you to confirm | | `list_chatgpt_ads` / `get_chatgpt_ad` | Read | List ads or get one | | `create_chatgpt_ad` | Write | Create a chat\_card ad (title, body, image, URL) | | `update_chatgpt_ad` | Write | Update an ad's creative | | `pause_chatgpt_ad` / `resume_chatgpt_ad` / `archive_chatgpt_ad` | Write | Control ad state. Archiving is permanent and asks you to confirm | | `launch_chatgpt_ad` | Write | One-shot: campaign → ad group → upload → ad (PAUSED) | | `upload_chatgpt_creative` | Write | Upload a chat\_card image from a public URL | | `chatgpt_geo_lookup` | Read | Resolve a location to a targeting value | | `get_chatgpt_performance` | Read | Impressions, clicks, spend, CTR, CPC | | `get_chatgpt_insights` | Read | Scoped insights (fields, filters, sort, pagination) | | `get_chatgpt_conversion_insights` | Read | Conversions, click-through conversions, and view-through conversions at account, campaign, ad-group, or ad level, optionally split by country or device. View-through is a 1-day window reported on its own line, never added into the total | | `list_chatgpt_custom_audiences` / `get_chatgpt_custom_audience` | Read | Your custom audiences with status (`processing` → `ready` / `too_small` / `failed`) and matched-user size range. OpenAI publishes a range, not an exact count | | `create_chatgpt_custom_audience` | Write | Create an audience, empty or seeded from an uploaded file. Processing is asynchronous — poll until it's `ready` | | `add_chatgpt_custom_audience_members` / `remove_chatgpt_custom_audience_members` | Write | Add or remove identifiers (email, phone, pre-hashed, or Google Advertising ID), inline or from a file. Returns an operation to poll | | `replace_chatgpt_custom_audience_members` | Write | Replace an audience's entire membership from a file | | `merge_chatgpt_custom_audiences` | Write | Merge 2–64 audiences into a new one | | `list_chatgpt_custom_audience_operations` / `get_chatgpt_custom_audience_operation` | Read | Track add / remove / replace / merge work in progress | | `resume_chatgpt_custom_audience_operation` / `cancel_chatgpt_custom_audience_operation` | Write | Restart or stop an add / remove operation | | `archive_chatgpt_custom_audience` | Write | Retire an audience so it can no longer be targeted. Permanent — asks you to confirm first | | `set_chatgpt_conversions_config` / `get_chatgpt_conversions_config` | Write | Configure or review Pixel / Conversions API | | `list_chatgpt_conversion_events` | Read | Conversion events being recorded | | `test_chatgpt_conversion` | Write | Send a test conversion to verify tracking | | `send_chatgpt_conversion_event` | Write | Send a real server-side conversion with advanced matching — value in whole minor units, an order id for de-duplication, and customer fields. Raw emails, phones, and names are SHA-256 hashed at the point of the call and never logged. `validate_only` gives a dry run | | `list_chatgpt_pixels` | Read | Your measurement pixels, each with its Source ID (`cds_…`) and short Pixel ID | | `create_chatgpt_pixel` | Write | Create a web measurement pixel and get the ready-to-paste site snippet back. Automatic Advanced Matching is on unless you opt out. Permanent — confirmed before it's created, and it won't replace an existing pixel unless you say so | | `create_chatgpt_conversions_api_key` | Write | Create a server-side Conversions API key. The secret is shown once and can't be retrieved again; stored encrypted by default so Adspirer can send events immediately. Permanent, and won't replace a stored key unless you say so | | `list_chatgpt_event_settings` | Read | Conversion event settings with event type, source, and attribution window | | `create_chatgpt_event_setting` | Write | Tie a conversion event (`order_created`, `lead_created`, a custom event) to a pixel or Conversions API source, with an attribution window. Permanent once created | ## Microsoft Advertising Tools (36) Read, create, and edit on Microsoft Advertising (Bing Ads). Budgets and bids are plain decimals in the account's own currency, never cents and never micros. Performance reporting is not live yet. Edits are partial — pass the fields you want changed and the rest is left alone. Two exceptions: setting a creative list (headlines, descriptions, images) replaces that whole list, and an ad-extension edit has to carry the complete object because Microsoft deletes any field you don't send. **View all 36 Microsoft Advertising tools** | Tool Name | Type | Description | | - | - | - | | `list_microsoft_accounts` | Read | Connected Microsoft Advertising account(s), each with the `account_id` to pass, its customer id, and its currency. Several accounts and several Microsoft logins can be connected; with two or more, name the account you mean and an ambiguous request returns the account list rather than a guess | | `list_microsoft_campaigns` | Read | Campaigns of every type on the account — Search, Shopping, Audience, Performance Max, Hotel, App — each with status, budget, and bidding scheme | | `create_microsoft_campaign` | Write | Create a campaign of any type Microsoft supports, with its budget, bidding scheme, languages, time zone, and dates | | `update_microsoft_campaign` | Write | Edit a live campaign — name, budget, bidding scheme, languages, time zone, URL tracking, dates, status. Campaign type can't change. Clear a URL field with `""`, detach a shared budget or portfolio bid strategy with `0`, remove an end date by passing one on or after 2050-01-01 | | `list_microsoft_ad_groups` | Read | Ad groups in a campaign — status, type, CPC bid, bidding scheme | | `create_microsoft_ad_groups` | Write | Add one or more ad groups to an existing campaign, each with its CPC/CPM/CPV bids | | `update_microsoft_ad_groups` | Write | Edit live ad groups — name, status, CPC/CPM/CPV/mCPA bids, bidding scheme | | `list_microsoft_ads` | Read | Ads in an ad group with every creative control — all headlines and descriptions, pinning, paths, URLs | | `create_microsoft_ads` | Write | Add ads to an existing ad group — every ad type Microsoft supports, including responsive search ads | | `update_microsoft_ads` | Write | Edit live ads — status, and the creative on responsive ads: headlines, descriptions, long headlines, images, videos with pinning, paths, URLs. Setting a list replaces that whole list; the ad's type can't change | | `list_microsoft_keywords` | Read | Keywords in an ad group — text, match type (Broad/Phrase/Exact), bid, status | | `create_microsoft_keywords` | Write | Add keywords to an existing ad group with match type and per-keyword bid | | `update_microsoft_keywords` | Write | Edit live keywords — match type, status, per-keyword bid | | `list_microsoft_budgets` | Read | The account's shared budget library — id, name, amount, budget type | | `update_microsoft_budgets` | Write | Edit shared budgets — amount, name, budget type. A shared budget change affects every campaign using it | | `list_microsoft_bid_strategies` | Read | Portfolio (shared) bid strategies — id, name, full bidding scheme | | `update_microsoft_bid_strategies` | Write | Edit portfolio bid strategies — name, bidding scheme, and its targets | | `list_microsoft_asset_groups` | Read | Performance Max asset groups in a campaign — name, status, and how many headlines and descriptions each carries | | `create_microsoft_asset_groups` | Write | Create Performance Max asset groups — the PMax creative structure, in place of ad groups and ads | | `update_microsoft_asset_groups` | Write | Edit live Performance Max asset groups — name, status, business name, call to action, headlines, descriptions, images, videos, final URLs, paths, search themes, dates. Setting an asset list replaces it, and the edit refuses to replace a live list when an image or video fails to resolve rather than emptying it | | `list_microsoft_ad_extensions` | Read | The account's shared extension library — sitelinks, callouts, and the rest — with ids and text, so you can reuse them | | `create_microsoft_ad_extensions` | Write | Add extensions to the library — sitelinks, callouts, structured snippets, images, and more | | `update_microsoft_ad_extensions` | Write | Edit extensions in the library — sitelink text and URLs, callout text, price rows, promotion details. Not partial: Microsoft deletes any field you don't send, so the edit carries the complete object | | `associate_microsoft_ad_extensions` | Write | Attach existing extensions by id to an account, campaign, or ad group so they serve with the ads there | | `create_microsoft_ad_group_criterions` | Write | Add deep targeting to an ad group — age, gender, day and time (dayparting), device, location, audience, webpage, profile | | `list_microsoft_ad_group_criterions` | Read | Read an ad group's targeting of one type back, with bids and mode | | `update_microsoft_ad_group_criterions` | Write | Edit an ad-group criterion's bid adjustment and status in place. The criterion's detail — the age range, device, geo — can't change; delete and re-add for that | | `delete_microsoft_ad_group_criterions` | Write | Remove ad-group targeting by id. Permanently deletes live targeting | | `create_microsoft_campaign_criterions` | Write | Add the same deep targeting at campaign level | | `list_microsoft_campaign_criterions` | Read | Read a campaign's targeting of one type back, with bids and mode | | `update_microsoft_campaign_criterions` | Write | Edit a campaign-level criterion's bid adjustment and status in place | | `delete_microsoft_campaign_criterions` | Write | Remove campaign-level targeting by id. Permanently deletes live targeting | | `list_microsoft_audiences` | Read | The account's audience library — ids, names, types, membership duration | | `create_microsoft_audiences` | Write | Create audience lists — remarketing, customer list, combined, product audience | | `discover_microsoft_media` | Read | Images already in the account's media library, used by image extensions and Performance Max | | `validate_and_prepare_microsoft_assets` | Write | Validate and upload images and videos to Microsoft and hand back the asset ids the create and edit tools need | ## Audit Tools (1) | Tool Name | Type | Description | | - | - | - | | `audit_conversion_tracking` | Read | Audit conversion tracking health across platforms. Checks Meta Pixel (event volume, CAPI, dedup), LinkedIn (conversion rules, CAPI, Insight Tag), and Google Ads (conversion actions, enhanced conversions, attribution). Returns health score (0-100), grade (A-F), and actionable recommendations. Pass optional `account_id` (or `customer_id`) to audit one account instead of every active account on the platform. Works on manager (MCC) child accounts and on accounts shared with teammates; when a critical check can't run, the report is headed **Incomplete** rather than given a grade. | ## Competitor Research (1) | Tool Name | Type | Description | | - | - | - | | `competitor_ads_research` | Read | Pull a competitor's live ads from public ad-transparency sources — creatives, headlines, offers, calls to action, formats, and how long each ad has been running — read with vision analysis and placed beside your own connected accounts, including any competitor brand terms you already pay for. `competitor_domains` is required and takes websites (`semrush.com`), not brand names; a bare brand returns nothing and the agent asks for the domain rather than guessing. `sources` chooses which ad libraries to pull: `google` (the default — Search, Display, and YouTube), plus `meta` for their Facebook and Instagram ads, `tiktok`, and `linkedin`. Optional `region` (ISO country code, defaults to your account's market), `max_creatives`, and `account_id` (or `customer_id`) to scope the your-ads half to one account. **No connected ad account is required** — the ad-library research runs regardless, and the your-ads comparison is simply left out when you have nothing connected to compare. Never returns competitor spend, ROAS, conversions, CPC, or impressions — no source publishes them, so nothing is estimated. Video ads are covered too — the poster frame is read with the same vision analysis, and the ad itself opens on the platform it runs on. Renders as an interactive card in ChatGPT and Claude, with the same findings as text everywhere else. | **Which sources to ask for.** Google is pulled by default; name the others and they're added — "what is `figma.com` running on LinkedIn and Meta". Each extra source is another set of lookups, so ask for the platforms your competitor actually advertises on rather than all four by reflex. **`region` doesn't apply everywhere.** Google and Meta ad libraries are filtered by market. TikTok's and LinkedIn's are worldwide and can't be narrowed, so results from those two are labelled worldwide instead of being passed off as your market. **Matching is strict on purpose.** A domain is resolved to one advertiser, confirmed against the links in their own ads where the platform exposes them. When the match can't be confirmed you get an honest empty result rather than a similarly-named stranger's ads. TikTok and LinkedIn have no website to verify against, so a match there is by advertiser name and the result says so. The your-ads half of the comparison reads Google, Meta, TikTok, and Amazon. LinkedIn ad copy isn't stored, so LinkedIn is left out of the copy comparison rather than guessed at. The **Your ads** tab appears only when your connected accounts have creatives to put beside theirs — and its absence never blocks the research. If you run Meta only, or haven't connected anything yet, you still get the competitor findings. Not to be confused with `start_research` below, which launches an async AI research job. `competitor_ads_research` returns real ads that are running right now. ## Automation Tools (16) **View all 16 Automation tools** ### Watch Agent (Proactive Signal) | Tool Name | Type | Description | | - | - | - | | `run_watch_now` | Read | Trigger an on-demand Watch Agent scan immediately. The agent reviews all connected ad accounts, writes a finding, and emails a re-entry prompt. Normally runs automatically every 15 minutes. | | `get_signal_briefing` | Read | Pull the advisory briefing and pre-staged fix actions for a specific Watch Agent finding. Use after receiving a finding email or after `run_watch_now`. | | `apply_signal_actions` | Write | Apply the pre-staged actions from a Watch Agent finding. Executes approved campaign adjustments (pause, bid change, add negatives) in one call. | | `list_pending_actions` | Read | List all actions staged by the Watch Agent that are waiting for your approval (pending\_approval, executed, rejected, expired). | | `manage_action` | Write | Approve or reject a specific pending action staged by the Watch Agent. | ### Monitors & Alerts | Tool Name | Type | Description | | - | - | - | | `create_monitor` | Write | Set a metric alert. Supports CPA, ROAS, CTR, CPC, spend, conversions, impressions, clicks, cost per lead, conversion rate, budget utilization. Same alerts visible in the [Monitors web UI](https://adspirer.ai/monitors). | | `list_monitors` | Read | View all active performance monitors (excludes deleted/tombstoned alerts). | | `delete_monitor` | Write | Remove a monitoring alert permanently. | | `get_monitor_history` | Read | View all past trigger events for a specific alert — timestamps, metric values, and what triggered it. | | `test_monitor` | Read | Dry-run a monitor against today's data. See whether the alert would fire right now without waiting for the next scheduled check. | ### Scheduled Briefs & Reports | Tool Name | Type | Description | | - | - | - | | `schedule_brief` | Write | Schedule recurring performance summaries via email — daily, weekly, or every N days, at the time and timezone you choose. Briefs now attach a PDF. | | `generate_report_now` | Read | Generate an ad-hoc cross-platform performance report immediately. | | `list_scheduled_tasks` | Read | View all scheduled briefs, monitors, and reports with status. | | `manage_scheduled_task` | Write | Unified pause, resume, or delete for any scheduled task (brief, monitor, or report). Pass `task_id` from `list_scheduled_tasks` and `action`: `'pause'`, `'resume'`, or `'delete'`. | | `start_research` | Write | Launch an async AI-powered research job (competitor analysis, keyword research, market landscape, audience insights, campaign strategy). | | `get_research_status` | Read | Check the status and results of an in-progress or completed research job. | ## Marketing Stack Integrations (Plus and above) Router tools that proxy to third-party marketing tools through [Pipedream Connect](https://pipedream.com/connect). The agent calls `action="list_tools"` first to discover what's available, then `action="execute"` with the specific tool name. | Tool Name | Type | Description | | - | - | - | | `google_analytics` | Read | Pull GA4 property data — sessions, conversions, traffic sources, landing-page performance, real-time. See the [Google Analytics integration page](/docs/integrations/google-analytics). | | `klaviyo` | Read | Pull Klaviyo campaigns (email + SMS), flows, segments, profiles, and metrics. See the [Klaviyo integration page](/docs/integrations/klaviyo). | | `google_search_console` | Write | Read organic-search performance for your verified sites — clicks, impressions, CTR, and average position, broken down by query, page, country, device, or date — and submit a URL to Google for re-crawling. | | `google_tag_manager` | Write | Read the tags and variables in your GTM containers — which conversion pixels, analytics, and remarketing tags are on your site and how they're configured — and create or update a tag or variable. | `google_tag_manager` is the tool behind "is my Meta pixel installed?" and "why isn't this conversion firing?". The read actions (`google_tag_manager-get-tags`, `google_tag_manager-get-tag`) answer both. Its three write actions — create a tag, update a tag, update a variable — change a live container that fires tracking on your real website, where a wrong edit can break conversion tracking site-wide, so the agent confirms the exact change with you before writing. `google_search_console` exposes two actions. `google_search_console-retrieve-site-performance-data` is read-only: pass the site URL, a start and end date, the dimensions you want (`query`, `page`, `country`, `device`, `date`), and a row limit. `google_search_console-submit-url-for-indexing` is a write — it tells Google a URL was updated or deleted — so the agent confirms the exact URL with you before submitting. Every integration requires the user to connect the account in the [Connections panel](https://adspirer.ai/connections). Free-tier users see the integration cards with an Upgrade prompt. These four tools are listed in your AI client whether or not you've connected them, the same as every ad platform. Call one you haven't connected and it answers with a prompt to authorize it in Connections — it doesn't disappear from the tool list, so you can find out an integration exists by asking for it. **More than one account per integration.** You can connect several accounts to the same integration — two GA4 logins, a client's Tag Manager container next to your own, a second Search Console user — up to your plan's account limit. Connect the extra one from **Connect another account** on that integration's card. When an integration has more than one account, pass `account_id` to say which; leave it off with a single account and nothing changes. Ask the agent and it lists the accounts it can see. **And more than one property inside an account.** One Google login usually reaches several GA4 properties, several verified Search Console sites, or a Tag Manager account with containers under it. Call an action that operates on one of those without naming it — no `property`, no `siteUrl`, no `accountId`/`containerId`/`workspaceId` — and the agent pulls the labelled list off your connection and asks which to use instead of picking one. Reads auto-resolve when there is exactly one; writes (`submit-url-for-indexing`, `submit-sitemap`, `delete-sitemap`, `create-tag`, `update-tag`, `update-variable`) confirm their target every time, even at one. Tag Manager asks one level at a time — account, then container, then workspace. The question is a precondition, not a result, so it doesn't cost a tool call. ## System Tools (5) | Tool Name | Type | Description | | - | - | - | | `get_connections_status` | Read | Show all connected ad platforms and account IDs | | `list_connected_accounts` | Read | List ad accounts across platforms — including connected-but-not-yet-activated accounts and live Google MCC child accounts. Used by sequential sub-agents to fan out work. Optional `platform` filter. Zero API calls (reads from database). | | `switch_primary_account` | Write | Change which ad account is active — by name, from chat, including switching between Google MCC child accounts. Respects your plan's active-account cap (replaces on single-account tiers, adds on multi-account tiers). Doesn't cost a tool call. | | `get_usage_status` | Read | Check Adspirer plan limits (tool calls used/remaining this month) | | `get_business_profile` | Read | View user's Adspirer account details and subscription info | ## Diagnostic & Helper Tools (9) Read-only "get unstuck" tools — get-started guidance, draft validation, error diagnosis, and value summaries. **All quota-free** (they never count against your tool-call limit) and available on **every plan, including Free**. Your assistant discovers them automatically; in ChatGPT and Claude their results render as interactive cards. See the [Diagnostic & Helper Tools reference](/docs/agent-skills/diagnostic-helper-tools). **View all 9 Diagnostic & Helper tools** | Tool Name | Type | Description | | - | - | - | | `start_here` | Read | The single best next step for your exact state, with a worked example prompt | | `suggest_next_action` | Read | Ranks the highest-value things to do right now from your live data | | `list_what_i_can_do` | Read | Personalized capability menu by goal, filtered to your connected platforms | | `get_campaign_spec` | Read | Required fields, character limits, and allowed values for a campaign type | | `validate_campaign_draft` | Read | Dry-run validates a campaign draft against the platform spec (no write) | | `explain_platform_error` | Read | Translates a raw platform error into a plain-language cause and fix | | `why_did_this_fail` | Read | Summarizes your recent failed actions and the errors behind them | | `verify_campaign_is_live` | Read | Real live check that a campaign exists and is serving (all 6 platforms) | | `usage_value_summary` | Read | Tool calls used vs. included this period and what they accomplished | `diagnose_my_setup`, `preflight_campaign`, `whats_changed_since_last_visit`, and `weekly_opportunities` were withdrawn on August 24, 2026 — see [Recently withdrawn](/docs/agent-skills/diagnostic-helper-tools#recently-withdrawn). ## Raw data mode All performance and analytics tools accept an optional `raw_data` parameter. When set to `true`, the tool returns a compact JSON code block with only raw metrics — no severity labels, suggested bids/budgets, industry benchmarks, or optimization recommendations. Default is `false` (full markdown output with recommendations). Use `raw_data=true` when you run your own attribution model, want to minimize token usage, or need to pipe metrics into an external tool. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} {"raw_data": true, "date_range": "last_30_days"} ``` ## Tool call best practices > [!NOTE] > > * **Always start with `get_connections_status`:** Verify the correct ad account is active before using platform-specific tools > * **Chain Read tools before Write tools:** Research, validate, then create. Never jump straight to campaign creation. > * **Ask for user confirmation before Write tools:** Present the plan, get approval, then execute. > * **Never retry Write tools on error:** If a campaign creation fails, report the error and wait for user input. Don't auto-retry. > * **Format results as tables:** Performance data should be scannable (columns: metric, value, change vs. previous period) > * **Use `raw_data=true` for compact output:** When you need just the numbers without recommendations, pass `raw_data=true` to any performance tool. ## Input Format Requirements Follow these rules when calling Adspirer tools to avoid validation errors: ### IDs Must Be Strings All IDs (`campaign_id`, `ad_account_id`, `video_id`, `image_hash`, `ad_group_id`, `keyword_id`, `organization_id`, `creative_id`) must be passed as quoted strings, never as bare integers. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} // ✅ Correct {"existing_video_id": "1333064875515942"} // ❌ Wrong {"existing_video_id": 1333064875515942} ``` ### Never Modify IDs Copy IDs exactly as returned by list/discover tools. Do not round, truncate, or change any digits. ### Always Call List/Discover Before Create/Update Many tools require IDs from prior tool calls: * `list_campaigns` → get `campaign_id` before update/pause/structure * `get_campaign_structure` → get `ad_group_id` before keyword operations * `discover_existing_assets` → get `image_hash`, `video_id` before campaign creation * `get_linkedin_organizations` → get `organization_id` and `account_id` ### Text Length Limits The server will reject text that exceeds platform limits: | Field | Platform | Max Characters | | - | - | - | | Headline | Google Ads | 30 | | Description | Google Ads | 90 | | Sitelink text | Google Ads | 25 | | Callout | Google Ads | 25 | | primary\_text | Meta Ads | 125 | | Headline | Meta Ads | 40 | ### Meta Ad Copy Formatting Meta `primary_text` supports emojis, line breaks (`\n`), and bullet points for higher engagement: ``` 🔥 Limited Time Offer! ✅ Free Shipping ✅ 30-Day Returns ✅ Best Price Guarantee 👉 Shop now before it's gone! ``` Use emojis strategically (🔥 ✅ 🎯 💰 ⚡ 🚀 👉 ⭐ 💡 📈) and structure copy with line breaks and bullet points (•, ✅, ▸) for readability. ### Enum Values Are Case-Insensitive The server auto-normalizes casing. Common enum values: * **status:** `ENABLED`, `PAUSED`, `ACTIVE`, `ARCHIVED` * **objective:** `OUTCOME_TRAFFIC`, `OUTCOME_SALES`, `OUTCOME_LEADS` * **match\_type:** `EXACT`, `PHRASE`, `BROAD` * **date\_range:** `last_7_days`, `last_30_days`, `last_90_days` * **campaign\_type:** `search`, `pmax`, `image`, `video`, `carousel` ### Budgets Are Numbers Pass budget fields as numbers, not strings. Budget is in the account's local currency (not cents). ### Keywords Format For `add_negative_keywords`, each keyword must be an object with `text` and `match_type` fields: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} // ✅ Correct {"keywords": [{"text": "free", "match_type": "BROAD"}]} // ❌ Wrong {"keywords": ["free", "cheap"]} ``` ## Related Documentation * [Core Workflows](/docs/agent-skills/workflows) -- See how these tools fit into step-by-step processes * [Skills Overview](/docs/agent-skills/overview) * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) * [TikTok Ads Integration](/docs/ad-platforms/tiktok-ads) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Core Workflows for AI Ad Campaign Management Source: https://www.adspirer.com/docs/agent-skills/workflows Complete workflows for ad campaign management — step-by-step tool sequences for Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads creation and optimization. Exact tool sequences for campaign creation, optimization, and analysis. These are the workflows that agent skills enforce automatically. ## 1. Performance Analysis (Cross-Platform) Pull metrics from all connected ad platforms and present a unified view. ### Tool Sequence ``` 1. get_connections_status → confirm which platforms are connected 2. get_campaign_performance (Google Ads) 3. get_meta_campaign_performance (Meta Ads) 4. get_amazon_campaign_performance (Amazon Ads) 5. get_chatgpt_performance (ChatGPT Ads) 6. get_linkedin_campaign_performance (LinkedIn Ads) 7. get_tiktok_campaign_performance (TikTok Ads) → run in parallel if multi-platform 8. Present side-by-side comparison table ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[get_connections_status] --> B{Multi-platform} B -->|Yes| C[Google] B -->|Yes| D[Meta] B -->|Yes| E[Amazon] B -->|Yes| F[ChatGPT] B -->|Yes| G[LinkedIn] B -->|Yes| H[TikTok] B -->|Single| I[One platform] C --> J[Comparison table] D --> J E --> J F --> J G --> J H --> J I --> J ``` ### Output Format Results should be formatted as a table with columns: Platform, Spend, Conversions, CPA, ROAS, CTR. ### Deep Analysis Tools (Optional) * `analyze_wasted_spend` (Google), `analyze_meta_wasted_spend` (Meta), `analyze_amazon_wasted_spend` (Amazon), `analyze_linkedin_wasted_spend` (LinkedIn) -- Find campaigns wasting spend. Campaigns in learning phase (\< 14 days) or with insufficient data (\< \$20 spend) are excluded from waste totals automatically. * `detect_meta_creative_fatigue` (Meta) -- Identify declining ad performance * `explain_performance_anomaly` (any platform) -- Diagnose sudden CPA spikes or CTR drops ## 2. Google Search Campaign Creation Five-step workflow. Skip a step = campaign creation fails. ### Tool Sequence ``` 1. get_connections_status → verify Google Ads is connected 2. research_keywords → input: business_description, seed_keywords, target_location → output: keyword suggestions with real CPC data 3. discover_existing_assets → check if user has images/headlines in Google Ads already 4. suggest_ad_content (if new assets needed) → generate headlines, descriptions within character limits 5. validate_and_prepare_assets → verify assets meet Google's requirements 6. create_search_campaign → campaign created PAUSED 7. ASK USER FOR CONFIRMATION before proceeding ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[research_keywords] B --> C[discover_existing_assets] C --> D{New assets needed} D -->|Yes| E[suggest_ad_content] D -->|No| F[validate_and_prepare_assets] E --> F F --> G[create_search_campaign PAUSED] G --> H{{USER CONFIRMATION}} ``` ### Key Parameters * **research\_keywords:** business\_description, seed\_keywords, target\_location (e.g., "United States") * **create\_search\_campaign:** campaign\_name, daily\_budget (min \$10), asset\_bundle, targeting ### Safety Rules > [!WARNING] > > * Never skip keyword research (even if user provides keywords -- validate CPC data) > * Always validate assets before campaign creation > * Campaign is created PAUSED -- user reviews before launching ## 3. Google PMax Campaign Creation Performance Max campaigns require high-quality assets plus optional search themes and audience signals for targeting. ### Tool Sequence ``` 1. get_connections_status 2. discover_existing_assets → check for high-quality images, videos, logos 3. help_user_upload (if assets missing) → guide user to upload to Merchant Center or provide URLs 4. validate_and_prepare_assets → PMax requires: 5+ images, 1+ video, 5+ headlines, 5+ descriptions 5. create_pmax_campaign → campaign created PAUSED 6. add_pmax_search_themes → add up to 50 search themes to guide targeting (recommended) 7. search_audiences → find relevant in-market, affinity, and custom audiences 8. add_pmax_audience_signal → combine audience segments into a targeting signal (recommended) 9. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[discover_existing_assets] B --> C{Assets complete} C -->|Missing| D[help_user_upload] C -->|Complete| E[validate_and_prepare_assets] D --> E E --> F[create_pmax_campaign PAUSED] F --> G[add_pmax_search_themes] G --> H[search_audiences] H --> I[add_pmax_audience_signal] I --> J{{USER CONFIRMATION}} ``` ### Asset Requirements * Minimum 5 images (1200x628px landscape + 1200x1200px square) * Minimum 1 video (under 30 seconds recommended) * 5 headlines (max 30 chars each) * 5 descriptions (max 90 chars each) * 1 logo (1200x1200px) ### Search Themes (PMax Only) Search themes are short phrases (max 50 per asset group) that tell Google which search queries your PMax campaign should target. They supplement Google's automated targeting with explicit intent signals. * Derive themes from keyword research, search term reports, and brand context * Max **50 themes** per asset group * Only support **add** and **remove** (no update — remove + re-add instead) * Tools: `add_pmax_search_themes`, `get_pmax_search_themes`, `remove_pmax_search_themes` ### Audience Signals (PMax Only) Audience signals tell Google which audience segments are most likely to convert. They are **signals, not hard targeting** — Google uses them as starting points and expands from there. * Only **one audience signal** per asset group (combine multiple segments in one signal) * Supported types: in-market audiences, affinity audiences, custom audiences, user lists (remarketing) * Use `search_audiences` to find audience IDs by keyword * Tools: `add_pmax_audience_signal`, `get_pmax_audience_signals`, `remove_pmax_audience_signal` ## 4. Google Display Campaign Creation Six-step workflow for standard Display (full manual targeting) and Smart Display (Google-managed). See the [Display Ads guide](/docs/ad-platforms/google-display-ads) for complete details. ### Tool Sequence ``` 1. get_connections_status → verify Google Ads is connected 2. resolve_google_locations → names → exact geoTargetConstants/ → rejects ambiguity ("Baja" surfaces 5 candidates) 3. list_google_languages → validate ISO language codes 4. search_audiences (standard Display, if using audience targeting) → find real in-market / affinity / custom audience IDs 5. Prepare creative: 1-5 short headlines ≤30 chars, 1 long headline ≤90, 1-5 descriptions ≤90, ≥1 landscape + ≥1 square image 6. create_display_campaign → campaign + ad group + RDA created PAUSED 7. add_sitelinks + add_callout_extensions + add_structured_snippets 8. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[resolve_google_locations] B --> C[list_google_languages] C --> D{Standard or Smart?} D -->|Standard| E[search_audiences + topics/placements/keywords] D -->|Smart Display| F[Conversion tracking check] E --> G[Prepare creative] F --> G G --> H[create_display_campaign PAUSED] H --> I[Add extensions] I --> J{{USER CONFIRMATION}} ``` ### Targeting Surfaces (Standard Display) Five independent surfaces that intersect — mix and match: * **Audiences** — in-market, affinity, custom, user lists (use `search_audiences`) * **Topics** — Google content categories * **Managed placements** — specific websites, apps, YouTube channels/videos * **Display keywords** — contextual (always BROAD match) * **Demographics** — age, gender, parental status, income exclusions Each surface has GET / ADD / REMOVE tools, plus a unified `remove_display_criteria` for cleanup. ### Smart Display Rules * Requires `bidding_strategy=TARGET_CPA` + `target_cpa` set * Requires 50+ Display conversions in the last 30 days * **Rejects** manual targeting fields — fully Google-managed * Set `smart_display=true` on `create_display_campaign` ### Safety Rules > [!WARNING] > > * ALWAYS resolve locations + languages before creation — no silent US fallback > * Never fabricate audience IDs — run `search_audiences` first > * Smart Display + manual targeting is rejected; use one or the other > * Campaign created PAUSED — user reviews before launching ## 5. Google Shopping Campaign Creation Standard Shopping campaigns advertise your Merchant Center product feed. See the [Google Ads integration](/docs/ad-platforms/google-ads) for details. ### Tool Sequence ``` 1. get_connections_status → verify Google Ads is connected 2. get_merchant_center_links → confirm a Merchant Center feed is linked → link_merchant_center (if none is linked yet) 3. create_shopping_campaign → campaign created PAUSED 4. add_shopping_ad_group → add an ad group to the campaign 5. add_shopping_product_ad → surface your feed's products 6. add_product_group → build the product partition tree (subdivide by brand, category, product type, or item ID) 7. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[get_merchant_center_links] B --> C{Feed linked?} C -->|No| D[link_merchant_center] C -->|Yes| E[create_shopping_campaign PAUSED] D --> E E --> F[add_shopping_ad_group] F --> G[add_shopping_product_ad] G --> H[add_product_group partition tree] H --> I{{USER CONFIRMATION}} ``` ### Safety Rules > [!WARNING] > > * A linked Merchant Center feed is required — no feed, no Shopping campaign > * Build the product partition tree with `add_product_group` to bid per subdivision > * Campaign created PAUSED — user reviews before launching ## 6. Meta Campaign Creation Six-step workflow for Facebook & Instagram campaigns. ### Tool Sequence ``` 1. get_connections_status → verify Meta Ads is connected 2. search_meta_targeting → find audiences by interests, demographics, behaviors → output: targeting options with audience size estimates 3. select_meta_campaign_type → image, video, or carousel based on user's creative 4. discover_meta_assets → check existing creatives in Meta 5. validate_and_prepare_meta_assets → verify image/video URLs meet Meta requirements 6. create_meta_image_campaign | create_meta_video_campaign | create_meta_carousel_campaign → campaign created PAUSED 7. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[search_meta_targeting] B --> C[select_meta_campaign_type] C --> D[discover_meta_assets] D --> E[validate_and_prepare_meta_assets] E --> F{Campaign type} F -->|Image| G[create_meta_image_campaign] F -->|Video| H[create_meta_video_campaign] F -->|Carousel| I[create_meta_carousel_campaign] G --> J{{USER CONFIRMATION}} H --> J I --> J ``` ### Creative Requirements by Type * **Image:** 1080x1080px, JPG/PNG, under 30MB * **Video:** 1080x1080px, MP4/MOV, under 4GB, 1-240 seconds * **Carousel:** 2-10 cards, each 1080x1080px ### Ad Copy Tips * Use emojis, line breaks (`\n`), and bullet points (•, ✅, ▸) in `primary_text` for higher engagement * `primary_text` max 125 characters, headline max 40 characters * For location targeting, use `search_meta_targeting` with `search_type='location'` to find cities, regions, or zip codes — pass the returned objects directly to campaign creation ### Safety Rules > [!WARNING] > > * Creative assets must be provided as URLs (Google Drive, Dropbox, S3) > * Validate creative URLs are publicly accessible before campaign creation > * Minimum \$5/day budget per ad set ## 7. Meta Advantage+ Catalog (Dynamic Product Ads) Advantage+ Catalog campaigns show the exact SKUs from your product feed to the right shopper automatically. See the [Meta Ads integration](/docs/ad-platforms/meta-ads) for details. ### Tool Sequence ``` 1. get_connections_status → verify Meta Ads is connected 2. list_meta_catalogs → pick the product catalog to advertise from 3. validate_catalog_readiness → confirm the catalog + recent pixel data support retargeting (view / add-to-cart / purchase events) or prospecting 4. create_meta_product_set (optional) → narrow to a subset (e.g. "best sellers under $50") 5. create_meta_catalog_campaign → prospecting or retargeting, campaign created PAUSED 6. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[list_meta_catalogs] B --> C[validate_catalog_readiness] C --> D{Narrow to a product set?} D -->|Yes| E[create_meta_product_set] D -->|No| F[create_meta_catalog_campaign PAUSED] E --> F F --> G{{USER CONFIRMATION}} ``` ### Safety Rules > [!WARNING] > > * Run `validate_catalog_readiness` before creating — retargeting needs recent pixel events > * Campaign created PAUSED — user reviews before launching ## 8. Amazon Sponsored Products Campaign Creation Sponsored Products campaigns advertise your ASINs in Amazon search results and on product pages. Amazon also supports Sponsored Brands and Sponsored Display. See the [Amazon Ads integration](/docs/ad-platforms/amazon-ads) for details. ### Tool Sequence ``` 1. get_connections_status → verify Amazon Ads is connected 2. list_amazon_profiles → pick the advertiser profile / region (NA, EU, FE) to advertise under 3. get_amazon_keyword_recommendations + get_amazon_bid_recommendations → find keywords for your ASINs and suggested bids 4. create_amazon_sp_campaign → campaign created PAUSED (use create_amazon_sb_campaign / create_amazon_sd_campaign for Sponsored Brands / Display) 5. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[list_amazon_profiles] B --> C[get_amazon_keyword_recommendations + get_amazon_bid_recommendations] C --> D[create_amazon_sp_campaign PAUSED] D --> E{{USER CONFIRMATION}} ``` ### Key Metrics Amazon campaigns are optimized toward **ACOS** (ad spend ÷ attributed sales, lower is better) and **ROAS** (attributed sales ÷ ad spend, higher is better) — tied to real retail revenue. ### Safety Rules > [!WARNING] > > * Select an advertiser profile first (multi-region: NA, EU, FE) — no profile, no campaign > * Campaign created PAUSED — user reviews before launching ## 9. ChatGPT Ads Campaign Creation Pay-per-click "chat-card" ads that appear inside ChatGPT responses. `launch_chatgpt_ad` is a one-shot orchestrator that builds the whole paused ad in one step. See the [ChatGPT Ads integration](/docs/ad-platforms/chatgpt-ads) for details. ### Tool Sequence ``` 1. get_connections_status → verify ChatGPT Ads is connected 2. launch_chatgpt_ad → one-shot: URL + headline + body + image + budget + geo → creates the campaign, ad group, image upload, and chat_card ad, all PAUSED (prefer step-by-step? create_chatgpt_campaign → create_chatgpt_ad_group → upload_chatgpt_creative → create_chatgpt_ad) 3. ASK USER FOR CONFIRMATION — review budget + creative, then resume_chatgpt_campaign ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[launch_chatgpt_ad] B --> C[Campaign + ad group + image + chat_card ad PAUSED] C --> D{{USER CONFIRMATION}} D --> E[resume_chatgpt_campaign] ``` ### Safety Rules > [!WARNING] > > * Minimum budget \$1/day — the agent speaks in dollars, not micros > * Every object is created PAUSED — nothing serves until you resume it > * The agent reports OpenAI review status honestly — no false "live" claims while review is pending ## 10. LinkedIn Campaign Creation Five-step workflow for B2B sponsored content. ### Tool Sequence ``` 1. get_linkedin_organizations → list user's company pages, select one to advertise under 2. search_linkedin_targeting | research_business_for_linkedin_targeting → find B2B audiences by job title, industry, company size, seniority → output: targeting options with audience size 3. discover_linkedin_assets → check existing creatives 4. validate_and_prepare_linkedin_assets → verify images meet LinkedIn requirements 5. create_linkedin_image_campaign → campaign created PAUSED 6. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_linkedin_organizations] --> B[search_linkedin_targeting] B --> C[discover_linkedin_assets] C --> D[validate_and_prepare_linkedin_assets] D --> E[create_linkedin_image_campaign PAUSED] E --> F{{USER CONFIRMATION}} ``` ### Targeting Best Practices > [!TIP] > > * Combine job titles + industries (e.g., "Marketing Manager" + "Computer Software") > * Add seniority filter for decision-makers (Director, VP, C-level) > * Use company size to match your ICP (Ideal Customer Profile) > * Minimum audience size: 300 members (LinkedIn requirement) ### Safety Rules > [!WARNING] > > * Must select organization first (no org = campaign creation fails) > * Minimum \$10/day budget > * Image dimensions: 1200x627px or 1200x1200px ## 11. TikTok Campaign Creation Three-step workflow (simpler than other platforms). ### Tool Sequence ``` 1. get_connections_status → verify TikTok Ads is connected 2. list_tiktok_ad_videos → reuse a video already in your library (or upload a new one) 3. validate_and_prepare_tiktok_assets → verify video meets TikTok requirements: 9:16 vertical, 5-60 seconds 4. create_tiktok_video_campaign → campaign created PAUSED 5. ASK USER FOR CONFIRMATION ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_connections_status] --> B[list_tiktok_ad_videos] B --> C[validate_and_prepare_tiktok_assets] C --> D[create_tiktok_video_campaign PAUSED] D --> E{{USER CONFIRMATION}} ``` For a conversions campaign, insert `list_tiktok_pixels` before creation to get the numeric `pixel_id` and a valid `optimization_event` for that pixel. There is no default event. ### Creative Requirements * Vertical video: 9:16 aspect ratio (1080x1920px) * Duration: 5-60 seconds (9-15 seconds performs best) * Format: MP4 or MOV * File size: Under 500MB ## 12. Budget Optimization Workflow Reallocate spend based on performance data. ### Tool Sequence ``` 1. get_campaign_performance → pull last 30 days 2. optimize_budget_allocation (Google) OR optimize_meta_budget (Meta) OR optimize_amazon_budget (Amazon) OR optimize_linkedin_budget (LinkedIn) → analyzes ROAS or CPA, suggests reallocation 3. Present recommendations in table: - Current budget allocation - Recommended budget allocation - Expected impact (conversions gained) 4. ASK USER FOR APPROVAL before executing changes ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[get_campaign_performance] --> B{Platform} B -->|Google| C[optimize_budget_allocation] B -->|Meta| D[optimize_meta_budget] B -->|Amazon| E[optimize_amazon_budget] B -->|LinkedIn| F[optimize_linkedin_budget] C --> G[Present recommendations] D --> G E --> G F --> G G --> H{{USER APPROVAL}} ``` ### Optimization Logic * Shift budget from low-ROAS campaigns to high-ROAS campaigns * Increase spend on campaigns with CPA below target * Decrease or pause campaigns with CPA 2x+ above target * Maintain minimum budgets per platform ($10 Google/LinkedIn, $5 Meta, $1 Amazon/ChatGPT, $20 TikTok) ## 13. Account Management Workflow Managing multiple ad accounts and checking system status. ### Tool Sequence ``` 1. get_connections_status → shows all connected platforms and account IDs 2. switch_primary_account (if managing multiple accounts) → change active account for subsequent tool calls 3. get_usage_status → check Adspirer plan limits: tool calls used/remaining 4. get_business_profile → view user's Adspirer account details ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[get_connections_status] --> B[switch_primary_account] B --> C[get_usage_status] C --> D[get_business_profile] ``` ### When to Use * At the start of every session (verify correct account is active) * Before creating campaigns (confirm you're in the right ad account) * When switching between client accounts (agencies managing multiple advertisers) ## 14. Automation & Proactive Monitoring Schedule recurring tasks, set alerts, and use the Watch Agent for proactive campaign monitoring. ### Watch Agent (Proactive Signal) The Watch Agent runs automatically in the background every 15 minutes, scanning your connected ad accounts for issues. When it finds something actionable, it emails you a copy-paste prompt to act on it immediately. **Tool Sequence — on-demand scan:** ``` 1. run_watch_now → kicks off a Watch Agent session right now (async) 2. [email arrives with signal_id and re-entry prompt] 3. get_signal_briefing(signal_id) → advisory + pre-staged fix actions 4. apply_signal_actions(signal_id) → execute the fixes (with confirmation) ``` ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[run_watch_now] --> B[Watch Agent scans accounts] B --> C{Issues found?} C -->|Yes| D[Finding + email with signal_id] C -->|No| E[No action] D --> F[get_signal_briefing] F --> G[Review recommendations] G --> H{{USER APPROVAL}} H --> I[apply_signal_actions] ``` **Managing staged actions:** ``` 1. list_pending_actions → see all Watch Agent staged fixes waiting for approval 2. manage_action(action_id, decision="approve") → approve one action OR apply_signal_actions(signal_id) → approve all staged actions for a finding ``` ### Monitors & Alerts **Tool Sequence — create a metric alert:** ``` 1. create_monitor(metric, operator, threshold) → set the alert OR use the Monitors web UI at adspirer.ai/monitors 2. list_monitors → verify it's active 3. [alert fires when threshold is crossed, email sent] 4. get_monitor_history(alert_id) → see all past trigger events test_monitor(alert_id) → dry-run against today's data ``` ### Scheduled Briefs ``` 1. schedule_brief(delivery_destination, schedule_type, time, platforms) → schedule_type: "daily", "weekly", or "every_n_days" → set up the recurring email report (now includes PDF attachment) 2. list_scheduled_tasks → see all active briefs and monitors 3. manage_scheduled_task(task_id, action="pause") → pause, resume, or delete ``` ### Example: Daily Performance Brief ```python Daily Performance Brief theme={"theme":{"light":"github-light","dark":"github-dark"}} schedule_brief( name="Morning Standup Brief", delivery_destination="team@company.com", schedule_type="daily", time="08:00", timezone="America/New_York", platforms=["google_ads", "meta_ads", "amazon_ads", "chatgpt_ads", "linkedin_ads"] ) ``` ### Example: CPA Spike Monitor ```python CPA Spike Alert theme={"theme":{"light":"github-light","dark":"github-dark"}} create_monitor( metric="cpa", operator="greater_than", threshold=50, # alert if CPA exceeds $50 consecutive_days=2, # only alert if it stays above for 2 days (reduces noise) platforms=["google_ads"] ) ``` ### Example: On-Demand Watch Agent Scan ``` "Run the watch agent on my accounts now" → run_watch_now() → [email arrives] "Show me the briefing for signal abc123" → get_signal_briefing(signal_id="abc123") → "Apply the staged fixes" → apply_signal_actions(signal_id="abc123") ``` ## Workflow Principles These rules apply to ALL workflows: > [!NOTE] > > 1. **Always start with connections check:** Run `get_connections_status` before platform-specific tools > 2. **Read before write:** Research/validate before creating campaigns > 3. **User confirmation required:** Ask before any action that affects spend > 4. **Campaigns created PAUSED:** User reviews before launching live > 5. **Never retry on error:** Report failures, don't auto-retry campaign creation > 6. **Format results as tables:** Make data scannable (columns: metric name, value, change vs. previous period) ## Input Format Rules > [!NOTE] > > * **IDs must be strings:** Pass all IDs (`campaign_id`, `video_id`, `ad_account_id`, etc.) as quoted strings, never bare integers > * **Never modify IDs:** Copy IDs exactly as returned by list/discover tools — do not round or change digits > * **Respect text limits:** Google headline max 30 chars, description max 90, Meta primary\_text max 125. Meta primary\_text supports emojis and line breaks > * **Enum casing:** The server auto-normalizes, but prefer uppercase for status/objective/match\_type and lowercase for date\_range/campaign\_type > * **Budgets are numbers:** Pass as numbers in account's local currency (not cents, not strings) > * **Keywords as objects:** `add_negative_keywords` expects `[{"text": "free", "match_type": "BROAD"}]`, not `["free"]` See [Tool Catalog — Input Format Requirements](/docs/agent-skills/tools#input-format-requirements) for full details. ## Related Documentation * [Tool Catalog](/docs/agent-skills/tools) -- All 400+ tools with parameters * [Skills Overview](/docs/agent-skills/overview) * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Meta Ads Integration](/docs/ad-platforms/meta-ads) * [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) * [ChatGPT Ads Integration](/docs/ad-platforms/chatgpt-ads) * [LinkedIn Ads Integration](/docs/ad-platforms/linkedin-ads) * [TikTok Ads Integration](/docs/ad-platforms/tiktok-ads) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Connect ChatGPT to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/chatgpt Connect Adspirer to ChatGPT as a custom MCP server: Plugins → Add → Add custom MCP server, paste https://mcp.adspirer.com/mcp, and sign in. Works on every ChatGPT plan, including Free. Manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads with 400+ tools. > [!NOTE] > > **Connect Adspirer to ChatGPT as a custom MCP server.** The Adspirer plugin in ChatGPT's **Plugins** directory is having issues right now, and it's missing our newest tools. Adding Adspirer directly takes about two minutes, works on every ChatGPT plan including Free, and gives you every tool the day it ships. Manage ad campaigns from ChatGPT. There are two ways to connect. Both use the same Adspirer account, the same sign-in, and the same server. | | **Custom MCP server** (recommended) | **Adspirer plugin** | | - | - | - | | Setup | **Plugins → Add → Add custom MCP server**, paste the server URL, sign in. About two minutes. | Open **Plugins**, search "Adspirer," click **Install plugin**. | | Status | Working | Having issues right now | | Platforms | Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, TikTok Ads, **plus Google Analytics and Google Search Console** | Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads | | New tools | Available the day they ship | Arrive when OpenAI approves each plugin update | | Warnings | ChatGPT shows **Custom MCP servers introduce risk** (expected, explained below) | None | [Run Google Ads Directly from ChatGPT with Adspirer](https://www.youtube.com/embed/QSAlo6LHqXI) Run Google Ads Directly from ChatGPT ## Setup **Custom MCP server (recommended)** ChatGPT talks to `mcp.adspirer.com` directly, so you get every tool without waiting on a plugin review: Amazon Ads, ChatGPT Ads, Google Analytics, Google Search Console, and whatever ships next. ChatGPT saves it as a plugin of your own. **1. Open Plugins → Add → Add custom MCP server** In ChatGPT, click **Plugins** in the left sidebar. Click **Add** in the top right and choose **Add custom MCP server**. ![ChatGPT Plugins page with the Add menu open, showing Create plugin, Upload plugin archive, and Add custom MCP server](https://mintcdn.com/adspirer/xPeUNeB1sfjBaY7j/images/chatgpt/add-menu.png?fit=max\&auto=format\&n=xPeUNeB1sfjBaY7j\&q=85\&s=c8589690552f81889d74efe42c222735) Plugins → Add → Add custom MCP server > [!NOTE] > > Don't see **Add custom MCP server**? On Business and Enterprise, your workspace admin controls custom MCP servers. Ask them to allow it. **2. Fill in the form** | Field | Value | | - | - | | **Icon** | Optional. PNG only, 10 KB max. It only changes how the plugin looks in your sidebar. | | **Name** | `Adspirer-Custom`. Any name works, and it's what you'll @mention in chats. | | **Description** | Optional, e.g. `Google, Meta, Amazon, LinkedIn, TikTok, ChatGPT Ads` | | **Connection** | Keep **Server URL** selected (not **Tunnel**) and paste `https://mcp.adspirer.com/mcp` | | **Authentication** | **OAuth** | Leave **Advanced OAuth settings** alone. ChatGPT discovers the right values from the server. ![ChatGPT Add custom MCP server form with Name Adspirer-Custom, Connection set to Server URL https://mcp.adspirer.com/mcp, Authentication OAuth, the 'Custom MCP servers introduce risk' warning, the ticked 'I understand and want to continue' checkbox, and the Create as a plugin button](https://mintcdn.com/adspirer/xPeUNeB1sfjBaY7j/images/chatgpt/add-custom-mcp-server.png?fit=max\&auto=format\&n=xPeUNeB1sfjBaY7j\&q=85\&s=c5ab3d2883acdec077418814bece3543) The Add custom MCP server form, filled in **3. Tick the box and click Create as a plugin** Tick **I understand and want to continue**, then click **Create as a plugin**. > [!WARNING] > > ChatGPT shows **Custom MCP servers introduce risk** for every server it hasn't reviewed. That's expected for this path. It's the same Adspirer server that powers the plugin in ChatGPT's directory. You sign in on adspirer.ai with OAuth, and ChatGPT never sees your ad-platform passwords. **4. Connect the plugin** ChatGPT opens your new plugin's page. It lists you as the developer because it's your own private plugin. Click **Try in chat**, then click **Connect Adspirer-Custom** (or whatever you named it) in the dialog that opens. ![ChatGPT Connect Adspirer-Custom dialog explaining what ChatGPT shares with the app, with Connect Adspirer-Custom and Cancel buttons](https://mintcdn.com/adspirer/xPeUNeB1sfjBaY7j/images/chatgpt/custom-connect-dialog.png?fit=max\&auto=format\&n=xPeUNeB1sfjBaY7j\&q=85\&s=f408e1b3ea2750b2367db470a8910ac9) ChatGPT asks you to connect the plugin you created **5. Authorize ChatGPT on Adspirer** Your browser opens Adspirer. Sign in, or create a free account. New accounts connect their first ad platform on the way. You land on **Authorize ChatGPT**, which lists what ChatGPT will be able to do: view your campaigns, create and manage campaigns, view performance metrics, and view your connected ad accounts. Click **Authorize**, then return to ChatGPT. ![Adspirer Authorize ChatGPT screen showing the signed-in account, the four permissions ChatGPT is requesting, the requested scopes, and the Authorize button](https://mintcdn.com/adspirer/xPeUNeB1sfjBaY7j/images/chatgpt/authorize-chatgpt.png?fit=max\&auto=format\&n=xPeUNeB1sfjBaY7j\&q=85\&s=237db69e6b399a4317633e5d47d88688) Adspirer's Authorize ChatGPT screen **6. Start managing ads** Start a new conversation. Mention the plugin by the name you gave it, or just ask about your campaigns. ``` @Adspirer-Custom check my connected ad platforms ``` You should see a table of your connected accounts across all platforms with account IDs, names, and connection status. To add more ad accounts later, go to [adspirer.ai/connections](https://adspirer.ai/connections). > [!TIP] > > You're connected directly to Adspirer's server. Every tool on this page is available, including Amazon Ads, ChatGPT Ads, Google Analytics, and Google Search Console, and new ones appear as soon as they ship. **Adspirer plugin** > [!WARNING] > > **The Adspirer plugin is having issues right now.** It's also missing Amazon Ads, ChatGPT Ads, Google Analytics, and Google Search Console. Use the **Custom MCP server** tab instead. These steps stay here for when the plugin is back. **1. Open Plugins and search for Adspirer** In ChatGPT, click **Plugins** in the left sidebar. Type **Adspirer** in **Search plugins** and select it. Or open the [Adspirer plugin](https://chatgpt.com/plugins/plugin_asdk_app_69461dc91ee48191ae4a14eb9bde1c21) directly. **2. Click Install plugin** On the Adspirer page (*Create, launch & analyze ads*), click **Install plugin**. ![Adspirer plugin page in ChatGPT, subtitled Create, launch & analyze ads, with the Install plugin button](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/chatgpt/plugin-listing.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=5a2ec926c27fa523660b2e87bb3c356e) The Adspirer plugin in ChatGPT's Plugins directory **3. Sign in with Adspirer** Click **Sign in with Adspirer**. Your browser opens Adspirer's login page. Sign in (or create an account) and link the ad platforms you want to manage. ![Add Adspirer to ChatGPT dialog with the Sign in with Adspirer button and a Reference memories and chats toggle](https://mintcdn.com/adspirer/QbDcLM8vS1nI3Ofq/images/chatgpt/connect-dialog.png?fit=max\&auto=format\&n=QbDcLM8vS1nI3Ofq\&q=85\&s=f368d3d1f0d39be389259b45ed93ad7a) **4. Start managing ads** Start a new conversation and mention **@adspirer**: ``` @adspirer check my connected ad platforms ``` > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=chatgpt)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in under two minutes. ## Connection Details Paste these into ChatGPT's **Add custom MCP server** form: ``` Connection: Server URL Server URL: https://mcp.adspirer.com/mcp Authentication: OAuth ChatGPT plan: Any, including Free ``` ## What You Can Do 400+ tools across 6 ad platforms, plus the [Google Analytics](/docs/integrations/google-analytics) and [Google Search Console](/docs/knowledge-base/capabilities#marketing-stack-integrations-plus-and-above) integrations. Everything below is available through a custom MCP server. The plugin is missing Amazon Ads, ChatGPT Ads, Google Analytics, and Google Search Console. | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, per-ad performance, wasted spend analysis, budget optimization | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection, EU DSA support | | **Amazon Ads** | 61 | Sponsored Products / Brands / Display, ASIN targeting, ACOS/ROAS analytics, wasted-spend detection | | **ChatGPT Ads** | 36 | Launch & manage pay-per-click chat-card ads inside ChatGPT, paused by default | | **LinkedIn Ads** | 55 | Sponsored content, lead gen forms, B2B targeting by job title, industry, seniority | | **TikTok Ads** | 37 | In-feed video, Spark Ads, pixel and video discovery, asset validation, performance analysis | > [!TIP] > > **Interactive cards.** When you run Adspirer's free [Diagnostic & Helper tools](/docs/agent-skills/diagnostic-helper-tools) — get-started guidance, launch-readiness checks, error explanations, "what changed since last visit" — the answers render as branded interactive cards (checklists, usage meters, opportunity lists, an account switcher) right inside ChatGPT, not just plain text. They're quota-free and available on every plan. > [!TIP] > > **In-chat dashboards.** Performance and audit answers render as interactive dashboards inside ChatGPT, not walls of text. `get_campaign_performance` (Google) and `get_meta_campaign_performance` (Meta) open a tabbed dashboard — Overview / Campaigns / Insights — with KPI tiles, period-over-period deltas, charts, and **7 / 14 / 30 / 60 / 90-day plus custom date-range** switching that re-runs the query live. `audit_conversion_tracking` renders a graded scorecard, and `get_connections_status` shows an account switcher. Action buttons ("pause this campaign," "draft a message for my developer") post straight back into the chat. These render on the ChatGPT mobile app too, and fall back to clean text on any client that doesn't support widgets. ## Example Prompts ### Research Keywords Keyword research with real CPC data from Google Keyword Planner. Research Google Ads keywords for "project management software" — show search volume, CPC, and competition level ### Create a Campaign Google Search campaign with keyword research and intent grouping. Create a Google Ads search campaign for my SaaS product: * Product: project management tool for remote teams * Budget: \$60/day * Research keywords first, then group by intent ### Audit Performance Wasted spend audit for zero-conversion keywords. Audit my Google Ads account for the last 30 days. Find wasted spend — keywords with clicks but zero conversions. ### Amazon Ads Wasted Spend ACOS-based wasted spend analysis. Not in the plugin. Analyze my Amazon Ads for wasted spend over the last 60 days. Which keywords are spending with no sales or a very high ACOS? Suggest negative keywords I should add. ### Ads vs. On-Site Behavior Correlate Google Ads spend with GA4 sessions and conversions. Not in the plugin. Compare last month's Google Ads spend by campaign with the GA4 sessions and conversions those campaigns drove. Which campaigns bring traffic that doesn't convert? > [!TIP] > > Mention Adspirer in your message by the name you gave your custom MCP server (e.g. **@Adspirer-Custom**) to invoke it directly. ChatGPT can also be conservative about automatically calling tools; if you need a specific one, name it explicitly, e.g., "Use the research\_keywords tool to find keywords for..." ## FAQ > **Which should I use — the plugin or a custom MCP server?** > > The custom MCP server. The Adspirer plugin in ChatGPT's directory is having issues right now, and it's missing **Amazon Ads**, **ChatGPT Ads**, **Google Analytics**, and **Google Search Console**. The custom server connects to the same Adspirer account and the same server, so nothing about your ad platform connections changes, and it gets new tools the day they ship. > **Can I have both installed at once?** > > Yes. They share one Adspirer account and one tool-call quota. If both are installed, @mention your custom server by name so ChatGPT doesn't pick the plugin. If the plugin keeps getting in the way, disconnect it under **Settings → Plugins**. > **Why does ChatGPT warn that custom MCP servers introduce risk?** > > ChatGPT shows that warning for every server it hasn't reviewed, so it appears for any custom MCP server. It's the same Adspirer server that backs the reviewed plugin. Authentication is OAuth: you sign in on adspirer.ai, approve ChatGPT on the **Authorize ChatGPT** screen, and ChatGPT holds a token, not your Google, Meta, or Amazon passwords. > **I installed the plugin and ChatGPT can't find any Amazon Ads, ChatGPT Ads, or Google Analytics tools.** > > That's expected. The plugin listing hasn't been updated since those shipped. Follow the **Custom MCP server** tab above. It takes about two minutes, and then the tools are there. > **ChatGPT says a required tool isn't available and stops mid-task.** > > Adspirer asks your assistant to look up a tool's exact parameters with `get_tool_schema` before calling it — that's what stops it inventing an argument. The plugin's tool list is fixed at the version OpenAI last approved, and on some installs `get_tool_schema` isn't in it, so ChatGPT would report a required tool as missing and stop. > > It now works around it on its own: the assistant is told to fetch the schema through a platform router instead, which returns the same thing. If an older chat still gets stuck, start a new one so ChatGPT picks up the current instructions. A custom MCP server never hits this — it always carries the current tool list. > **What are ChatGPT plugins? Are they the same as apps?** > > Yes. OpenAI renamed ChatGPT **apps** to **plugins**, and the App Store is now the **Plugins** directory. A custom MCP server you add is saved as a plugin of your own, which is why ChatGPT lists you as its developer. Plugins let ChatGPT securely connect to external services using the Model Context Protocol (MCP), the same open standard Claude uses. Adspirer's plugin manages advertising across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok. If you're weighing apps against a Custom GPT, see [ChatGPT Apps vs Custom GPTs for Advertising](https://www.adspirer.com/blog/chatgpt-apps-vs-custom-gpts). > **Which ChatGPT plans work with Adspirer?** > > Every plan, including Free. You add the custom MCP server the same way on Free, Plus, and Pro. On Business and Enterprise, your workspace admin controls custom MCP servers, so ask them if **Add custom MCP server** is missing from the **Add** menu on the Plugins page. > **How is ChatGPT different from Claude for ads?** > > Both use the same Adspirer MCP server, so functionality is identical. However, ChatGPT may be more conservative in automatically calling tools — you might need to explicitly mention which tool to use. Claude (created by Anthropic, who also created MCP) tends to invoke tools more naturally and supports progress streaming. > **Can I use Adspirer with both ChatGPT and Claude?** > > Yes. Your Adspirer account works everywhere. Add Adspirer as a custom MCP server in ChatGPT and install the Anthropic-verified Adspirer connector in Claude, and add Adspirer in Cursor, Grok Bot, Claude Code, Perplexity, or any MCP-compatible client. Your ad account connections carry across all of them. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing](https://www.adspirer.com/pricing). > **Tools aren't working or I see connection errors. What do I do?** > > If no Adspirer tools work at all (even basic ones like checking connections), follow these steps: > > 1. **Check tool permissions:** In **Settings → Plugins**, set your Adspirer plugin to **Allow low-risk tools**, so read tools run on their own and changes still ask first, or to **Always ask**. If you blocked tools by accident, reset the permission there. > 2. **Reconnect:** > * *Custom MCP server* — **Settings → Plugins**, remove the plugin you created, then **Plugins → Add → Add custom MCP server** again with `https://mcp.adspirer.com/mcp` and sign in. > * *Adspirer plugin* — the plugin is having issues right now. Disconnect it in **Settings → Plugins** and add the custom MCP server instead. > 3. **Refresh your Adspirer session:** Go to [adspirer.ai](https://adspirer.ai), log out, log back in, then return to ChatGPT. > > ChatGPT plugins may disconnect every 1–2 weeks — this is normal. Just reconnect and re-authenticate when it happens. > > See [Troubleshooting FAQ](/docs/knowledge-base/faq#troubleshooting) for more details. ## Related Documentation * [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) — Sponsored Products, Brands, and Display (custom MCP server) * [Google Analytics 4 Integration](/docs/integrations/google-analytics) — Correlate ad spend with on-site behavior (custom MCP server) * [Claude Setup](/docs/ai-clients/claude) — the Anthropic-verified Adspirer connector, with progress streaming * [Perplexity Setup](/docs/ai-clients/perplexity) — Search-powered ad management via Perplexity Computer * [Claude Code Setup](/docs/ai-clients/claude-code) — Terminal-based setup for developers * [Google Ads Integration](/docs/ad-platforms/google-ads) — Full Google Ads tool reference * [How to Connect ChatGPT to Google Ads](https://www.adspirer.com/blog/connect-chatgpt-google-ads) — Step-by-step walkthrough with example prompts * [ChatGPT Apps vs Custom GPTs for Advertising](https://www.adspirer.com/blog/chatgpt-apps-vs-custom-gpts) — Which ChatGPT setup is right for managing ad campaigns * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; paste its agent instructions into a ChatGPT Project (\$39 one-time) # Connect Claude to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/claude Adspirer is an Anthropic-verified connector in Claude's directory. Search for it, click Connect to Claude, and manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads with 400+ tools. No URL to paste. > [!NOTE] > > **Adspirer is an Anthropic-verified connector.** Open **Customize → Connectors**, search for **Adspirer**, and click **Connect to Claude**. You don't need a custom connector or an MCP URL. The listing is **Adspirer Ads & Performance Marketing Agent**, and the verified badge means Anthropic has reviewed it for quality and security. Adspirer gives Claude live access to your ad accounts, with native tool calls and progress streaming. Add it from Claude's directory once and it's available in every chat. [Claude Cowork + Adspirer: 30 Days of Ads Analyzed in One Prompt](https://www.youtube.com/embed/zgNjF1y6GzY) Claude Cowork + Adspirer: 30 Days of Ads Analyzed in One Prompt ## Prerequisites > [!NOTE] > > * A Claude **Pro**, **Max**, **Team**, or **Enterprise** subscription (connectors are not available on the free tier) > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)). You can also create one during the connect step > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup (2 Minutes) There are two listings in Claude's directory, and both connect to the same Adspirer account. The **connector** gives Claude the 400+ tools. The **plugin** installs that same verified connector and adds Adspirer's 15 skills, 5 slash commands, and a performance marketing agent. You don't need both. **Connector (verified)** **1. Search Claude's directory for Adspirer** Open [Customize → Connectors](https://claude.ai/customize/connectors), make sure **Discover** is selected, and type **Adspirer** in the search box. Pick **Adspirer Ads & Performance Marketing Agent** by Adspirer. It's the one with the verified badge. ![Claude Customize page with the Connectors tab and Discover selected, showing Adspirer Ads & Performance Marketing Agent by Adspirer with a verified badge in the search results](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/claude/directory-search.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=9cb772f0357525ce1a9fbaec8435d0bc) Search Customize → Connectors → Discover for Adspirer Or go straight to the [Adspirer listing](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent). **2. Click Connect to Claude** On the listing, click **Connect to Claude**. Hover the badge next to the name to see *"Verified — Anthropic has reviewed this connector for quality and security."* ![Adspirer Ads & Performance Marketing Agent listing in Claude with the tooltip 'Verified — Anthropic has reviewed this connector for quality and security' and the Connect to Claude button](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/claude/connector-verified.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=fef83b19724b8a6f8c94432af45c5319) The Adspirer listing in Claude, with the verified badge and the Connect to Claude button **3. Sign in to Adspirer** Your browser opens Adspirer's sign-in page. Sign in (or create an account) and approve Claude. Authentication is OAuth, so Claude never sees your ad platform passwords. If you close the window early, Claude shows **You started connecting...but didn't finish**. Click **Connect** on that screen to pick up where you left off. ![Claude connector screen explaining that the Adspirer connection was started but not finished, with a Connect button to resume](https://mintcdn.com/adspirer/9neHVIcd-r_femLX/images/claude/connection-resume.png?fit=max\&auto=format\&n=9neHVIcd-r_femLX\&q=85\&s=f7b7aee9cd5b617134171ab36577c6dd) Resume the connection if sign-in was interrupted **4. Connect your ad accounts** Link the platforms you want Claude to manage at [adspirer.ai/connections](https://adspirer.ai/connections). Claude can only reach accounts you've connected there. **5. Check the connection** Under **Customize → Connectors → Yours**, **Adspirer Ads & Performance Marketing Agent** shows a checkmark in the **Status** column. ![Claude Connectors page showing Adspirer Ads & Performance Marketing Agent with a connected status checkmark](https://mintcdn.com/adspirer/9neHVIcd-r_femLX/images/claude/connector-connected.png?fit=max\&auto=format\&n=9neHVIcd-r_femLX\&q=85\&s=826021f28cca8f43727a6dafe486dd42) The checkmark confirms that Adspirer is connected **Plugin (connector + skills)** **1. Search Claude's plugins for Adspirer** Open [Customize → Plugins](https://claude.ai/customize/plugins), select **Discover**, and search for **Adspirer**. The listing says **from Anthropic Directory**. Or go straight to the [Adspirer plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory). ![Adspirer plugin listing in Claude, from Anthropic Directory, with tabs for Skills 15, Commands 5, Connectors 1, and Agents 1 and an Add button](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/claude/plugin-directory.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=694e7b2dac6dd3e8b3b2ce2ec91c0c40) The Adspirer plugin: 15 skills, 5 commands, 1 connector, and 1 agent **2. Click Add** Click **Add**. The plugin installs **Adspirer Ads & Performance Marketing Agent** (the verified connector) along with the skills, commands, and agent. **3. Sign in to Adspirer** When Claude asks you to connect, sign in to Adspirer in your browser and approve Claude. Then link your ad platforms at [adspirer.ai/connections](https://adspirer.ai/connections). > [!TIP] > > The plugin is the same install you use in [Claude Cowork](/docs/ai-clients/claude-cowork). Skills teach Claude Adspirer's workflows: research before creating, validate before launching, and confirm before spending. They load automatically when your request matches. ## Start a New Chat Start a new chat and ask: Confirms the connection without changing anything. Check my connected ad platforms You should see a table of your connected accounts across all platforms, with account IDs, names, and connection status. If Claude answers without calling Adspirer, open the chat's tools menu below the text box and check that **Adspirer Ads & Performance Marketing Agent** is switched on. > [!TIP] > > You're connected. Claude now uses Adspirer's tools whenever you ask about your ad campaigns. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=claude)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. ## Connector Details ``` Name: Adspirer Ads & Performance Marketing Agent Developer: Adspirer Status: Anthropic verified Plugin: Adspirer (Anthropic Directory): the connector plus 15 skills, 5 commands, 1 agent Authentication: OAuth Required Plan: Claude Pro, Max, Team, or Enterprise ``` Both listings connect to Adspirer's live server, so new tools show up in Claude the day they ship. You never need to update anything. For the terminal, see the [Claude Code Setup Guide](/docs/ai-clients/claude-code). ## Why Claude for Advertising Claude offers unique advantages for ad management: * **Progress Streaming** — Real-time updates during long operations. See campaign creation progress as it happens (5–30 seconds). * **Natural Tool Invocation** — Claude understands when to use Adspirer's tools without special syntax. Just describe your goals. * **Native MCP** — Anthropic created the Model Context Protocol. Claude has the deepest, most reliable integration. * **Team & Enterprise** — Admins add the connector once for the entire org. Team members authenticate individually. ## What You Can Do 400+ tools across 6 ad platforms: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, per-ad performance, wasted spend analysis, budget optimization | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection, EU DSA support | | **Amazon Ads** | 61 | Sponsored Products / Brands / Display, ASIN targeting, ACOS/ROAS analytics, wasted-spend detection | | **ChatGPT Ads** | 36 | Launch & manage pay-per-click chat-card ads inside ChatGPT, paused by default | | **LinkedIn Ads** | 55 | Sponsored content, lead gen forms, B2B targeting by job title, industry, seniority | | **TikTok Ads** | 37 | In-feed video, Spark Ads, pixel and video discovery, asset validation, performance analysis | > [!TIP] > > **Interactive cards.** When you run Adspirer's free [Diagnostic & Helper tools](/docs/agent-skills/diagnostic-helper-tools) — get-started guidance, launch-readiness checks, error explanations, "what changed since last visit" — the answers render as branded interactive cards (checklists, usage meters, opportunity lists, an account switcher) right inside Claude, not just plain text. They're quota-free and available on every plan. > [!TIP] > > **In-chat dashboards.** Performance and audit answers render as interactive dashboards inside Claude. `get_campaign_performance` (Google) and `get_meta_campaign_performance` (Meta) open a tabbed dashboard — Overview / Campaigns / Insights — with KPI tiles, period-over-period deltas, charts, and **7 / 14 / 30 / 60 / 90-day plus custom date-range** switching. `audit_conversion_tracking` renders a graded scorecard and `get_connections_status` an account switcher, with action buttons that post back into the chat. Widgets render in Claude on web, desktop (macOS), and mobile; Claude Code shows a clean text fallback. ## Example Prompts ### Research Keywords Keyword research with real CPC data from Google Keyword Planner. Research Google Ads keywords for "project management software" — show search volume, CPC, and competition level ### Create a Campaign Google Search campaign with keyword research and intent grouping. Create a Google Ads search campaign for my SaaS product: * Product: project management tool for remote teams * Budget: \$60/day * Research keywords first, then group by intent ### Cross-Platform Audit Multi-platform audit with prioritized action list and savings estimate. Audit all my ad accounts for the last 30 days: * Google: find wasted spend (keywords with clicks but zero conversions) * Meta: check for creative fatigue (frequency > 3, declining CTR) * LinkedIn: compare CPA across audience segments Give me a prioritized action list with estimated monthly savings. ## Team & Enterprise Setup For organizations using Claude Team or Enterprise: **Owner setup:** a workspace owner finds **Adspirer Ads & Performance Marketing Agent** in Claude's directory (search "Adspirer") and turns it on for the organization. Because it's an Anthropic-verified directory listing, there's no custom connector to approve and no server URL to allow-list. **Member setup:** 1. Go to **Customize → Connectors** 2. Find **Adspirer Ads & Performance Marketing Agent** and click **Connect** 3. Sign in to Adspirer and link your own ad accounts Each team member authenticates with their own ad accounts while using the org-wide connector. Agencies running campaigns across many client accounts can [book a demo](https://www.adspirer.com/book-demo) to size a plan with multi-seat access, pooled tool calls, and dedicated support. ## FAQ > **Do I need to add a custom connector or paste the MCP URL?** > > No. Adspirer is an Anthropic-verified connector, so you add it by searching Claude's directory. Don't use **Add custom connector**. The directory listing connects to the same server, always has the latest tools, and in the plugin form also includes Adspirer's skills, commands, and agent. If you added Adspirer as a custom connector before it was listed, remove that one and connect the verified listing so Claude doesn't see two copies of every tool. > **Is it a connector or a plugin?** > > Both exist, and both come from Adspirer through Anthropic's directory. **Adspirer Ads & Performance Marketing Agent** is the verified connector: the 400+ tools. The **Adspirer** plugin installs that connector plus 15 skills, 5 slash commands, and an agent. Use the connector for chat. Use the plugin if you want the skills and commands, or if you work in [Cowork](/docs/ai-clients/claude-cowork). > **What are Claude connectors?** > > Claude connectors (powered by MCP — Model Context Protocol) allow Claude to securely connect to external services and take actions on your behalf. Anthropic created MCP as an open standard for AI tool integration. **Adspirer Ads & Performance Marketing Agent** enables advertising management across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads. > **Which Claude plans support connectors?** > > MCP connectors are available on Claude Pro, Max, Team, and Enterprise plans. The free tier does not include connector functionality. Claude Code (for developers) also supports MCP on paid plans. > **What makes Claude different from ChatGPT for ads?** > > Claude was created by Anthropic, who also developed MCP. This means the deepest integration, including progress streaming that shows real-time updates during campaign creation. Claude also naturally invokes tools without explicit prompting, while ChatGPT may need you to mention specific tools by name. > **Can I also use Claude Code?** > > Yes. Claude Code is the terminal-based developer tool that also supports MCP. See the full [Claude Code Setup Guide](/docs/ai-clients/claude-code) for the one-command setup. Both Claude (chat app) and Claude Code connect to the same Adspirer MCP server. > **Can I use Adspirer with both Claude and ChatGPT?** > > Yes. Your Adspirer account works across all supported AI clients. Connect **Adspirer Ads & Performance Marketing Agent** from Claude's directory and install the Adspirer plugin from ChatGPT's **Plugins** directory. Your Adspirer account and ad platform connections carry across both. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing](https://www.adspirer.com/pricing). > **Tools aren't working or I see connection errors. What do I do?** > > If no Adspirer tools work at all (even basic ones like checking connections), follow these steps: > > 1. **Check tool permissions:** When Claude prompts you to allow a tool, make sure read tools are set to **Always allow** and write tools to **Custom** (ask each time). If you accidentally blocked tools, go to **Customize → Connectors**, find **Adspirer Ads & Performance Marketing Agent**, and reset permissions. > 2. **Reconnect the connector:** Go to **Customize → Connectors**, disconnect **Adspirer Ads & Performance Marketing Agent**, then connect again and complete the OAuth flow. > 3. **Refresh your Adspirer session:** Go to [adspirer.ai](https://adspirer.ai), log out, log back in, then return to Claude. > > Claude web connectors may disconnect every 1–2 weeks — this is normal. Just re-enable and re-authenticate when it happens. > > See [Troubleshooting FAQ](/docs/knowledge-base/faq#troubleshooting) for more details. ## Related Documentation * [ChatGPT Setup](/docs/ai-clients/chatgpt) — the Adspirer plugin for ChatGPT * [Perplexity Setup](/docs/ai-clients/perplexity) — Search-powered ad management via Perplexity Computer * [Claude Code Setup](/docs/ai-clients/claude-code) — Terminal-based setup for developers * [Google Ads Integration](/docs/ad-platforms/google-ads) — Full Google Ads tool reference * [Agent Skills Overview](/docs/agent-skills/overview) — Teach Claude the right workflows * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, dossier, and prompt book generated from your own ad account (\$39 one-time) * [How to Connect Claude to Google Ads](https://www.adspirer.com/blog/connect-claude-google-ads) — Step-by-step walkthrough with example prompts * [Pricing & Plans](https://www.adspirer.com/pricing) # Connect Claude Code to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/claude-code Connect Claude Code to Adspirer MCP in 2 minutes. Manage Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads from your terminal with 400+ tools. Manage all your ad campaigns from the terminal. Two commands to connect, 400+ tools to use. > [!TIP] > > **Adspirer runs its own Claude Code plugin marketplace.** Add it once with `/plugin marketplace add amekala/ads-mcp`, then install **Adspirer Advertising Agent** from the **Discover** tab (or run `/plugin install adspirer-advertising-agent@adspirer-marketplace` directly). This is the recommended way to connect Adspirer to Claude Code — full walkthrough below. [Adspirer + Claude Code: Create Google Ads Campaigns From Your Terminal](https://www.youtube.com/embed/hkYsJ5urfJY) Create Google Ads Campaigns From Your Terminal ## Prerequisites > [!NOTE] > > * Claude Code installed: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > npm install -g @anthropic-ai/claude-code > ``` > > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads > * macOS or Linux (Windows requires WSL) ## Setup ### Install Adding Adspirer's plugin marketplace once, then installing the plugin, sets up the MCP connector, slash commands, skills, and the Performance Marketing Agent together. > [!NOTE] > > The `/plugin`, `/mcp`, and `/reload-plugins` commands below are **slash commands** — type them directly into the Claude Code input. Do not ask the AI to run them for you (that will cause a "nested session" error). **1. Add the Adspirer Marketplace** Adspirer runs its own plugin marketplace on GitHub — it's not on a shared/curated marketplace, so you add it once by source. Type `/plugin` to open the plugin manager. The UI has four tabs — **Discover**, **Installed**, **Marketplaces**, **Errors** — cycle with Tab. Switch to **Marketplaces**, then select **+ Add Marketplace**. ![Claude Code plugin manager Marketplaces tab with + Add Marketplace option](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/marketplace-tab.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=1f8551e5190ef753a650b5bd7b83fb5c) Plugin manager — Marketplaces tab, + Add Marketplace Enter the marketplace source and press Enter: ``` amekala/ads-mcp ``` ![Add Marketplace dialog with amekala/ads-mcp entered as the GitHub source](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/marketplace-add-dialog.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=2ae325c0b7571f3c7f0be6a0266be44b) Add Marketplace — entering amekala/ads-mcp as the source This registers Adspirer's marketplace (`adspirer-marketplace`) and downloads its plugin list. Or skip the UI and run it directly: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin marketplace add amekala/ads-mcp ``` **2. Find and Install the Plugin** Switch to the **Discover** tab — you'll see **Adspirer Advertising Agent**. ![Plugin Discover tab showing Adspirer Advertising Agent plugin](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/plugin-discover-search.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=6f81d8b6a8676214915cf1eb914ca30c) Discover tab — Adspirer Advertising Agent found after adding the marketplace Select it and install. Or install directly from the command line: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin install adspirer-advertising-agent@adspirer-marketplace ``` **3. Reload Plugins** Claude Code confirms the install and prompts you to reload: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /reload-plugins ``` Or close and reopen Claude Code. ![Claude Code output confirming Adspirer Advertising Agent installed, followed by reload-plugins output](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/plugin-reloaded.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=6eb7fba251c2dad27622a40e4bcc64d0) Plugin installed, then /reload-plugins applies it **4. Authenticate with Adspirer** The plugin's MCP server needs a one-time OAuth sign-in. Type `/mcp` to open the MCP server manager. ![Typing the /mcp slash command in Claude Code](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/mcp-command.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=864045662c6ee9ea9862ac0553613850) Typing /mcp to open the MCP server manager Find **plugin:adspirer-advertising-agent:adspirer** in the list, select it, then choose **Authenticate** — your browser opens for OAuth sign-in. Sign in with your Adspirer account and review the requested scopes (campaigns:read/write, performance:read, accounts:read). **New to Adspirer?** The browser lands on a quick sign-up page first — create a free account (no credit card) and you're sent straight back to the authorization screen. Click **Authorize**. ![Adspirer OAuth authorization page showing requested scopes](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/oauth-scopes.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=1698175a9dcd9372e9272aae5ac45045) OAuth authorization — review and approve the requested scopes Return to Claude Code and run `/mcp` (or `/plugin`) again — **plugin:adspirer-advertising-agent:adspirer** now shows connected with its full tool count. You're ready to go. ![MCP server manager showing plugin:adspirer-advertising-agent:adspirer connected](https://mintcdn.com/adspirer/1O0fQlIGCYmUzlC7/images/claude-code/mcp-server-connected.png?fit=max\&auto=format\&n=1O0fQlIGCYmUzlC7\&q=85\&s=435730dd539e3dc938720a038a69357f) plugin:adspirer-advertising-agent:adspirer connected, 20 tools **5. Set Up Your Brand Workspace** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /adspirer:setup ``` This connects to your accounts, scans your folder for brand docs, pulls live campaign data, and creates a `CLAUDE.md` brand workspace file. ![Adspirer slash commands in Claude Code](https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/images/claude-code/slash-commands.png?fit=max\&auto=format\&n=vhaKM86uNtBGo98V\&q=85\&s=ed66f5582a8a7b2a18c2ea5fd3511b5d) All Adspirer slash commands available after setup **6. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=claude-code)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. ### Verify Your Setup Run a test prompt: ``` Check my connected ad platforms ``` You should see a table showing your connected accounts across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads — along with account IDs, names, and connection status. > [!TIP] > > You're connected. Claude Code now has access to 400+ advertising tools from your terminal. ## Brand Workspace When you run `/adspirer:setup`, the agent bootstraps a brand-specific workspace: 1. **Connects to Adspirer** — verifies your ad platform connections 2. **Scans your folder** — reads any brand docs (`.md`, `.txt`, `.csv`, `.yaml`, `.json`, `.pdf`) for voice, audience, and budget context 3. **Pulls live data** — campaign performance, search terms, benchmarks from all connected platforms 4. **Creates `CLAUDE.md`** — a brand context file with connected platforms, performance snapshot, KPI targets, and brand guidelines Open your brand folder and run setup: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ~/Clients/YourBrand claude ``` Then say "set up my brand workspace" or run `/adspirer:setup`. Your brand folder can contain docs or be completely empty — the agent builds context from your live ad platform data either way. More docs = better brand context = better ad copy and recommendations. ## Slash Commands The plugin includes 5 slash commands that trigger proven workflows: | Command | What it Does | | - | - | | `/adspirer:setup` | Bootstrap a brand workspace — connect accounts, scan docs, pull data, create CLAUDE.md | | `/adspirer:performance-review` | Cross-platform performance scorecard with KPI comparison | | `/adspirer:write-ad-copy` | Brand-voice ad copy from real keyword and performance data | | `/adspirer:wasted-spend` | Find and fix wasted spend across all platforms | | `/adspirer:refresh-brand-context` | Re-scan docs and update CLAUDE.md with latest data | You don't need to remember these — just describe what you want and Claude will use the right workflow. ## What You Can Do 400+ tools across 6 ad platforms. Here's what matters: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, wasted spend analysis, budget optimization, ad extensions, asset management | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | Sponsored content, lead gen forms, B2B targeting (job titles, industries, seniority), creative performance analysis | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection, placement optimization | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance analysis | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | Plus 8 automation tools: scheduled briefs, performance monitors, cross-platform reports. ## Example Prompts What to actually say once you're set up: ### Google Search Campaign Google Search campaign with keyword research grouped by intent. Create a Google Ads search campaign for my SaaS product: * Product: project management tool for remote teams * Target: team leads and ops managers at companies with 20-200 employees * Budget: \$60/day * Research keywords with real CPC data first * Group keywords by intent (branded, competitor, feature-based) ### Google PMax Campaign Performance Max campaign across all Google channels. Set up a Performance Max campaign for my e-commerce store: * Product: organic dog treats, \$24.99 avg order value * Target ROAS: 400% * I have product images at these URLs: \[paste URLs] * Write 5 headlines and 3 descriptions * Use my existing Google Merchant Center feed ### Meta Ads Campaign Meta image campaign with audience targeting and creative copy. Create a Meta image campaign for my skincare brand: * Product: anti-aging serum for women 30-55 * Budget: \$40/day * Target interests: skincare, beauty, wellness, anti-aging * Image URL: \[paste URL] * Write 3 primary text variations and 2 headlines * Optimize for purchases ### LinkedIn Ads Campaign LinkedIn B2B campaign targeting senior data leaders. Launch a LinkedIn sponsored content campaign: * Product: enterprise data analytics platform * Target: VPs and Directors of Data/Analytics at companies with 500+ employees * Industries: financial services, healthcare, technology * Budget: \$100/day * Goal: lead generation with a whitepaper download * Image URL: \[paste URL] ### Cross-Platform Audit Multi-platform audit with prioritized action list and savings estimate. Audit all my ad accounts for the last 30 days: * Google: find wasted spend (keywords with clicks but zero conversions) * Meta: check for creative fatigue (frequency > 3, declining CTR) * LinkedIn: compare CPA across audience segments Give me a prioritized action list with estimated monthly savings. ## Safety Features Adspirer's agent skills enforce safety rules to prevent accidental spend: * **All campaigns created PAUSED:** You review before they go live * **User confirmation required:** Claude asks before any action that affects spend * **Read-before-write:** Skills force research and validation before campaign creation * **Connection status checks:** Always verifies you're managing the right account first * **No automatic retries:** If a campaign creation fails, Claude won't retry without asking ## Troubleshooting ### "Nested session" error when installing If you see `Error: Claude Code cannot be launched inside another Claude Code session`, you're asking the AI to install the plugin instead of typing the slash command yourself. The `/plugin` command must be typed directly into the Claude Code input — don't ask Claude to run them for you. ### Plugin not showing after install Run `/reload-plugins` after installing, or restart Claude Code. Then verify via either: * `/plugin` → **Installed** tab — you should see **Adspirer Advertising Agent** listed * `/mcp` — you should see **plugin:adspirer-advertising-agent:adspirer** If the plugin is missing from the **Discover** tab, make sure the marketplace was added (`/plugin` → **Marketplaces** tab should list `adspirer-marketplace`), or refresh it: `/plugin marketplace update adspirer-marketplace`. ### Authentication keeps failing Clear your browser cache or try a different browser. The OAuth flow uses PKCE for security — some browser extensions can interfere. Disable ad blockers temporarily. ### MCP server not found Run `/mcp` and look for **plugin:adspirer-advertising-agent:adspirer**. If it's missing, run `/reload-plugins` or restart Claude Code. If it's still missing, re-run: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin marketplace add amekala/ads-mcp /plugin install adspirer-advertising-agent@adspirer-marketplace ``` ### Tools not working after connecting Check your Adspirer account status at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account). Free accounts get 15 tool calls/month. If you've hit the limit, upgrade to Plus ($49/mo for 150 calls) or Pro ($99/mo for 600 calls). ### Skills not loading Verify the skills directory exists: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} ls -la ~/.claude/skills/ad-campaign-management/ ``` You should see a SKILL.md file. If not, re-run the plugin install command. ### Slash commands not available If `/adspirer:setup` isn't recognized, the plugin may not be installed. Run: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin marketplace add amekala/ads-mcp /plugin install adspirer-advertising-agent@adspirer-marketplace /reload-plugins ``` ## FAQ > **Do I need to know MCP to use this?** > > No. MCP (Model Context Protocol) is the plumbing — you don't interact with it directly. You just talk to Claude in plain English. The MCP connection happens behind the scenes. > **What's the difference between Claude Code and Claude Cowork / Claude Desktop?** > > **Claude Code is Anthropic's terminal/CLI developer tool** — you run `claude` in a shell, it works inside your codebase, optimized for software-engineering workflows. There's also a Claude Code desktop / IDE-side surface. > > **[Claude Cowork](/docs/ai-clients/claude-cowork)** is a completely different product — a brand-aware workspace mode inside the Claude desktop app (and on claude.ai). You open a folder, Claude reads its docs, and you collaborate with it on the work in that folder. > > Both support Adspirer through MCP, but they're separate apps. Use Claude Code if you live in the terminal. Use [Claude Cowork](/docs/ai-clients/claude-cowork) if you want a brand-aware workspace with folder context. > **What does the plugin install?** > > The `adspirer-advertising-agent` plugin installs: the MCP server connection, 5 slash commands (setup, performance-review, write-ad-copy, wasted-spend, refresh-brand-context), a performance marketing agent, and the ad campaign management skill file. > **Can I manage multiple ad accounts?** > > Yes. Adspirer supports multiple accounts per platform. Use the `switch_primary_account` tool to change which account you're managing, or specify the account ID in your prompts. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See the [full pricing breakdown](https://www.adspirer.com/pricing). > **Is my data safe?** > > Yes. Adspirer uses OAuth 2.1 with PKCE — we never see your passwords. Your ad account credentials live with Google/Meta/LinkedIn/TikTok. We only get read/write permissions you explicitly authorize. You can revoke access anytime from your ad platform's security settings. ## Related Documentation * [Google Ads Integration Guide](/docs/ad-platforms/google-ads) * [Claude Desktop + Adspirer](https://www.adspirer.com/integrations/claude) * [Pricing & Plans](https://www.adspirer.com/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; drop the skill folder into `.claude/skills/` and its agent definition into `.claude/agents/` (\$39 one-time) # Connect Claude Cowork to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/claude-cowork Connect Claude Cowork (Claude's desktop app workspace mode — not the terminal CLI) to Adspirer. Manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads with 400+ tools, brand-aware skills, and a marketing agent. **Claude Cowork is Claude's brand-aware workspace mode inside the Claude desktop app** (and on claude.ai) — you open a folder, Claude reads its docs, and you collaborate with it on the work in that folder. This is different from [Claude Code](/docs/ai-clients/claude-code), which is Anthropic's terminal/CLI developer tool. They're two separate products from Anthropic that both happen to support MCP connectors. > [!NOTE] > > **Cowork vs. Claude Code — which page do you want?** > > | | **Claude Cowork** (this page) | **[Claude Code](/docs/ai-clients/claude-code)** | > | - | - | - | > | **What it is** | Workspace mode in the Claude desktop app — open a folder, chat with Claude about its contents | Terminal CLI / IDE-side developer tool from Anthropic | > | **Where you use it** | Claude desktop app → **Cowork** tab (or claude.ai → Cowork) | `claude` command in your shell, or Claude Code desktop | > | **How you connect Adspirer** | **Customize → Plugins** → search Adspirer → **Add** (this page) | `/plugin install adspirer-ads-agent@claude-community` | > | **Plan required** | Claude **Max**, Team, or Enterprise | Any Claude plan | > | **Best for** | Brand-aware advertising work where Claude reads your brand folder | Terminal-first developer workflows | This page is for **Claude Cowork** — Claude's brand-aware advertising workspace. Connect Adspirer and you get 400+ ad management tools the agent can call against your Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok accounts, all grounded in the brand folder you point Cowork at. [How to connect Claude Cowork with Adspirer](https://www.youtube.com/embed/Bgpkc2DDcEM) How to connect Claude Cowork with Adspirer ## Prerequisites > [!NOTE] > > * A Claude **Max**, **Team**, or **Enterprise** subscription (Cowork requires Max or above) > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup (5 Minutes) Search for Adspirer under **Customize → Plugins** and click **Add**. One install brings in Adspirer's Anthropic-verified connector, 15 skills, 5 slash commands, and a Performance Marketing Agent. ### 1. Open Cowork and Customize **1. Open Claude Cowork** Open the Claude desktop app (or claude.ai) and click the **Cowork** tab at the top. ![Claude Cowork tab](https://mintcdn.com/adspirer/0GXeYWLZAEKikC6R/images/claude-cowork/cowork-tab.png?fit=max\&auto=format\&n=0GXeYWLZAEKikC6R\&q=85\&s=5e3d0544af32ac28750034269dcdf5f5) Select the Cowork tab in Claude **2. Go to Customize** Click **Customize** in the left sidebar. Skills, Connectors, and Plugins are all managed here. ### 2. Add the Adspirer plugin from Anthropic's directory The plugin comes from Anthropic's directory and bundles the verified **Adspirer Ads & Performance Marketing Agent** connector with 15 skills, 5 slash commands, and a Performance Marketing Agent. You don't add a custom connector or paste a URL. **1. Search Plugins for Adspirer** In **Customize**, open **Plugins**, select **Discover**, and search for **adspirer**. Choose **Adspirer** — the listing reads **from Anthropic Directory**. Or open the [Adspirer plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory) directly. ![Adspirer plugin listing in Claude, from Anthropic Directory, with tabs for Skills 15, Commands 5, Connectors 1, and Agents 1 and an Add button](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/claude/plugin-directory.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=694e7b2dac6dd3e8b3b2ce2ec91c0c40) The Adspirer plugin in Anthropic's directory: 15 skills, 5 commands, 1 connector, 1 agent **2. Click Add** Click **Add**. The **Contents** tab lists what installs: * **Commands**: `/setup`, `/performance-review`, `/write-ad-copy`, `/wasted-spend`, `/refresh-brand-context` * **Skills**: 15 skills that teach Claude Adspirer's advertising workflows, per platform and per task * **Connector**: **Adspirer Ads & Performance Marketing Agent**, the Anthropic-verified connector with 400+ tools * **Agent**: a Performance Marketing Agent that runs ad work with your brand context **3. Connect Adspirer** Claude asks you to connect **Adspirer Ads & Performance Marketing Agent**. Click **Connect**. You can also do it later from **Customize → Connectors**. > [!WARNING] > > **Connect button grayed out?** Two common causes: > > * **You're on a VPN.** Many corporate VPNs block the handshake to `mcp.adspirer.com`. Disconnect from the VPN and try again. > * **Your workspace hasn't allowed it.** On Claude Team or Enterprise, an owner controls which directory connectors and plugins members can use. Ask them to allow Adspirer. It's an Anthropic-verified listing, so there's no custom URL for them to approve. **4. Sign in to Adspirer** Your browser opens Adspirer's sign-in page. Sign in (or create an account), approve Claude, and link your Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok accounts at [adspirer.ai/connections](https://adspirer.ai/connections). Once you've approved it, the connector shows as connected and its tools are listed under tool permissions. > [!TIP] > > **Recommended tool permissions.** Set **Interactive** and **Read-only** tools to **Always allow** so research, reporting, and dashboards run without interruption. Leave **Write / delete** tools on **Needs approval**, so anything that changes a campaign still pauses for your confirmation. Adspirer also creates every new campaign paused by default. > [!TIP] > > If the connector doesn't show as connected right away, restart Claude and check again. ### 3. Open a brand folder and try it **1. Work in a Brand Folder** Back on the Cowork main screen, click **Work in a folder** and select the folder containing your brand documents — voice of customer research, brand guidelines, previous campaigns, keyword research, audience targeting docs, or any other brand context. Claude Cowork will use this folder as your brand workspace. The more context you provide, the better Adspirer's recommendations and ad copy will be. > [!NOTE] > > Your brand folder can contain docs or be completely empty — the agent builds context from your live ad platform data either way. More docs = better brand context = better ad copy and recommendations. **2. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=claude-cowork)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. > [!TIP] > > You're connected. Claude Cowork now has access to 400+ advertising tools, brand-aware skills, and a Performance Marketing Agent that knows how to use them in the right order. ## Slash Commands The plugin includes 5 slash commands that trigger proven workflows: | Command | What it Does | | - | - | | `/setup` | Bootstrap a brand workspace — connect accounts, scan docs, pull data, create CLAUDE.md | | `/performance-review` | Cross-platform performance scorecard with KPI comparison | | `/write-ad-copy` | Brand-voice ad copy from real keyword and performance data | | `/wasted-spend` | Find and fix wasted spend across all platforms | | `/refresh-brand-context` | Re-scan docs and update CLAUDE.md with latest data | You don't need to remember these — just describe what you want and Claude will use the right workflow. ## What You Can Do 400+ tools across 6 ad platforms: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, per-ad performance, wasted spend analysis, budget optimization | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection, EU DSA support | | **Amazon Ads** | 61 | Sponsored Products / Brands / Display, ASIN targeting, ACOS/ROAS analytics, wasted-spend detection | | **ChatGPT Ads** | 36 | Launch & manage pay-per-click chat-card ads inside ChatGPT, paused by default | | **LinkedIn Ads** | 55 | Sponsored content, lead gen forms, B2B targeting by job title, industry, seniority | | **TikTok Ads** | 37 | In-feed video, Spark Ads, pixel and video discovery, asset validation, performance analysis | ## Example Prompts ### Research Keywords Keyword research with real CPC data from Google Keyword Planner. Research Google Ads keywords for "project management software" — show search volume, CPC, and competition level ### Create a Campaign Google Search campaign with keyword research and intent grouping. Create a Google Ads search campaign for my SaaS product: * Product: project management tool for remote teams * Budget: \$60/day * Research keywords first, then group by intent ### Cross-Platform Audit Multi-platform audit with prioritized action list and savings estimate. Audit all my ad accounts for the last 30 days: * Google: find wasted spend (keywords with clicks but zero conversions) * Meta: check for creative fatigue (frequency > 3, declining CTR) * LinkedIn: compare CPA across audience segments Give me a prioritized action list with estimated monthly savings. ## Why Claude Cowork for Advertising * **Brand-Aware** — Cowork reads the brand folder you point it at. Voice guidelines, past campaigns, audience targeting docs — all of it informs ad copy and recommendations. * **Desktop App, Not Terminal** — Cowork lives in the Claude desktop app and on claude.ai. No CLI, no terminal commands. If you want a CLI workflow, use [Claude Code](/docs/ai-clients/claude-code) instead. * **Plugin Ecosystem** — The Adspirer plugin ships the Anthropic-verified connector, 5 slash commands, 15 skills, and a Performance Marketing Agent that knows how to use all 400+ Adspirer tools in the right order with safety rules — all added in one click from Anthropic's directory. * **Progress Streaming** — Real-time updates during long operations. See campaign creation progress as it happens. * **Native MCP** — Anthropic created the Model Context Protocol. Claude has the deepest, most reliable integration. ## FAQ > **What is Claude Cowork?** > > Claude Cowork is a **workspace mode inside the Claude desktop app** (also on claude.ai) where you point Claude at a folder on your machine and it reads everything inside as context — brand docs, voice guidelines, past campaigns, keyword research. You then chat with Claude about that work, and the agent has full visibility into your brand. Cowork is built around folders + plugins + connectors. It's where brand-aware advertising work happens. > **Is Cowork the same thing as Claude Code?** > > **No — they are two different products from Anthropic.** > > * **Claude Cowork** is the workspace mode inside the Claude desktop app and claude.ai. You use it through a GUI. It's the page you're on right now. > * **[Claude Code](/docs/ai-clients/claude-code)** is Anthropic's terminal/CLI developer tool. You run `claude` in a shell, it works inside your codebase, and it's optimized for software-engineering workflows. It also has a desktop / IDE-side surface. > > They're separate apps. Cowork ≠ Claude Code. If you typed `claude` in your terminal to get here, you want the [Claude Code setup page](/docs/ai-clients/claude-code), not this one. > **How is Cowork different from Claude Chat?** > > Claude Chat (the standard chat interface) supports connectors — you add an MCP server URL and that's it. Cowork supports the same connectors **plus** plugins (slash commands, skills, agents) **plus** brand folders. For one-off ad questions, Chat is fine. For ongoing brand-aware work, Cowork is the richer surface. > **Which Claude plans support Cowork?** > > Cowork is available on Claude Max, Team, and Enterprise plans. Pro plans have access to Chat connectors but not the full Cowork experience. > **What does the Adspirer plugin include?** > > The plugin installs Adspirer's Anthropic-verified connector (**Adspirer Ads & Performance Marketing Agent**), 5 slash commands (setup, performance-review, write-ad-copy, wasted-spend, refresh-brand-context), 15 advertising skills, and 1 performance marketing agent. It all comes in one **Customize → Plugins → Add** step. > **The Add or Connect button is grayed out — why?** > > Two common causes: > > * **You're on a VPN.** Many corporate VPNs block the handshake to `mcp.adspirer.com`. Disconnect from the VPN and the button becomes clickable. > * **Your workspace owner hasn't allowed it.** On Claude Team or Enterprise, owners decide which directory connectors and plugins members can use. Ask your owner or IT admin to allow **Adspirer Ads & Performance Marketing Agent**. It's an Anthropic-verified directory listing, so there's no custom connector for them to review. > > Once either is resolved, the button activates and you can continue. > **Claude says "No OAuth flow is in progress"** > > This is a known **client-side** bug in the Claude desktop/Cowork app — Claude loses its sign-in session between steps and shows *"No OAuth flow is in progress."* It's an issue in Anthropic's app, not a problem with your Adspirer account or connection. > > **Fix:** go to **Customize → Connectors**, open **Adspirer Ads & Performance Marketing Agent**, and click **Connect** from there instead of from the plugin prompt. If it still fails, disconnect it, fully quit and reopen Claude, and connect again. Don't add Adspirer as a custom connector. The verified listing is the same server, and a second copy duplicates every tool. > **Can I use both Cowork and Claude Chat?** > > Yes. The Cowork plugin/connector and Claude Chat connector work independently. You can use Cowork for brand-aware workspace sessions and Chat for quick ad questions. Both connect to the same Adspirer MCP server and share one tool-call quota. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing](https://www.adspirer.com/pricing). ## Related Documentation * [Claude Chat Setup](/docs/ai-clients/claude) — for plain Claude chat connectors (no folder, no plugins) * [Claude Code Setup](/docs/ai-clients/claude-code) — Anthropic's **separate** terminal/CLI developer tool — use this if you want a command-line workflow, not the desktop app * [Agent Skills Overview](/docs/agent-skills/overview) — Teach Claude the right workflows * [Google Ads Integration](/docs/ad-platforms/google-ads) — Full Google Ads tool reference * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; upload it as a skill in Customize (\$39 one-time) # Connect Codex CLI to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/codex Connect OpenAI Codex to Adspirer MCP for autonomous ad management across Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads. AI agents that optimize daily. Autonomous ad campaign management. Your AI agent runs campaigns while you sleep. > [!NOTE] > > **Prefer a chat window?** Codex is also built into the ChatGPT desktop app. [Codex Desktop setup](/docs/ai-clients/codex-desktop) installs this same plugin with three chat messages and no terminal. ## What Makes Codex Different Most AI tools are assistants. They answer questions. They generate copy. They analyze data when you ask. Codex is autonomous. You define the goal — "check my ad performance every morning and flag anything unusual" — and the agent runs that task on a schedule. No human in the loop. It wakes up, pulls your campaign data, analyzes it, and sends you a summary. If your cost-per-acquisition spikes 40% overnight, you get an alert before you've had coffee. When you connect Codex to Adspirer, you get 400+ advertising tools that run on a schedule. It's an AI ad manager that operates 24/7. ## Prerequisites > [!NOTE] > > * [OpenAI Codex CLI](https://github.com/openai/codex) installed and working > * [git](https://git-scm.com/) installed (used by the installer) > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup **Plugin Marketplace (Recommended)** > [!NOTE] > > **Important:** The `/plugins` command below is a **slash command** — type it directly into the Codex input. Do not ask the AI to run it for you. **1. Open Codex** Launch a Codex session in your terminal: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} codex ``` **2. Add the Adspirer Marketplace** You have two options: **Option A — type this directly in the Codex prompt:** ``` codex plugin marketplace add amekala/ads-mcp ``` Codex runs the command and confirms: *"Added the marketplace adspirer-marketplace from amekala/ads-mcp."* **Option B — use the plugin browser:** type `/plugins` → navigate to the **Add Marketplace** tab → enter `amekala/ads-mcp`. **3. Find and Install Adspirer Ads Agent** Type `/plugins` to open the plugin browser. Navigate to the **Adspirer** tab using the `` keys — you'll see **Adspirer Ads Agent** listed as **Available**. Press **Enter** to open the plugin detail view. You'll see the 5 skills, MCP server (`adspirer`), and an **Install plugin** option. Select **Install plugin**. **4. Authorize with Adspirer** A browser window opens with the Adspirer OAuth 2.1 screen. Sign in to your Adspirer account and click **Authorize** to grant Codex access. Return to your terminal — you'll see *"Installed Adspirer Ads Agent plugin."* The plugin now appears as **Installed** in `/plugins`. **5. Set Up Your Brand Workspace** Open your brand folder and start a new Codex session: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ~/Clients/YourBrand codex ``` Say "set up my brand workspace". The agent connects to your ad accounts, scans for brand docs, pulls live campaign data, and creates `AGENTS.md`. If it doesn't trigger automatically, type: `$adspirer-setup` **6. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=codex)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. **Shell Installer** **1. Run the Installer** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/codex/adspirer/install.sh) ``` This installs all 5 skills, the agent config, MCP server, and multi-agent support automatically. **2. Restart Codex** Close and reopen Codex to load the new config. **3. Authenticate with Adspirer** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} codex mcp login adspirer ``` A browser window will open. Sign in with your Adspirer account and authorize access. Return to your terminal when complete. **4. Set Up Your Brand Workspace** Open your brand folder and launch Codex: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ~/Clients/YourBrand codex ``` Say "set up my brand workspace". The agent will connect to your ad accounts, scan for brand docs, pull live campaign data, and create `AGENTS.md`. If it doesn't trigger automatically, run: `$adspirer-setup` **Manual Setup** **1. Clone the Repo** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} git clone https://github.com/amekala/ads-mcp.git /tmp/ads-mcp cd /tmp/ads-mcp/plugins/codex/adspirer ``` **2. Install Skills** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p ~/.agents/skills cp -r skills/adspirer-ads ~/.agents/skills/ cp -r skills/adspirer-setup ~/.agents/skills/ cp -r skills/adspirer-performance-review ~/.agents/skills/ cp -r skills/adspirer-write-ad-copy ~/.agents/skills/ cp -r skills/adspirer-wasted-spend ~/.agents/skills/ ``` **3. Add the MCP Server** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} codex mcp add adspirer --url https://mcp.adspirer.com/mcp ``` **4. Install Agent Config** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p ~/.codex/agents cp agents/performance-marketing-agent.toml ~/.codex/agents/ ``` **5. Update config.toml** Add to `~/.codex/config.toml`: ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}} [features] multi_agent = true [agents.performance-marketing-agent] description = "Brand-specific performance marketing agent. Use for ad campaigns, performance, keywords, ad copy, budgets." config_file = "agents/performance-marketing-agent.toml" ``` **6. Restart and Authenticate** Restart Codex, then authenticate: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} codex mcp login adspirer ``` A browser window will open. Sign in and authorize access. > [!TIP] > > You're connected. Codex now has 400+ advertising tools available for autonomous and interactive use. ## Available Skills | Skill | Invocation | What it Does | | - | - | - | | **Adspirer Ads** | `$adspirer-ads` or just ask naturally | Full campaign management — 400+ tools, all workflows, all platforms | | **Setup** | `$adspirer-setup` | Bootstrap a brand workspace (first-time or refresh) | | **Performance Review** | `$adspirer-performance-review` | Cross-platform performance scorecard | | **Write Ad Copy** | `$adspirer-write-ad-copy Google Search` | Brand-voice ad copy from real data | | **Wasted Spend** | `$adspirer-wasted-spend` | Find and fix wasted ad spend | You don't need to remember skill names — just describe what you want and Codex will match the right skill automatically. ## What You Can Do 400+ tools across 6 ad platforms, available for autonomous or on-demand tasks: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research, Search & PMax campaigns, wasted spend detection, budget reallocation, search term analysis | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | B2B targeting (job titles, industries, company size), sponsored content, lead gen forms, performance analysis | | **Meta Ads** | 60 | Image/video/carousel campaigns, creative fatigue detection, audience targeting, placement optimization | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance tracking | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | ## Autonomous Workflows (The Real Use Case) Here's why people use Codex with Adspirer: ### Daily Performance Check-In **Agent YAML default\_prompt:** ``` "Pull yesterday's performance across all my ad platforms. Compare to the previous 7-day average. Flag any campaigns with CPA increases over 30% or spend increases over 50%. Send me a summary." ``` Schedule this to run every morning at 8am. You wake up to a performance summary in your inbox or Slack. No dashboards to check. ### Weekly Wasted Spend Audit **Agent YAML default\_prompt:** ``` "Audit my Google Ads account for wasted spend in the last 7 days. Find keywords with spend but zero conversions. For each keyword, recommend: pause it, add a negative keyword, or lower the bid. Total up potential monthly savings." ``` Run this every Monday. The agent finds money leaks and tells you exactly what to fix. ### Budget Rebalancing **Agent YAML default\_prompt:** ``` "Analyze performance across Google and Meta Ads for the last 30 days. I have $10,000/month total budget. Recommend how to split the budget for maximum conversions. Show me current allocation vs recommended allocation." ``` Run this monthly. The agent analyzes cross-platform ROI and recommends where to shift spend. ### Anomaly Detection **Agent YAML default\_prompt:** ``` "Check all active campaigns across Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok. Look for anomalies in the last 24 hours: - Sudden CPA spikes - Campaigns that stopped converting - Unexpected spend increases Alert me immediately if anything is found." ``` Run this every 6 hours. The agent acts as a 24/7 monitoring system. If something breaks at 3am, you get an alert. ## On-Demand Prompts (Non-Autonomous) You can also run Codex with one-off prompts instead of the default task: ### Campaign Creation ``` codex run adspirer-ads "Create a Google PMax campaign for my DTC brand: - Product: premium wireless earbuds, $129 retail price - Target ROAS: 350% - I have product images and videos ready - Write asset group headlines and descriptions - Use my Google Merchant Center feed" ``` ### LinkedIn Lead Gen ``` codex run adspirer-ads "Launch a LinkedIn campaign targeting CTOs: - Company size: 100-1,000 employees - Industries: fintech, SaaS, cybersecurity - Product: zero-trust security platform - Budget: $150/day - Goal: whitepaper downloads - Image URL: [paste URL]" ``` ### Cross-Platform Report ``` codex run adspirer-ads "Generate a Q1 2026 performance report. Pull data from Google Ads, Meta Ads, and LinkedIn Ads. Include: total spend, conversions, ROAS by platform. Format as markdown." ``` ## Safety Features (Critical for Autonomous Agents) When an AI agent runs without human oversight, safety matters. Adspirer enforces these rules: * **All campaigns created PAUSED:** Even in autonomous mode, campaigns don't launch until you manually approve them * **No budget changes without confirmation:** The agent can analyze and recommend budget changes, but it can't execute them autonomously * **Read-before-write workflows:** Skills force research and validation before any campaign creation * **Connection status checks:** Agent verifies it's managing the correct account before taking any action * **No automatic retries:** If a tool call fails, the agent reports the error instead of retrying blindly Bottom line: Autonomous doesn't mean uncontrolled. The agent analyzes, recommends, and alerts — but you make the final spending decisions. ## Troubleshooting | Problem | Solution | | - | - | | MCP server not found | Run `codex plugin marketplace add amekala/ads-mcp`, then `/plugins` to install. Or: `codex mcp add adspirer --url https://mcp.adspirer.com/mcp` | | MCP shows "Unsupported" | Run `codex mcp login adspirer` to complete OAuth authentication | | Authentication failed | Run `codex mcp login adspirer` to re-authenticate | | Install appears to hang | A browser window may have opened for OAuth — complete sign-in and return to terminal | | No ad platforms connected | Connect platforms at [adspirer.com](https://www.adspirer.com) | | Skills not showing | Verify: `ls ~/.agents/skills/` — should show `adspirer-*` directories | | No data returned | Check for active campaigns. Try longer lookback (60/90 days) | | Rate limit hit | Check Adspirer tier (Free: 15/mo, Plus: 150, Pro: 600, Max: 3,000) | ## FAQ > **Can the agent actually spend money autonomously?** > > No. All campaigns are created PAUSED, and budget changes require user confirmation. The agent can analyze, recommend, and alert — but you approve spending decisions manually. > **What's the difference between Codex and Claude Code?** > > [Claude Code](/docs/ai-clients/claude-code) is interactive — you ask it to do something, it does it. Codex is autonomous — you define a task once, and it runs on a schedule. Use Claude Code for ad-hoc analysis. Use Codex for recurring tasks like daily performance checks. > **How do I change the agent's default task?** > > Edit the `default_prompt` in `~/.codex/agents/performance-marketing-agent.toml`. Restart the agent for changes to take effect. > **Can I run multiple agents for different ad accounts?** > > Yes. Create separate agent config files with different default prompts. Each agent can specify which Adspirer account to use via the `switch_primary_account` tool. > **How much does this cost?** > > Adspirer pricing is based on tool calls. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. Autonomous agents typically use 2-5 tool calls per run. See [full pricing details](https://www.adspirer.com/pricing). ## Related Documentation * [Codex Desktop Setup](/docs/ai-clients/codex-desktop) — Same plugin inside the ChatGPT desktop app, no terminal * [Claude Code Setup Guide](/docs/ai-clients/claude-code) * [Cursor Setup Guide](/docs/ai-clients/cursor) * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; drop the skill folder into `.agents/skills/` and its agent definition into `.codex/agents/` (\$39 one-time) # Connect Codex Desktop to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/codex-desktop Install Adspirer in Codex inside the ChatGPT desktop app — three chat messages, no terminal. Manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads with 400+ tools. The ChatGPT desktop app has Codex built in. Switch to Codex, send three messages, and Adspirer is installed and signed in — no terminal, no config files. You get the same plugin as [Codex in the terminal](/docs/ai-clients/codex): 400+ ad platform tools and five advertising skills, running in a chat window. > [!NOTE] > > **Codex Desktop vs. Codex Terminal.** Same plugin, same skills, same Adspirer account. Use the desktop app if you'd rather work in a chat window. Use the [terminal setup](/docs/ai-clients/codex) if you want scheduled, autonomous runs or you already live in a CLI. ## Prerequisites > [!NOTE] > > * The **ChatGPT desktop app** for macOS, Windows, or Linux — [download it here](https://learn.chatgpt.com/docs/app#getting-started) > * A ChatGPT plan that includes Codex (Plus, Pro, Business, or Enterprise) > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) — you can also create one during the sign-in step > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup (3 Messages) **1. Install the ChatGPT desktop app** Download the app from [OpenAI's desktop app page](https://learn.chatgpt.com/docs/app#getting-started) — it covers macOS, Windows, and Linux. Open it and sign in with your ChatGPT account. Already have it? Make sure it's up to date. Codex only appears in recent versions. **2. Switch to Codex** Click the dropdown at the top left of the sidebar (it says **ChatGPT**) and choose **Codex**. The sidebar switches to Codex's — **New chat**, **Projects**, **Plugins**, and so on. Click **New chat**. Codex works inside a folder on your computer. When it asks where to work, pick or create one for your ads work — if you keep brand guidelines or media plans there, the agent reads them. ![ChatGPT desktop app with Codex selected in the top-left dropdown, showing the Codex sidebar and a new chat asking what to work on](https://mintcdn.com/adspirer/My0vMqzyp3JsH-jn/images/codex-desktop/codex-home.png?fit=max\&auto=format\&n=My0vMqzyp3JsH-jn\&q=85\&s=526c9a678d6cb3b02ecd6bfd0d0ee561) Codex selected in the top-left dropdown, ready for a new chat **3. Message 1 — add the Adspirer marketplace** Send this as a chat message. Codex runs it for you — if it asks permission to run a command, approve it. ``` codex plugin marketplace add amekala/ads-mcp ``` Codex confirms **Marketplace is registered successfully**, naming it `adspirer-marketplace` with the source `github.com/amekala/ads-mcp`. **4. Message 2 — install the plugin** ``` install plugin ``` Codex confirms **Installed and verified** — `adspirer-ads-agent@adspirer-marketplace`. ![Codex chat showing the marketplace add command confirmed as registered, then 'install plugin' confirmed as installed and verified for adspirer-ads-agent](https://mintcdn.com/adspirer/My0vMqzyp3JsH-jn/images/codex-desktop/marketplace-install.png?fit=max\&auto=format\&n=My0vMqzyp3JsH-jn\&q=85\&s=a47e1d90b26f17f8d23c792006879502) Messages 1 and 2 — marketplace registered, plugin installed **5. Message 3 — sign in to Adspirer** ``` help me oauth it ``` Your browser opens Adspirer's login page. Sign in (or create an account), click **Authorize**, and link the ad platforms you want to manage. Back in Codex you'll see **Adspirer OAuth is complete and verified**, with the endpoint `https://mcp.adspirer.com/mcp` and status `enabled`. ![Codex chat confirming Adspirer OAuth is complete and verified, with status enabled, authentication OAuth, and the mcp.adspirer.com endpoint](https://mintcdn.com/adspirer/My0vMqzyp3JsH-jn/images/codex-desktop/oauth-complete.png?fit=max\&auto=format\&n=My0vMqzyp3JsH-jn\&q=85\&s=327d4d24fe7ab8461e2b9d5689ef6185) Message 3 — OAuth complete, Adspirer enabled **6. Start a new chat and check your connections** The plugin loads in your next task, so click **New chat** and ask: ``` Check my connected ad platforms ``` You should see a table of your connected accounts with account IDs, names, and connection status. **7. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=codex-desktop)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. > [!TIP] > > You're connected. Codex in the desktop app now has Adspirer's 400+ advertising tools and five skills — the same plugin as the terminal setup. ## Optional Add-Ons Two things that make Codex noticeably more useful for ads work. Neither is required — the setup above is complete without them. ### Let Codex use your computer With **Computer use** on, Codex can work inside your other apps, not just call Adspirer's tools: open Ads Manager or Merchant Center in Chrome to check something the API doesn't expose, read a budget sheet in Excel, or drop a report into one. Codex asks before it touches an app, and you can set **Always allow** per app once you trust it. **1. Turn on Computer use** In the ChatGPT desktop app, open **Settings → Computer use** and switch on the apps you want Codex to reach: **Any App**, **Google Chrome** (it installs a browser extension — **Manage** shows whether it's in), and **Microsoft Excel**. Leave **Locked use** off unless you want tasks to keep running while your Mac is locked. ![ChatGPT desktop app Computer use settings with Any App, Google Chrome (browser extension installed), and Microsoft Excel toggled on, and Locked use off](https://mintcdn.com/adspirer/OSHz24xmGFzOssI4/images/codex-desktop/computer-use.png?fit=max\&auto=format\&n=OSHz24xmGFzOssI4\&q=85\&s=863ebe7f997f055237b20388deecbb36) Settings → Computer use — Any App, Google Chrome, and Microsoft Excel switched on On macOS the app asks for **Screen Recording** and **Accessibility** permissions the first time — grant both, or Computer use can't see or click anything. Available on macOS and Windows. **2. Turn on Computer history (macOS)** Open **Settings → Integrations → Computer history** and click **Turn on**. Codex turns your recent activity into memories it can use, so "pick up where I left off on the Q4 budget" means something. Use **Permissions → Choose** to keep apps and sites you'd rather not share — your bank, your inbox — out of it. ![ChatGPT desktop app Computer history settings, toggled on, with a Pause button and a Permissions row with a Choose button](https://mintcdn.com/adspirer/OSHz24xmGFzOssI4/images/codex-desktop/computer-history.png?fit=max\&auto=format\&n=OSHz24xmGFzOssI4\&q=85\&s=9dbda167fa356a51e0b0c607f4beff3b) Settings → Computer history, with Permissions for including or excluding apps and websites It needs Memories turned on, it's off by default, and on Business and Enterprise plans an admin has to allow it before you'll see the switch. > [!WARNING] > > Adspirer's safety rails — campaigns created paused, budget changes confirmed first — apply to its tools, not to clicks Codex makes in a browser. When a task touches an ad platform's web UI, leave Chrome on ask-each-time rather than **Always allow**, and let the Adspirer plugin do the writes. ### Install your Expert Kit The [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) generates an **Expert Kit** from one of your ad accounts: an agent with account-specific instructions, a skill, a prompt book graded Beginner → Expert, and reference files on the account and on working with Adspirer. It's a paid add-on (included on annual plans) — pricing and what's inside are on that page. On Codex Desktop you don't copy files anywhere: you hand the folder to Codex. **1. Download the kit** Go to [adspirer.ai/expert-space](https://adspirer.ai/expert-space), open the kit for the account, and click **Download kit (.zip)**. Unzip it — you get one folder, named like `google-ads-expert-/`, containing: ``` AGENTS.md PROMPTBOOK.md README.md SKILL.md agents/google-ads-expert-.md agents/google-ads-expert-.toml references/account-profile.md references/working-with-adspirer.md ``` **2. Hand it to Codex** In a Codex chat inside your ads project folder, attach the unzipped folder (click **+** in the composer, or drag the folder in) and send: ``` Install this kit's contents and instructions for this project ``` Codex installs the kit into the project: the skill goes where Codex loads skills from, the agent definition registers your account's expert, and every file is checked against the download. It keeps `AGENTS.md` inside the skill rather than at the project root, so it doesn't override instructions you already have. Your Adspirer sign-in is untouched. **3. Start a new task with the expert** Codex ends with a link to the new agent — click it, or start a **New chat** and ask for the expert by name. From here the agent knows your account's structure, spend history, and operating doctrine. Open `PROMPTBOOK.md` for prompts written against your real campaigns. ## Desktop or Terminal? | | **Codex Desktop** | **Codex Terminal** | | - | - | - | | Setup | Three chat messages | One command, then `/plugins` | | Where you work | A chat window in the ChatGPT desktop app | Your terminal | | Best for | Day-to-day analysis, ad copy, campaign builds | Scheduled and autonomous runs, agent configs | | Plugin | `adspirer-ads-agent` — same tools, same skills | `adspirer-ads-agent` — same tools, same skills | Both connect to the same Adspirer account, so you can install in both and switch freely. The [Codex Terminal guide](/docs/ai-clients/codex) covers scheduled runs, agent configuration, and the manual install. ## What You Can Do 400+ tools across 6 ad platforms: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research, Search & PMax campaigns, wasted spend detection, budget reallocation, search term analysis | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | B2B targeting (job titles, industries, company size), sponsored content, lead gen forms, performance analysis | | **Meta Ads** | 60 | Image/video/carousel campaigns, creative fatigue detection, audience targeting, placement optimization | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance tracking | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | The plugin also brings five skills — campaign management, brand workspace setup, performance review, ad copy, and wasted spend. You don't need to name them; describe what you want and Codex picks the right one. The [skill reference](/docs/ai-clients/codex#available-skills) is on the terminal page. ## Example Prompts ### First Look at Your Accounts Connection check plus a performance summary — sets up the brand workspace if this is a fresh folder. Check connected ad platforms and summarize recent campaign performance for this brand. If this is a new workspace, set it up first. ### Find Wasted Spend Cross-platform wasted spend audit with a prioritized fix list. Find wasted ad spend across all my active campaigns and give me a prioritized list of fixes. ### Write Ad Copy in Your Brand Voice Headlines and descriptions from real campaign data and your brand docs. Write 3 Google Ads headlines and 2 descriptions for my top campaign using my brand voice. ### Create a Campaign Google Search campaign with keyword research and intent grouping. Created paused. Create a Google Ads search campaign for my SaaS product: * Product: project management tool for remote teams * Budget: \$60/day * Research keywords first, then group by intent ## Troubleshooting | Problem | Solution | | - | - | | ChatGPT explains the command instead of running it | You're in ChatGPT, not Codex. Switch with the top-left dropdown and send it again in a Codex chat. | | Codex asks for permission to run a command | Approve it. The marketplace and install steps run `codex` commands on your machine. | | No browser window opened for sign-in | Send `help me oauth it` again, or ask Codex to run `codex mcp login adspirer`. | | Plugin installed but Adspirer tools don't respond | Click **New chat**. The plugin loads in the next task, not the one where you installed it. | | "No ad platforms connected" | Connect them at [adspirer.ai/connections](https://adspirer.ai/connections), then ask again. | | Marketplace add fails with a git error | The plugin is fetched from GitHub. On macOS, accept the prompt to install command line developer tools, then resend the message. | ## FAQ > **Do I need to install the Codex CLI separately?** > > No. Codex is built into the ChatGPT desktop app. The three messages above are all the setup there is — Codex runs the underlying commands for you. > **Is this the same plugin as the terminal install?** > > Yes. Both install `adspirer-ads-agent` from the Adspirer marketplace: the same 400+ tools, the same five skills, the same brand-workspace behavior. If you later want scheduled, autonomous runs, follow the [Codex Terminal guide](/docs/ai-clients/codex) — your Adspirer sign-in carries over. > **Can I also use the Adspirer app in ChatGPT itself?** > > Yes. The [ChatGPT plugin](/docs/ai-clients/chatgpt) and Codex Desktop use the same Adspirer account and the same tool-call quota. Use ChatGPT for quick questions and interactive dashboards; use Codex when you want the agent to work through a multi-step task in your folder. > **What does Codex do with the folder I pick?** > > It treats the folder as your brand workspace. On first use the plugin scans it for brand docs — guidelines, media plans, briefs — pulls live campaign data, and writes an `AGENTS.md` with what it learned, so later chats start with context. An empty folder works too; the agent builds the workspace from your ad accounts. > **Can the agent spend money on its own?** > > No. Every campaign is created **paused**, and budget changes need your confirmation. The agent analyzes, recommends, and drafts — you approve spend. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing](https://www.adspirer.com/pricing). ## Related Documentation * [Codex Terminal Setup](/docs/ai-clients/codex) — CLI install, scheduled runs, and agent configuration * [Codex Agent](/docs/agent-skills/codex-agent) — How the Adspirer marketing agent works inside Codex * [ChatGPT Setup](/docs/ai-clients/chatgpt) — The Adspirer app in ChatGPT * [Google Ads Integration](/docs/ad-platforms/google-ads) — Full Google Ads tool reference * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account (\$39 one-time) # Connect Cursor to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/cursor Adspirer is a Verified by Cursor plugin on the Cursor Marketplace. Search for it in Cursor, click Add, and manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads from your editor — 400+ tools, 14 skills, and a marketing subagent. > [!NOTE] > > **Adspirer is Verified by Cursor.** It's listed on the [Cursor Marketplace](https://cursor.com/marketplace/adspirer), created by Adspirer and reviewed by Cursor. Search for **adspirer** in Cursor and add it, or type `/add-plugin adspirer` in chat. That's one install with no config file, no MCP URL, and no API key. ![Adspirer plugin page on the Cursor Marketplace showing Created by Adspirer, Verified by Cursor, the Sign In To Add button, the /add-plugin adspirer command, 1 subagent, and 14 skills](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/cursor/marketplace-verified.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=aab6c35249abb0173ae48ee114668fb1) Adspirer on the Cursor Marketplace: Created by Adspirer, Verified by Cursor On cursor.com the button reads **Sign In To Add** until you sign in, and then **Add to Cursor**. ## Setup **Install from Customize (Recommended)** **1. Open Customize** In Cursor, open **Customize** in the sidebar. This is where every plugin, MCP server, rule, and skill is managed. You need Cursor v2.4+ (for subagent support) and an Adspirer account — [free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup), no card. **2. Search for Adspirer** Search for **adspirer**, or click **Browse Marketplace** to see the full catalog. Pick **Adspirer**, created by Adspirer and marked **Verified by Cursor**. ![Cursor Customize page with a marketplace search returning the Adspirer plugin, next to the Browse Marketplace button](https://mintcdn.com/adspirer/xQY-jlSRqCTgZmaL/images/cursor/customize-search.png?fit=max\&auto=format\&n=xQY-jlSRqCTgZmaL\&q=85\&s=4e3e5f20c8b8b3174100f34fc60c4fdc) Customize — search the marketplace without leaving Cursor **3. Install it** Select **Install** and choose a scope: * **User** — Adspirer is available in every Cursor project. Pick this if you manage ads regularly. * **Project** — Adspirer is available only in this folder. Pick this when you're working in one client's workspace. **4. Sign in to Adspirer** The first tool call opens Adspirer's sign-in page in your browser. Sign in, authorize access, and return to Cursor. Authentication is OAuth — there is no API key or client secret to paste anywhere. Then connect the ad accounts you want to manage at [adspirer.com/connections](https://www.adspirer.com/connections). **5. Set up your brand workspace** Open your brand folder in Cursor, switch to **Agent mode** (not Ask or Edit), and say: ``` set up my brand workspace ``` The agent checks your connected accounts, scans the folder for brand docs, pulls a live performance snapshot, and proposes a `BRAND.md`. It asks before writing any file. If it doesn't trigger on its own, run `/adspirer-setup`. **6. Try it now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=cursor)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. **Install from chat** **1. Run the add-plugin command** Needs Cursor v2.4+ and an Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)). In any Cursor chat, type: ``` /add-plugin adspirer ``` Cursor installs the plugin and everything in it — subagent, skills, rules, and the MCP server. **2. Sign in to Adspirer** The first tool call opens Adspirer's sign-in page in your browser. Sign in, authorize, and return to Cursor. Then connect your ad accounts at [adspirer.com/connections](https://www.adspirer.com/connections). **3. Set up your brand workspace** In **Agent mode**, in your brand folder, say `set up my brand workspace` — or run `/adspirer-setup`. > [!TIP] > > You're connected. Ask "which ad accounts am I connected to?" — if the agent answers with your real accounts, everything is wired up. ## What Gets Installed One install brings in four things. You don't copy files, clone a repo, or edit `mcp.json`. | Component | Count | What it does | | - | - | - | | **MCP server** | 1 | `adspirer` — 400+ advertising tools over OAuth | | **Subagent** | 1 | `performance-marketing-agent` — runs ad work in its own context with brand awareness | | **Skills** | 14 | One per platform and per workflow, loaded when the task matches | | **Rules** | 2 | Auto-load brand context and enforce the safety workflow | ![Cursor Marketplace listing for Adspirer showing 1 subagent, 14 skills, 2 rules, and 1 MCP server](https://mintcdn.com/adspirer/ktXbAHkqPipEy1iB/images/cursor/plugin-contents.png?fit=max\&auto=format\&n=ktXbAHkqPipEy1iB\&q=85\&s=ab886f0d17f74a6fd7a44234a179cf86) Everything the Adspirer plugin installs, as listed on the marketplace ## The 14 Skills Skills appear under **Agent Decides** in Customize. Cursor matches them automatically from what you ask — you only need the `/` command when you want to force one. | Skill | Command | What it covers | | - | - | - | | **Agent** | `/adspirer-agent` | Overall agent behavior and safety rules; routes to the right skill below | | **MCP contract** | `/adspirer-mcp` | How to call the Adspirer hub correctly — account IDs, quota, budget units | | **Setup** | `/adspirer-setup` | Bootstrap a brand workspace and create `BRAND.md` | | **Launch** | `/adspirer-launch` | Plan and launch a campaign, or split a budget across channels | | **Optimize** | `/adspirer-optimize` | Wasted spend, negative keywords, budget pacing, reallocation | | **Performance review** | `/adspirer-performance-review` | Cross-platform scorecard, CPA/ROAS/CTR trends, tracking audit. Read-only | | **Creative** | `/adspirer-creative` | Headlines, descriptions, primary text, creative fatigue fixes | | **Google Ads** | `/adspirer-google-ads` | Search, PMax, Demand Gen, YouTube, Display, keywords, extensions | | **Meta Ads** | `/adspirer-meta-ads` | Facebook and Instagram campaigns, ad sets, audiences, pixels | | **Amazon Ads** | `/adspirer-amazon-ads` | Sponsored Products, Brands, Display, ASIN targeting, ACoS | | **LinkedIn Ads** | `/adspirer-linkedin-ads` | Sponsored content, lead-gen forms, B2B targeting | | **TikTok Ads** | `/adspirer-tiktok-ads` | In-feed video, Spark Ads, carousel, app promotion | | **ChatGPT Ads** | `/adspirer-chatgpt-ads` | Chat-card ads inside ChatGPT responses | | **Docs** | `/adspirer-docs` | Answers about Adspirer itself — pricing, quota, what's supported | Each platform skill carries the traps that cause most failures on that platform: TikTok's pixel-placement rule, Meta's required Facebook page ID, LinkedIn's mandatory campaign group, Google's asset-bundle expiry. ## Also Works in Grok Bot The same marketplace listing installs into [Grok Bot](/docs/ai-clients/grok), where your bot runs the work in the cloud and can put it on a schedule. Install it once per product — a Cursor install doesn't carry over. ## What You Can Do 400+ tools across 6 ad platforms, from Cursor's chat or inline editing: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research, Search & PMax campaigns, wasted spend analysis, budget optimization, search term reports, ad extensions | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | Sponsored content, B2B targeting (job titles, industries, company size), lead gen forms, creative analysis | | **Meta Ads** | 60 | Image/video/carousel ads, audience targeting, placement optimization, creative fatigue detection | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance tracking | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | Plus 8 automation tools for scheduling, monitoring, and cross-platform reporting. ## Example Prompts What to actually say to Cursor once you're connected: ### Google Search Campaign Google Search campaign for B2B with negative keyword suggestions. Create a Google Search campaign for my B2B software: * Product: cloud-based inventory management for restaurants * Target: restaurant owners and ops managers * Budget: \$75/day * Research keywords with real CPC data first * Suggest negative keywords to avoid irrelevant clicks ### Google PMax Campaign PMax campaign for online courses with conversion tracking. Build a Performance Max campaign for my online course: * Product: "Advanced Python for Data Science" course, \$199 * Target ROAS: 300% * I have these image assets: \[paste URLs] * Write headlines and descriptions optimized for conversions * Set up conversion tracking for purchases ### Meta Ads Creative Testing Meta carousel campaign with per-card creative copy. Set up a Meta carousel campaign for my furniture store: * Products: 4 best-selling sofas ($800-$2,000 range) * Target: homeowners aged 28-45, interests in interior design and home decor * Budget: \$50/day * Image URLs: \[paste 4 URLs] * Write unique copy for each carousel card * Optimize for purchases ### LinkedIn B2B Lead Gen LinkedIn campaign targeting C-suite finance leaders. Create a LinkedIn campaign targeting CFOs and Finance Directors: * Company size: 200-5,000 employees * Industries: manufacturing, logistics, retail * Product: AP automation software * Budget: \$120/day * Goal: demo request sign-ups * Use this image: \[paste URL] ### Cross-Platform Performance Report Multi-platform performance report with budget recommendations. Pull performance data from all my connected platforms for the last 30 days. Create a markdown report with: * Executive summary with key metrics per platform * Top 3 campaigns by ROAS across all platforms * Wasted spend analysis (Google: zero-conversion keywords, Meta: fatigued creatives) * Budget reallocation recommendations for next month ## How the Rules Change Your Workflow The plugin ships two rules that run automatically. You can see them under **Rules** in Customize and toggle each between **Always**, **Agent Decides**, and **Manual**. **`brand-workspace`** loads context before the agent answers: `BRAND.md` for voice, audiences, budgets and KPI targets, `STRATEGY.md` for binding directives, and past decisions from memory. **`use-adspirer`** enforces the order of operations. Here's the difference it makes: **Without the rule** — you say *"Create a Google Ads campaign for running shoes"* and the agent calls `create_search_campaign` with generic parameters. It fails: no keyword research, no validated assets. **With the rule** — the same sentence triggers the full workflow: 1. `get_connections_status` — verify you're managing the right account 2. `research_keywords` on "running shoes" seeds, with real CPC data 3. Shows you the keyword and CPC data before going further 4. `discover_existing_assets` — reuse images and headlines you already have 5. `validate_and_prepare_assets` — check them against Google's requirements 6. `create_search_campaign` with validated data 7. **Asks for your confirmation** before anything is created One vague prompt becomes a complete, validated workflow. Nothing launches without your approval. ## Safety * **Campaigns are created paused.** Review before they spend. * **Spend-affecting writes need your approval.** Campaign creation, budget changes, and bid changes all stop for confirmation. * **Read before write.** Connection check, then research, then validate, then create. * **Results are read back.** The agent re-reads what it created before reporting success. * **Campaigns are never deleted automatically.** * **No credentials in the plugin.** OAuth 2.1 with PKCE; your ad platform credentials stay server-side with Adspirer. The marketplace build ships no hooks, executables, or bundled server code, and talks only to `https://mcp.adspirer.com/mcp`. ## Troubleshooting | Problem | Solution | | - | - | | Can't find Adspirer in Customize | Search `adspirer` (lowercase, one word). Update Cursor if the Marketplace section is missing. | | "Disabled by team admin" | Your Cursor team admin controls which marketplace plugins are available. Ask them to enable Adspirer. | | Tools don't appear after install | Check **Customize → MCP** and make sure `adspirer` is toggled on. A disabled server doesn't load. | | Sign-in window doesn't open | Check your browser's pop-up blocker, then restart Cursor. | | Authentication failed | Toggle the `adspirer` MCP server off and on in Customize to re-run OAuth. | | No ad platforms connected | Connect them at [adspirer.com/connections](https://www.adspirer.com/connections). | | Skills not matching | Confirm they're listed under **Agent Decides** in Customize. Force one with `/adspirer-setup` or `/adspirer-performance-review`. | | Subagent not triggering | You must be in **Agent mode** — not Ask or Edit. | | No data returned | Check that the account has active campaigns, then try a longer lookback (60 or 90 days). | | Rate limit hit | See [pricing](/docs/knowledge-base/pricing) for your plan's tool call allowance. | ## FAQ > **Should I install at user scope or project scope?** > > **User scope** makes Adspirer available in every Cursor project. Pick this if you manage ads regularly. > > **Project scope** limits it to one folder. Pick this when you're in a client's codebase and want ad tools only there, or when you keep a separate folder per brand. > **Do I need to add Adspirer as an MCP server or edit mcp.json?** > > No. Adspirer is a **Verified by Cursor** marketplace plugin, and installing it adds the `adspirer` MCP server for you, along with the subagent, skills, and rules. If you added `https://mcp.adspirer.com/mcp` to `mcp.json` or under **Customize → MCP** before the plugin existed, remove that entry so Cursor doesn't load two copies of every tool. > **What happened to the install script?** > > It's retired. The `bash <(curl ...)` installer predates the Cursor Marketplace — it copied skills, rules, and an agent into `~/.cursor/` by hand. The marketplace install does the same thing in one click, updates itself, and is reviewed by Cursor before each release. If you ran the old script, uninstall the copied files from `~/.cursor/skills/`, `~/.cursor/agents/`, and `~/.cursor/rules/` so they don't duplicate the plugin's. > **Can I use Adspirer with Cursor Composer?** > > Yes. Composer has full access to Adspirer tools. You can ask it to analyze campaigns, generate a report, and save the output as markdown in your project — all in one flow. > **Where does the plugin keep brand context?** > > `BRAND.md` and `STRATEGY.md` live in your project root, so they're yours to read and edit. Past decisions go in `.cursor/memory/performance-marketing-agent/MEMORY.md`. > > If you already have a `BRAND.md` that isn't an Adspirer workspace, the agent leaves it alone and says so. > **How much does Adspirer cost?** > > Pricing is based on tool calls, not ad spend, and it's the same across every AI client. See [pricing and plans](/docs/knowledge-base/pricing). > **Can I manage multiple ad accounts?** > > Yes. Connect multiple Google Ads accounts, multiple Meta Business Managers, and so on. Use `switch_primary_account` to change which one you're managing, or name the account ID in your prompt. See [multi-account](/docs/knowledge-base/multi-account). ## Related Documentation * [Grok Bot Setup](/docs/ai-clients/grok) — the same plugin, running in the cloud * [Cursor Agent](/docs/agent-skills/cursor-agent) — how the subagent, skills, and rules fit together * [Claude Code Setup Guide](/docs/ai-clients/claude-code) * [Google Ads Integration Guide](/docs/ad-platforms/google-ads) * [Pricing & Plans](/docs/knowledge-base/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account (\$39 one-time) # Connect Gemini CLI to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/gemini-cli Connect Gemini CLI to Adspirer MCP in 2 minutes. Manage Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads from your terminal with 400+ tools. Manage all your ad campaigns from the terminal using Google's Gemini CLI. One command to install, 400+ tools to use. ## Prerequisites > [!NOTE] > > * Gemini CLI installed: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > npm install -g @google/gemini-cli > ``` > > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup **1. Install the Adspirer Extension** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} gemini extensions install https://github.com/amekala/ads-mcp ``` This installs the Adspirer MCP server, 5 slash commands, and the ad campaign management skill. **2. Authenticate with Adspirer** Run Gemini CLI and ask it anything about your ad accounts: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} gemini ``` ``` Check my connected ad platforms ``` Your browser opens automatically for OAuth sign-in. Sign in with your Adspirer account and authorize access. Return to Gemini CLI — you're connected. **3. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=gemini-cli)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. ### Verify Your Setup Run a test prompt: ``` Check my connected ad platforms ``` You should see a table showing your connected accounts across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads — along with account IDs, names, and connection status. > [!TIP] > > You're connected. Gemini CLI now has access to 400+ advertising tools from your terminal. ## Slash Commands The extension includes 5 slash commands that trigger proven workflows: | Command | What it Does | | - | - | | `/adspirer:setup` | Bootstrap a brand workspace — connect accounts, scan docs, pull data | | `/adspirer:performance-review` | Cross-platform performance scorecard with KPI comparison | | `/adspirer:write-ad-copy` | Brand-voice ad copy from real keyword and performance data | | `/adspirer:wasted-spend` | Find and fix wasted spend across all platforms | | `/adspirer:refresh` | Re-scan docs and update context with latest data | You don't need to remember these — just describe what you want and Gemini will use the right workflow. ## What You Can Do 400+ tools across 6 ad platforms. Here's what matters: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, wasted spend analysis, budget optimization, ad extensions, asset management | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | Sponsored content, lead gen forms, B2B targeting (job titles, industries, seniority), creative performance analysis | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection, placement optimization | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance analysis | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | Plus 8 automation tools: scheduled briefs, performance monitors, cross-platform reports. ## Example Prompts What to actually say once you're set up: ### Google Search Campaign Google Search campaign with keyword research grouped by intent. Create a Google Ads search campaign for my SaaS product: * Product: project management tool for remote teams * Target: team leads and ops managers at companies with 20-200 employees * Budget: \$60/day * Research keywords with real CPC data first * Group keywords by intent (branded, competitor, feature-based) ### Google PMax Campaign Performance Max campaign across all Google channels. Set up a Performance Max campaign for my e-commerce store: * Product: organic dog treats, \$24.99 avg order value * Target ROAS: 400% * I have product images at these URLs: \[paste URLs] * Write 5 headlines and 3 descriptions * Use my existing Google Merchant Center feed ### Cross-Platform Audit Multi-platform audit with prioritized action list and savings estimate. Audit all my ad accounts for the last 30 days: * Google: find wasted spend (keywords with clicks but zero conversions) * Meta: check for creative fatigue (frequency > 3, declining CTR) * LinkedIn: compare CPA across audience segments Give me a prioritized action list with estimated monthly savings. ## Safety Features Adspirer enforces safety rules to prevent accidental spend: * **All campaigns created PAUSED:** You review before they go live * **User confirmation required:** Gemini asks before any action that affects spend * **Read-before-write:** Research and validation before campaign creation * **Connection status checks:** Always verifies you're managing the right account first * **No automatic retries:** If a campaign creation fails, Gemini won't retry without asking ## Troubleshooting ### Extension not installing Make sure you have the latest Gemini CLI: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm update -g @google/gemini-cli ``` Then retry the install: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} gemini extensions install https://github.com/amekala/ads-mcp ``` ### Authentication not working The OAuth flow opens your default browser automatically. If it doesn't: * Check your default browser settings * Try clearing browser cache or using a different browser * Disable ad blockers temporarily — some interfere with OAuth redirects ### Tools not working after connecting Check your Adspirer account status at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account). Free accounts get 15 tool calls/month. If you've hit the limit, upgrade to Plus ($49/mo for 150 calls) or Pro ($99/mo for 600 calls). ### Slash commands not recognized Make sure the extension installed successfully: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} gemini extensions list ``` You should see `ads-mcp` in the list. If not, reinstall the extension. ## FAQ > **What is Gemini CLI?** > > Gemini CLI is Google's official command-line AI tool, powered by the Gemini model. It lets you query codebases, generate apps, and automate workflows from your terminal. Install it with `npm install -g @google/gemini-cli`. > **How is this different from Claude Code?** > > Both are terminal-based AI tools that connect to Adspirer via MCP. Gemini CLI is powered by Google's Gemini model. Claude Code is powered by Anthropic's Claude model. Both have full access to the same 400+ advertising tools. Choose whichever AI model you prefer. > **Do I need a Google Cloud account?** > > No. Gemini CLI is free to use. You only need an Adspirer account to connect to your ad platforms. > **Can I use both Gemini CLI and Claude Code?** > > Yes. Your Adspirer account works with every supported AI client. All clients share the same tool call quota. See [Multi-Client](/docs/knowledge-base/multi-client) for details. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See the [full pricing breakdown](https://www.adspirer.com/pricing). > **Is my data safe?** > > Yes. Adspirer uses OAuth 2.1 with PKCE — we never see your passwords. Your ad account credentials live with Google/Meta/LinkedIn/TikTok. We only get read/write permissions you explicitly authorize. You can revoke access anytime from your ad platform's security settings. ## Related Documentation * [Google Ads Integration Guide](/docs/ad-platforms/google-ads) * [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/?name=amekalaads-mcp) * [Pricing & Plans](https://www.adspirer.com/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; drop the skill folder in and it ships its own agent definition (\$39 one-time) # Connect Grok Bot to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/grok Add the official Adspirer for Grok Bot plugin — Verified by Cursor — and give your bot live access to Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads. 400+ tools, cloud-scheduled reports, approval before any spend. > [!NOTE] > > **Adspirer for Grok Bot is an official plugin listing.** Open [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) and click **Add to Grok Bot**, or search **adspirer** in Grok Bot's **Marketplace**. It's published by Adspirer on the Cursor Marketplace and marked **Verified by Cursor**, so there's no MCP URL to paste and no custom connector to set up. **Grok Bot** runs your work in the cloud with bots, on a schedule if you want. With Adspirer added, a bot can read and act on your live ad accounts. ![Adspirer for Grok Bot listing on x.ai, by Adspirer, published on the Cursor Marketplace, with a button to open or download Grok Bot](https://mintcdn.com/adspirer/PuyhsbFPuRU-UDud/images/grok/official-listing.png?fit=max\&auto=format\&n=PuyhsbFPuRU-UDud\&q=85\&s=703f02735b95ece67599dcdb8858b4fa) The official Adspirer for Grok Bot listing on x.ai ![Adspirer plugin detail in Grok Bot showing Accounts with default Connected, Tools 23 of 23 enabled, Apps with the adspirer connector, and Skills 14](https://mintcdn.com/adspirer/xQY-jlSRqCTgZmaL/images/grok/plugin-detail.png?fit=max\&auto=format\&n=xQY-jlSRqCTgZmaL\&q=85\&s=f82aea07bd773e14f07adbd904567ce5) Adspirer installed in Grok Bot — the connected account, the tools the bot can call, and all 14 skills ## Setup **1. Create a bot for paid media** Sign in to Grok Bot with your Cursor account. You also need an Adspirer account — [free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup), no card. Choose **Create your own** and give the bot a short name, one title, and a description of the work it does. Keep one bot per job — a bot that does ads and nothing else gives better answers than a general one. Paste this as the description and edit the specifics: ``` Title: Paid media manager Manage paid media across Google Ads, Meta Ads, Amazon Ads, LinkedIn Ads, TikTok Ads, and ChatGPT Ads through the Adspirer plugin. Always pull live data before answering a performance question — never answer from memory. Before creating or changing anything: check which accounts are connected, research first, and show me the data you based the recommendation on. Create every campaign paused. Ask me before anything that changes spend — new campaigns, budget changes, bid changes. Never delete a campaign. Our brand: [brand name, what you sell, who you sell to] Voice: [tone, words to avoid] Guardrails: [monthly budget ceiling, target CPA or ROAS] ``` **2. Open the Marketplace** Select **Marketplace** at the bottom of the sidebar, or follow a **Connect** card in chat. On the mobile app, tap your avatar in the top left. ![Grok Bot window with the Marketplace button at the bottom of the left sidebar](https://mintcdn.com/adspirer/xQY-jlSRqCTgZmaL/images/grok/marketplace-sidebar.png?fit=max\&auto=format\&n=xQY-jlSRqCTgZmaL\&q=85\&s=ca0f791742e5870a8bfb7887dc5ff574) Marketplace sits at the bottom of the Grok Bot sidebar, under your bots **3. Add Adspirer** Search for **adspirer** and add it. Or open the [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) page and click **Add to Grok Bot**. If Grok Bot isn't installed on this computer, the page offers **Download for macOS** first. It's the same [marketplace listing](https://cursor.com/marketplace/adspirer) that Cursor installs from, **Verified by Cursor**. **4. Authorize** When Grok Bot asks you to **Authorize**, finish the Adspirer sign-in in your browser. If it shows **Waiting for authorization**, use **Reopen** to bring the browser tab back. Confirm Adspirer appears under **Installed**. **5. Connect your ad accounts** Connect the platforms you want the bot to manage at [adspirer.com/connections](https://www.adspirer.com/connections). The bot can only reach accounts you've connected there. **6. Ask it something read-only first** Safe first task — confirms the connection without changing anything. Which ad accounts am I connected to, and what did each one spend in the last 30 days? > [!TIP] > > If the bot answers with your real account names and real spend figures, you're connected. ## What You'll See After Installing Open Adspirer from the Marketplace once it's installed and you get the whole surface on one screen — the shot at the top of this page. Four sections: | Section | What it means | | - | - | | **Accounts** | Your connected Adspirer account. **+ Add Another Account** connects a second one — useful if you keep client work on separate Adspirer logins. | | **Tools** | The tools the bot may call. Adspirer's connector is a hub: the handful listed here reach the 400+ operations behind them, so "23 of 23 enabled" is the healthy state, not a partial install. | | **Apps** | The `adspirer` connector itself — the MCP link to your ad accounts. | | **Skills** | All 14 come across from the marketplace, same as in Cursor. The bot loads the right one from what you ask. | > [!NOTE] > > Connecting an Adspirer account here is not the same as connecting your ad platforms. Those live at [adspirer.com/connections](https://www.adspirer.com/connections) — see [managing multiple accounts](/docs/knowledge-base/multi-account). ## What Your Bot Can Do 400+ tools across 6 ad platforms: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research, Search & PMax campaigns, wasted spend analysis, budget optimization, search term reports, ad extensions | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | Sponsored content, B2B targeting (job titles, industries, company size), lead gen forms, creative analysis | | **Meta Ads** | 60 | Image/video/carousel ads, audience targeting, placement optimization, creative fatigue detection | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance tracking | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | ## Example Prompts ### Monday Morning Scorecard Cross-platform performance review with the three things to fix. Pull last week's performance from every connected platform. Give me one table with spend, conversions, CPA, and ROAS per platform, flag anything that moved more than 20% week over week, and end with the top 3 actions you'd take. ### Find Wasted Spend Cross-platform waste audit with a savings estimate. Find wasted spend across all my platforms. Show me keywords with spend and zero conversions, Meta ads with rising frequency and falling CTR, and how much I'd save per month by cutting them. Don't change anything yet — just show me the list. ### Rewrite Underperforming Ad Copy New headlines grounded in real search terms. Find my lowest-CTR Google Search ad group, pull the search terms that actually converted in it over the last 60 days, and write 8 new headlines and 3 descriptions based on them. Keep to Google's character limits and my brand voice. ### Audit Before You Launch Conversion tracking check before spending on a new campaign. Before I launch anything new, audit my conversion tracking on Google and Meta. Tell me which conversion actions are firing, which ones haven't recorded a conversion in 30 days, and what you'd fix first. ### Plan a New Channel Budget split across channels for a defined goal. I have \$6,000/month to spend on demand gen for a B2B SaaS product selling to IT directors. Based on what my existing campaigns already tell us about cost and intent, recommend how to split that across Google Search, LinkedIn, and Meta. Then build the LinkedIn campaign paused so I can review it. ## Scheduled Reports With Routines A routine tells one bot when to run a workflow — and it runs in the cloud, so your laptop can be closed. This is the reason to put ad reporting in Grok Bot rather than only in your editor. **1. Open the routine panel** Open the bot, choose **View conversation details**, then **Routines**. **2. Write the instruction** Give the routine a name and the instruction you want run on a schedule: ``` Pull last week's performance from every connected Adspirer platform. Post a scorecard: spend, conversions, CPA, ROAS per platform, week over week. List anything that moved more than 20%. End with the top 3 actions. Read-only — do not change any campaign. ``` **3. Set when it runs** Open **When to run** and pick a schedule — **Every day**, **Weekdays**, **Every week**, **Every month**, or an interval. The clock time follows the **Timezone** in the bot's settings, not your browser's. **4. Turn Active on** An inactive routine stays saved and never fires. Saving doesn't run it either — the first run is the next matching time. > [!WARNING] > > Every run spends Adspirer tool calls and Grok Bot usage. A weekly scorecard is cheap; an hourly one is not. Start weekly, check the run history, and widen or narrow from there. See [pricing](/docs/knowledge-base/pricing) for your tool call allowance. Adspirer also has its own scheduling tools, which deliver briefs independently of any client. See [scheduled tasks](/docs/guides/scheduled-tasks) for when to use which. ## Safety * **Campaigns are created paused.** Nothing spends until you enable it. * **Read each approval card.** Grok Bot shows one before a tool takes action. Use **Allow once** while you learn how the bot handles a workflow, and **Deny** when the proposed action isn't what you asked for. * **Spend-affecting writes stop for confirmation** — campaign creation, budget changes, bid changes. * **Campaigns are never deleted automatically.** * **Never paste credentials into chat.** Adspirer uses OAuth, so it never asks for one. Your ad platform credentials stay server-side with Adspirer and are scoped to the accounts you connect. ## Grok Bot vs. Cursor Same plugin, same marketplace listing, two different products. Installing in one does not install in the other. | | **Grok Bot** | **[Cursor](/docs/ai-clients/cursor)** | | - | - | - | | **Where it runs** | Cloud — desktop, web, mobile | Your machine, inside the editor | | **Install from** | **Marketplace** in the sidebar | **Customize** in the sidebar | | **Scheduling** | Routines, run in the cloud | Adspirer's own scheduling tools | | **Brand context** | The bot's description | `BRAND.md` and `STRATEGY.md` in your project folder | | **Skills** | All 14 | All 14 | | **Workflow enforcement** | What you write in the description | Two rules that load automatically | | **Best for** | Recurring reporting and optimization you want to arrive on its own | Hands-on campaign building alongside your files | > [!NOTE] > > All 14 skills install in Grok Bot. What doesn't come across is the subagent and the two `.mdc` rules — those are Cursor plugin components. In Grok Bot the bot's description does that job, which is why the setup step above is worth filling in properly rather than leaving generic. ## Troubleshooting | Problem | Solution | | - | - | | Adspirer isn't in the plugin list | Search `adspirer` (lowercase, one word) in **Marketplace**. | | "Disabled by team admin" | If you use Grok Bot through a Cursor team, your Cursor team admin controls which marketplace plugins are available. Ask them to enable Adspirer. | | Stuck on "Waiting for authorization" | Use **Reopen** to bring the browser tab back and finish signing in. | | Plugin added but no ad data | Connect your platforms at [adspirer.com/connections](https://www.adspirer.com/connections) — installing the plugin doesn't connect accounts. | | Bot answers from memory instead of live data | Add "always pull live data before answering a performance question" to the bot's description. | | Routine saved but **Run history** says "No runs yet" | Saving doesn't create a run. Check **Active** is on and wait for the next matching time, or use **Test run** — which does real work, so give it a read-only instruction. | | Wrong time on a scheduled report | Schedules follow the **Timezone** in the bot's settings, not your browser's. | | Rate limit hit | See [pricing](/docs/knowledge-base/pricing) for your plan's tool call allowance. | ## FAQ > **Do I need to add Adspirer as a custom connector or MCP server?** > > No. Add the official [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) plugin from the **Marketplace**. It brings the connector, the tools, and all 14 skills in one step. If you added `https://mcp.adspirer.com/mcp` by URL before the listing existed, remove it so your bot doesn't see two copies of every tool. > **Do I need Cursor installed to use Adspirer in Grok Bot?** > > No. Grok Bot signs in with a Cursor account and installs from the Cursor Marketplace, but it runs on its own — desktop, web, or mobile. You never have to open the editor. > **If I installed Adspirer in Cursor, is it already in Grok Bot?** > > No. Install it once in each. They're separate products that share a marketplace. > **Can one bot manage several brands?** > > It can reach every ad account connected to your Adspirer account, so technically yes — but a bot holds one role and one set of context. For agency work, give each client its own bot with its own description. See [multi-client](/docs/knowledge-base/multi-client). > **Can the bot spend money without asking?** > > No. Campaigns are created paused, and spend-affecting actions stop for an approval card. The bot proposes; you approve. > **How much does Adspirer cost?** > > Pricing is based on tool calls, not ad spend, and it's the same across every AI client. Scheduled routines consume tool calls on every run. See [pricing and plans](/docs/knowledge-base/pricing). ## Related Documentation * [Cursor Setup](/docs/ai-clients/cursor) — the same plugin in the editor * [Cursor Agent](/docs/agent-skills/cursor-agent) — what's in the plugin and how the pieces fit * [Scheduled Tasks](/docs/guides/scheduled-tasks) — recurring reports and monitoring * [Google Ads Integration Guide](/docs/ad-platforms/google-ads) * [Pricing & Plans](/docs/knowledge-base/pricing) * [All Documentation](/docs/introduction) # Connect Manus to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/manus Connect Manus AI to Adspirer MCP. Manage Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads with 400+ tools, autonomous research, and interactive dashboards. Autonomous ad management with deep research. Manus connects to Adspirer as a custom MCP server, giving it 400+ advertising tools across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads. ## What Makes Manus + Adspirer Powerful Manus is an autonomous AI agent that can browse the web, write code, and execute multi-step tasks. When connected to Adspirer, it gains direct access to your ad accounts and can: * **Generate interactive dashboards** with charts, KPI cards, and data tables * **Run deep research** — competitor analysis, keyword research, market landscape * **Schedule performance briefs** — daily or weekly reports delivered to your inbox * **Monitor campaigns 24/7** — get alerts when ROAS drops or spend exceeds thresholds * **Create and manage campaigns** across all platforms from a single conversation Unlike other MCP clients that use OAuth, Manus connects via **API key authentication** through custom headers. ## Prerequisites > [!NOTE] > > * A [Manus](https://manus.im) account > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup **1. Generate an Adspirer API Key** 1. Go to [adspirer.ai/keys](https://adspirer.ai/keys) 2. Click **Create New Key** 3. Give it a name (e.g., "Manus") 4. **Copy the key immediately** — it starts with `sk_live_` and is only shown once > [!WARNING] > > Save your API key somewhere safe. You cannot view it again after creation. If you lose it, you'll need to generate a new one. **2. Open Manus MCP Settings** 1. Go to [manus.im](https://manus.im) 2. Click the **Settings** icon (gear) in the left sidebar 3. Click **Integrations** 4. Click **+ Add Custom MCP Server** **3. Configure the MCP Server** Fill in the following fields: | Field | Value | | - | - | | **Server Name** | `Adspirer` | | **Transport Type** | `HTTP` | | **Server URL** | `https://mcp.adspirer.com/mcp` | Then add a custom header: | Header Name | Header Value | | - | - | | `Authorization` | `Bearer sk_live_YOUR_API_KEY_HERE` | Replace `sk_live_YOUR_API_KEY_HERE` with the actual API key you copied in Step 1. > [!TIP] > > Make sure there is a space between `Bearer` and your key. The full value should look like: `Bearer sk_live_YOUR_API_KEY_HERE` **4. Add Skills (Recommended)** Skills teach Manus the correct workflow order, input formatting, and platform-specific patterns. Without skills, Manus discovers the tools but may not use them optimally. With skills, it operates like an expert performance marketer. 1. In Manus, click **Settings** (gear icon) in the left sidebar 2. Click **Skills** 3. Click **+ Add** → **Import from GitHub** 4. Import each skill by pasting its GitHub URL: **Performance Marketing Agent** Paste this URL in the Import from GitHub dialog: ``` https://github.com/amekala/ads-mcp/tree/main/skills/performance-marketing-agent ``` This skill teaches Manus to: * Always check connected platforms first (`get_connections_status`) * Follow the correct workflow order: read data → analyze → act * Present results in structured tables with key metrics * Handle cross-platform performance dashboards * Properly format tool inputs (string IDs, budget numbers, text limits) * Execute keyword research, budget optimization, and ROAS tracking **Best for:** Daily performance management, campaign analysis, optimization **Ad Campaign Management** Paste this URL in the Import from GitHub dialog: ``` https://github.com/amekala/ads-mcp/tree/main/skills/ad-campaign-management ``` This skill teaches Manus to: * Match user goals to the right tools and workflows * Create campaigns across Google (Search, PMax, Demand Gen, YouTube), Meta, LinkedIn, and TikTok * Research competitors and keywords before campaign creation * Manage ad extensions, bidding strategies, and audience targeting * Build cross-platform performance scorecards * Set up monitoring alerts and scheduled reports **Best for:** Campaign creation, multi-platform management, strategic planning 5. Toggle **both skills on** after importing > [!TIP] > > Import both skills for maximum effectiveness. Together they give Manus the full context needed to act as a complete advertising operations agent. **5. Save and Test** 1. Click **Save** to store the configuration 2. Click **Try it out** to verify the connection 3. If successful, Manus will discover all 400+ Adspirer tools > [!NOTE] > > If the connection fails, see the [Troubleshooting](#troubleshooting) section below. **6. Try It** Go back to the Manus chat and try a prompt: ``` Help me test the Adspirer connector and show me how to use its features. Show any data you can fetch. Give me a brief about its capabilities. The user authorization bearer token in the header is already provided. ``` Manus will discover the available tools, fetch your campaign data, and show you what's possible. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=manus)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. ## Using Skills in Conversation Once you've imported and enabled skills, you can invoke specific workflows directly in your Manus conversation: ### Performance Analysis ``` Run a cross-platform performance dashboard for the last 30 days. Show me a unified scorecard across all connected platforms. ``` Manus will follow the skill workflow: check connections → pull data from each platform → pull waste analysis → present a unified scorecard with recommendations. ### Campaign Creation with Research ``` I want to create a Google Search campaign for my plumbing business in Austin, TX. Research the market first, then build the campaign. ``` Manus will follow the campaign research workflow: web search for competitor ads → keyword research → analyze search terms → propose campaign structure → create after your approval. ### Budget Optimization ``` Where am I wasting ad spend? Analyze all platforms and tell me what to cut and where to reallocate. ``` ### Scheduled Briefs ``` Set up a daily performance brief and email it to me every morning at 9 AM. ``` ### Monitoring Alerts ``` Monitor my campaigns and alert me if ROAS drops below 2x or daily spend exceeds $500. ``` ### Reports ``` Generate a detailed performance report for all my ad accounts and email it to marketing@mycompany.com. ``` ## How It Works **1. You send a prompt in Manus** Ask Manus anything — "Show my campaign performance", "Create a Google Search campaign", or "Set up a daily performance brief". **2. Manus uses Adspirer skills and tools** Manus reads the imported skill instructions, discovers 400+ Adspirer MCP tools, and follows the correct workflow order automatically. **3. Adspirer MCP server handles authentication** Your API key (sent via the `Authorization` header) is validated server-side via SHA-256 hash lookup. Your raw key is never stored. **4. Data is fetched from your ad accounts** Adspirer connects to your Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, and YouTube Ads accounts using your stored OAuth tokens. Manus never sees your ad platform credentials. ## API Key Management ### Viewing Your Keys Go to [adspirer.ai/keys?tab=api-keys](https://adspirer.ai/keys) to see all your active keys. You'll see: * Key name * Key prefix (first 12 characters) * Created date * Last used date ### Revoking a Key If a key is compromised or no longer needed: 1. Go to [adspirer.ai/keys](https://adspirer.ai/keys) 2. Click the **Revoke** button next to the key 3. Generate a new key and update your Manus configuration ### Key Limits by Plan | Plan | Max API Keys | | - | - | | Free | 2 | | Plus | 5 | | Pro | 10 | | Max | 20 | | Enterprise | 50 | ## Troubleshooting > **Connection fails with 'OAuth authentication error'** > > This means the `Authorization` header is not reaching the server. Common causes: > > 1. **Missing `Bearer` prefix** — The header value must start with `Bearer ` (with a space) > 2. **Extra spaces or newlines** — Copy the key cleanly, no trailing whitespace > 3. **Expired or revoked key** — Check your key status at [adspirer.ai/keys?tab=api-keys](https://adspirer.ai/keys) > 4. **Manus overriding the header** — If the issue persists after verifying the above, try removing and re-adding the MCP server in Manus settings > > To verify your key works independently: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl -X POST https://mcp.adspirer.com/mcp \ > -H "Content-Type: application/json" \ > -H "Authorization: Bearer sk_live_YOUR_KEY" \ > -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' > ``` > > A successful response returns the server capabilities. A `401` means the key is invalid. > **'No Google Ads account connected' error** > > Your API key is valid, but you haven't connected an ad platform yet: > > 1. Go to [adspirer.ai](https://adspirer.ai) > 2. Click **Connections** in the sidebar > 3. Connect your Google Ads, Meta Ads, or other platform > 4. Return to Manus and try again > **Tools not showing up in Manus** > > After adding the MCP server: > > 1. Make sure you clicked **Save** (not just filled in the fields) > 2. Click **Try it out** to verify the connection > 3. Start a **new conversation** in Manus — tools are discovered per-session > 4. If still missing, remove the server and add it again > **'Session Expired' error during tool use** > > Your API key may have expired (default expiration: 365 days): > > 1. Check your key status at [adspirer.ai/keys?tab=api-keys](https://adspirer.ai/keys) > 2. If expired, generate a new key > 3. Update the `Authorization` header in Manus settings with the new key > **Manus calls tools in wrong order or formats inputs incorrectly** > > This usually means skills are not configured: > > 1. Go to **Settings > Skills** in Manus > 2. Click **+ Add > Import from GitHub** > 3. Import both skills from `https://github.com/amekala/ads-mcp/tree/main/skills/performance-marketing-agent` and `https://github.com/amekala/ads-mcp/tree/main/skills/ad-campaign-management` > 4. Toggle both skills **on** and start a new conversation > > Skills teach Manus the correct workflow order, input formatting rules, and platform-specific patterns. > **Manus can't access my ad data directly** > > This is by design. Manus runs in isolation and cannot call ad platform APIs directly. Adspirer uses a **pre-fetch pattern**: > > 1. Adspirer fetches your campaign data using your stored OAuth tokens > 2. The data is passed to Manus for analysis and report generation > 3. Manus generates insights, dashboards, or PDFs from the pre-fetched data > > This keeps your ad platform credentials secure — Manus never sees your OAuth tokens. ## Comparison with Other Clients | Feature | Manus | Perplexity | Claude | ChatGPT | Cursor | | - | - | - | - | - | - | | Auth method | API Key | OAuth | OAuth | OAuth | OAuth | | Autonomous tasks | Yes | Yes (Computer) | Limited | Limited | No | | Web research | Yes | Yes (native) | No | Yes (Browse) | No | | Dashboard generation | Yes | Yes | No | No | No | | Scheduled briefs | Yes | No | No | No | No | | Skill support | Skills (GitHub import) | Skill upload (SKILL.md) | `.claude/` | Custom GPT | `.cursor/` | | Campaign management | Yes | Yes | Yes | Yes | Yes | | Performance queries | Yes | Yes | Yes | Yes | Yes | ## What's Next > **[Performance Marketing Agent Skill](https://github.com/amekala/ads-mcp/blob/main/skills/performance-marketing-agent/SKILL.md)** > > Full skill reference for performance analysis, optimization, and reporting workflows. > **[Ad Campaign Management Skill](https://github.com/amekala/ads-mcp/blob/main/skills/ad-campaign-management/SKILL.md)** > > Full skill reference for campaign creation, keyword research, and multi-platform management. > **[Explore All Tools](/docs/agent-skills/tools)** > > Browse the full catalog of 400+ advertising tools available through Manus. > **[Ad Platform Setup](/docs/ad-platforms/google-ads)** > > Connect your Google Ads, Meta Ads, LinkedIn, or TikTok accounts. # Muse Advertising Connector | Adspirer Source: https://www.adspirer.com/docs/ai-clients/muse Connect Muse to Adspirer Advertising Agents through MCP and OAuth. Review advertising performance, research keywords, and plan campaigns across connected ad accounts. ![Meta AI icon used provisionally for Muse](https://mintcdn.com/adspirer/4r5prhvHmsPql3Tj/icons/metaai-color.svg?fit=max\&auto=format\&n=4r5prhvHmsPql3Tj\&q=85\&s=a273e9a0f0f3aa71e3697710e7799e9e) **Adspirer Advertising Agents** connects AI assistants to Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads. The Muse connector uses Adspirer's hosted MCP server to bring advertising data and campaign tools into your conversations. > [!NOTE] > > The Muse connector is being prepared for marketplace review. Availability in Muse and end-to-end connection testing are pending. This page documents the proposed connection and how to verify it when access becomes available. The Meta AI icon is used provisionally. ## What you can do * Review campaign performance and compare reporting periods across connected accounts. * Investigate wasted spend and prioritize optimization recommendations. * Research Google Ads keywords and estimated costs before planning a campaign. * Draft campaign plans and ad copy, then approve specific changes before execution. Capabilities depend on the connected advertising platform and your account permissions. See the [tool catalog](/docs/agent-skills/tools) for supported operations. ## Requirements * A Muse account with access to the connector once it becomes available. * An [Adspirer account](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=muse). * At least one advertising account connected in [Adspirer Connections](https://adspirer.ai/connections), with permission to view or manage the intended campaigns. Tool usage is subject to your [Adspirer plan](/docs/knowledge-base/pricing) and advertising-platform API limits. Advertising spend is billed separately by the advertising platforms. ## Connection details These are the settings for the Muse connector review and any supported custom MCP configuration. Muse's exact installation controls will be documented after verification. | Setting | Value | | - | - | | Connector name | `Adspirer Advertising Agents` | | Connection type | Existing MCP | | Hosted MCP endpoint | `https://mcp.adspirer.com/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth 2.1 with PKCE | | Client registration | Dynamic client registration supported | The proposed connection uses OAuth; users do not need to paste an API key. See [MCP documentation](/docs/mcp) for more about the server. ## Connect and verify when available **1. Authorize Adspirer** When the Adspirer connector is available to your Muse account, start its connection flow. Sign in to Adspirer, review the authorization request, and return to Muse after completing it. **2. Connect your advertising accounts** Open [Adspirer Connections](https://adspirer.ai/connections) and connect the platforms you want to use. Use the same Adspirer account you authorized from Muse. **3. Verify account access** Ask Muse: Verify connected advertising accounts without making changes. Check my connected advertising accounts. List each platform and account name, and tell me which accounts are available for reporting. Do not change any campaigns. Confirm that the returned accounts match your real accounts. Then request a small performance report to verify that tool calls return live data. ## Example prompts ### Review performance Compare advertising results and identify improvement opportunities. Review my Google Ads and Meta Ads performance over the last 30 complete days. Compare spend, conversions, cost per acquisition, and return on ad spend where available with the previous 30 days. Keep different currencies and conversion definitions separate. Identify the three biggest opportunities to improve results and explain what you recommend changing. Do not make changes. ### Find wasted spend Prioritize wasted-spend findings with supporting evidence. Audit my Google Ads campaigns for wasted spend over the last 30 days. Identify search terms spending without conversions and underperforming keywords. Show the spend and conversion data behind each finding, account for conversion lag, and prioritize recommendations by potential impact. Ask for my approval before making changes. ### Plan a campaign Research and draft a Google Search campaign before approval. Help me plan a Google Search campaign for an emergency plumbing business in Chicago with a \$100 daily budget. Research high-intent keywords and estimated costs, suggest negative keywords, and draft the ads. Ask for any missing business or landing-page details. Show me the full plan for approval before creating anything. If I approve creation, create the campaign paused. ### Prepare a weekly report Build a weekly brief across connected advertising accounts. Create a weekly advertising report across my connected accounts. Compare the last seven complete days with the previous seven days, highlight the strongest and weakest campaigns, and explain significant changes in spend and conversions. Separate observed results from possible explanations, and finish with three recommended actions for next week. Do not modify campaigns. ## Troubleshooting > **I cannot find Adspirer in Muse** > > Marketplace availability is pending. A published documentation page does not mean the connector has been approved or enabled for your Muse account. Contact [Adspirer support](mailto:support@adspirer.com) for availability information. > **Authorization did not complete** > > Restart the connection flow and complete sign-in and authorization in the same browser session. If it still fails, contact support with the time of the attempt and the displayed error. Do not send passwords, authorization codes, or access tokens. > **Connected successfully, but no advertising accounts appear** > > Confirm that your advertising platforms are connected in [Adspirer Connections](https://adspirer.ai/connections) under the same Adspirer account you authorized from Muse. Check that your platform user has access to the intended ad accounts. > **A tool returns a permission or usage-limit error** > > Check the account's advertising-platform permissions and your Adspirer plan usage. Some operations also depend on platform eligibility and API limits. Report the exact error to support if the account and permissions appear correct. ## Related documentation > **[MCP server](/docs/mcp)** > > Connection details and authentication for Adspirer's hosted MCP server. > **[Advertising tools](/docs/agent-skills/tools)** > > Explore available operations across supported advertising platforms. Icon source: [LobeHub Meta AI](https://github.com/lobehub/lobe-icons/tree/master/packages/static-svg), used under the project's MIT license. # Connect OpenClaw to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/openclaw Install the Adspirer OpenClaw plugin. 400+ ad tools, 14KB skill file built in, zero configuration. Manage Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads. One plugin, 400+ tools, 14KB skill file built in. No separate setup. ## What Makes OpenClaw Different Every other MCP client gives you access to Adspirer's 400+ tools. That's the baseline. OpenClaw gives you a complete AI advertising agent -- pre-configured, pre-trained, ready to run campaigns. The plugin includes a 14.4KB SKILL.md file that documents every tool, every workflow, every platform-specific nuance. The plugin doesn't just connect to Adspirer -- it includes a 14.4KB instruction manual that turns OpenClaw into a specialized advertising AI. You're deploying an expert, not configuring tools. ## Prerequisites > [!NOTE] > > * Node.js 18+ > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) ## Setup **Local Install** Install OpenClaw on your own machine (Mac, Linux, or Windows with WSL). **1. Install OpenClaw** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npm install -g openclaw ``` **2. Initialize OpenClaw** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw init ``` This creates `~/.openclaw/openclaw.json` with default settings. **3. Set Tools Profile** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw config set tools.profile full ``` This gives the agent access to bash, file operations, and web tools. **4. Install the Adspirer Plugin** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins install openclaw-adspirer ``` This installs the plugin with all 400+ tools and the 14.4KB SKILL.md instruction file bundled in. No separate skill or agent installation needed. **5. Authenticate with Adspirer** **Web Login (OAuth)** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer login ``` Your browser opens for OAuth 2.1 sign-in. After signing in at adspirer.ai, you'll be redirected back automatically. No passwords stored locally. **API Key (Headless/Remote)** Generate an API key at [adspirer.ai/keys](https://adspirer.ai/keys), then authenticate: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer login --token sk_live_your_token_here ``` See [Remote Server Setup](#remote-server-setup) for Docker, CI/CD, and environment variable options. **6. Restart the Gateway** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw gateway restart ``` This loads the plugin and registers all 400+ ad management tools. **7. Connect Your Ad Platforms** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer connect ``` This opens [adspirer.ai/connections](https://adspirer.ai/connections) where you can link: * Google Ads * Meta Ads (Facebook & Instagram) * LinkedIn Ads * TikTok Ads **8. Verify Your Setup** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer status ``` You should see your authentication status, connected platforms, and tool count. **9. Start Using** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw ``` Then ask the agent things like: * "Show me my Google Ads campaign performance for the last 30 days" * "What keywords are wasting spend?" * "Create a new search campaign for..." * "Pause campaign X" > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=openclaw)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. > [!TIP] > > You're connected. OpenClaw is now a fully configured advertising agent with built-in workflows. **Hostinger VPS** Deploy OpenClaw on a Hostinger VPS with OpenClaw pre-installed. Your agent runs 24/7 and is accessible from WhatsApp, Telegram, Discord, or a web dashboard. No terminal experience required. > [!TIP] > > For a detailed walkthrough with agency use cases and cost breakdown, see the [full Hostinger deployment guide](/docs/guides/deploy-paid-media-agent-hostinger). **1. Buy a Hostinger VPS with OpenClaw** Go to [Hostinger's VPS marketplace](https://www.hostinger.com/vps), select a plan, and click **Deploy**. OpenClaw is auto-selected as the pre-installed application. **2. Configure Environment Variables** Hostinger's setup screen asks for configuration values: * **OPENCLAW\_GATEWAY\_TOKEN** — auto-generated. **Copy and save this** — it's your login password. * **WHATSAPP\_NUMBER** — optional. Enter your phone number to connect WhatsApp later. * **AI API keys** — optional. Leave blank if you're only using Adspirer for ad management. Complete the purchase and wait for the status to show **Running** (1–2 minutes). **3. Generate Your Adspirer API Key** In a new browser tab: 1. Go to [adspirer.ai/keys](https://adspirer.ai/keys) 2. Click **Generate New Key** 3. Name it "Hostinger server" 4. Copy the key — it starts with `sk_live_` and **won't be shown again** **4. Access Your Server's Terminal** In Hostinger's hPanel, open the **Terminal** or **SSH Access** for your VPS. **5. Install the Adspirer Plugin** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins install openclaw-adspirer ``` **6. Authenticate with Adspirer** Replace `sk_live_your_token_here` with your actual API key: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer login --token sk_live_your_token_here ``` **7. Restart the Gateway** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw gateway restart ``` **8. Connect Your Ad Platforms** Go to [adspirer.ai/connections](https://adspirer.ai/connections) from any browser and connect your Google Ads, Meta Ads, LinkedIn Ads, or TikTok Ads accounts via OAuth. **9. Log Into the Dashboard** Open `http://your-server-ip:port` in your browser (find the IP and port in Hostinger's Docker Manager). Enter your `OPENCLAW_GATEWAY_TOKEN` to log in. **10. Connect WhatsApp (Optional)** In the OpenClaw dashboard, go to **Channels** → click **Show QR code** → scan with WhatsApp (**Settings → Linked Devices → Link a Device**). **11. Start Managing Ads** Send a message from WhatsApp, Telegram, or the web dashboard: > "Show me my Google Ads performance for the last 7 days" Your always-on ad agent is live. > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=openclaw-hostinger)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. > [!TIP] > > Your agent is running 24/7 on Hostinger with Adspirer's 400+ ad tools and the built-in SKILL.md instruction file. It's accessible from WhatsApp, Telegram, Discord, or your web browser. ## Remote Server Setup If you're running OpenClaw on a remote server (VPS, Docker, CI/CD), you can't use the browser-based OAuth login. Instead, use a **Personal Access Token** (API key). **1. Generate an API Key** 1. Go to [adspirer.ai/keys](https://adspirer.ai/keys) 2. Click **Generate New Key** 3. Give it a name (e.g., "Hostinger server", "CI/CD pipeline") 4. Copy the token — it starts with `sk_live_` and **won't be shown again** > [!WARNING] > > Store your API key securely. Treat it like a password. If compromised, revoke it immediately from the dashboard and generate a new one. **2. Authenticate with the API Key** **CLI Flag** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer login --token sk_live_your_token_here ``` **Environment Variable** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} export ADSPIRER_API_KEY=sk_live_your_token_here ``` The environment variable takes priority over stored config. No `login` command needed. **Docker** ```dockerfile theme={"theme":{"light":"github-light","dark":"github-dark"}} ENV ADSPIRER_API_KEY=sk_live_your_token_here ``` Or pass it at runtime: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} docker run -e ADSPIRER_API_KEY=sk_live_your_token_here your-image ``` **CI/CD (GitHub Actions)** ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} env: ADSPIRER_API_KEY: ${{ secrets.ADSPIRER_API_KEY }} ``` Add your API key as a repository secret in GitHub Settings. **3. Connect Your Ad Platforms** API keys authenticate you with Adspirer, but you still need to connect your ad platforms from a browser: 1. Go to [adspirer.ai/connections](https://adspirer.ai/connections) from any machine with a browser 2. Connect Google Ads, Meta Ads, LinkedIn Ads, or TikTok Ads via OAuth 3. Your remote server's API key will then have access to those connected accounts **4. Verify** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer status ``` You should see: ``` ✅ Authenticated via API Key Server: https://mcp.adspirer.com Key prefix: sk_live_a1b2... ``` > [!NOTE] > > API key limits are tier-based: Free (2 keys), Plus (5), Pro (10), Max (20). Each key can be named, set to expire, and revoked independently. ## CLI Commands | Command | Description | | - | - | | `openclaw init` | Create `~/.openclaw/openclaw.json` with default settings | | `openclaw config set tools.profile full` | Enable bash, file operations, and web tools | | `openclaw plugins install openclaw-adspirer` | Install the Adspirer plugin | | `openclaw gateway restart` | Reload plugins and register tools | | `openclaw adspirer login` | Authenticate via OAuth PKCE (browser-based) | | `openclaw adspirer login --token ` | Authenticate with an API key (headless/remote) | | `openclaw adspirer logout` | Clear stored tokens and API keys | | `openclaw adspirer status` | Show auth status, connections, tool count | | `openclaw adspirer accounts` | List connected ad accounts | | `openclaw adspirer tools` | List registered tools by platform | | `openclaw adspirer connect` | Open Adspirer to connect ad platforms | ## What You Get: The Skill File Most MCP integrations give you raw tool access. OpenClaw gives you a 14,400-character instruction manual that covers: * **400+ tools documented:** Every parameter, every return value, every edge case * **6 complete workflows:** Performance analysis, keyword research, campaign creation (per platform), budget optimization, account management, automation * **Platform quick reference:** When to use each platform, minimum budgets, best use cases * **Safety rules:** What to always check first, what requires user confirmation, what never to retry * **Troubleshooting guide:** Common errors and how to fix them * **Example prompts:** Real queries you can copy-paste to get started This isn't configuration. It's training. OpenClaw reads the SKILL.md file and knows how to behave like an expert advertising manager. ## What You Can Do 400+ tools across 6 ad platforms: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, wasted spend analysis, budget optimization, extensions, asset management | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | B2B targeting (job titles, industries, seniority), sponsored content, lead gen forms, performance analysis | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection, placement optimization | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance tracking | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | Plus 8 automation tools for scheduling, monitoring, and cross-platform reporting. ## Example Commands What to actually run once you're set up: ### Google Search Campaign ``` openclaw "Create a Google Search campaign for my consulting firm: - Service: fractional CFO services for startups - Target: startup founders and CEOs at Series A-B companies - Budget: $80/day - Research keywords with real CPC data - Add negative keywords for 'jobs', 'salary', 'free'" ``` ### Google PMax Campaign ``` openclaw "Set up a Performance Max campaign: - Product: standing desk, $549 retail price - Target ROAS: 500% - Product images: [paste URLs] - Write compelling headlines and descriptions - Use my Merchant Center product feed" ``` ### Meta Ads Campaign ``` openclaw "Create a Meta image campaign for my online course: - Product: UX design bootcamp, $599 one-time - Target: designers and career changers aged 24-38 - Interests: UX design, Figma, product design, career growth - Budget: $55/day - Image URL: [paste URL] - Optimize for registrations" ``` ### LinkedIn Lead Gen Campaign ``` openclaw "Launch a LinkedIn sponsored content campaign: - Product: employee engagement platform - Target: HR VPs and CHROs at enterprises with 1,000+ employees - Industries: tech, finance, healthcare - Budget: $130/day - Goal: book a product demo - Image URL: [paste URL]" ``` ### Cross-Platform Performance Report ``` openclaw "Generate a full performance report for the last 30 days. Pull data from all connected platforms. Include: - Executive summary with key wins and concerns - Per-platform metrics: spend, conversions, CPA, ROAS - Wasted spend analysis (Google keywords + Meta creative fatigue) - Top 5 recommendations for next month Format as markdown." ``` ## Tool Groups > [!NOTE] > > **Plugin v2026.5.30** adds the free [Diagnostic & Helper tools](/docs/agent-skills/diagnostic-helper-tools) — get-started guidance, launch-readiness checks, error explanations, and "what changed" summaries. Reinstall (`openclaw plugins install openclaw-adspirer`) to pick them up, then discover them at runtime with `action: "list_tools"` on the `diagnostic_and_helper_tools` router. | Group | Platform | Tools | | - | - | - | | `google_ads` | Google Ads | 40 | | `meta_ads` | Meta Ads | 20 | | `tiktok_ads` | TikTok Ads | 4 | | `linkedin_ads` | LinkedIn Ads | 28 | | `manus` | Automation | 8 | | `system` | Cross-Platform | 4 | | `diagnostic_and_helper_tools` | Cross-Platform | 1 router → 9 helpers | ### Filtering Enable only specific platforms: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} config: enabledGroups: ["google_ads", "meta_ads"] ``` Or cherry-pick individual tools: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} config: enabledTools: ["echo_test", "get_campaign_performance", "list_campaigns"] ``` ## Configuration | Field | Type | Default | Description | | - | - | - | - | | `serverUrl` | string | `https://mcp.adspirer.com` | MCP server URL | | `accessToken` | string | — | OAuth access token (set by login) | | `refreshToken` | string | — | OAuth refresh token (set by login) | | `tokenExpiresAt` | number | — | Token expiry timestamp (set by login) | | `apiKey` | string | — | Personal access token (`sk_live_...`) for headless auth. Set via `--token` flag or `ADSPIRER_API_KEY` env var. | | `defaultAccountId` | string | — | Default ad account ID | | `enabledGroups` | string\[] | all groups | Platform groups to enable | | `enabledTools` | string\[] | `[]` | Cherry-pick specific tools (overrides groups) | | `requestTimeoutMs` | number | `60000` | HTTP request timeout in ms | ## Tool Safety Model * **Read tools** (`get_*`, `list_*`, `analyze_*`, etc.) — auto-execute, no confirmation needed * **Write tools** (`create_*`, `update_*`, `pause_*`, etc.) — agent MUST ask user before executing ## The claw\.json Manifest The plugin includes a manifest file that defines its metadata and permissions: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "adspirer-ads-agent", "version": "1.2.1", "displayName": "Adspirer Ads Agent", "keywords": [ "advertising", "google-ads", "meta-ads", "linkedin-ads", "tiktok-ads", "ppc", "mcp" ], "permissions": { "network": [ "mcp.adspirer.com", "www.adspirer.com" ] } } ``` This tells OpenClaw that the plugin is an advertising agent, which keywords to associate with it, and which domains it's allowed to access. The network permissions ensure the plugin can only connect to Adspirer's servers — no other external services. ## Safety Features The skill file includes safety rules. OpenClaw enforces them automatically: * **All campaigns created PAUSED:** Review before they spend money * **User confirmation required:** OpenClaw asks before any action that affects spend * **Read-before-write workflows:** The agent researches keywords before creating campaigns, validates assets before launching * **Connection status checks:** Always verifies you're managing the correct account first * **No automatic retries:** If a tool call fails, OpenClaw reports the error instead of retrying blindly * **Platform-specific minimums:** The agent knows Google Ads requires $10/day minimum, LinkedIn requires $10/day, Meta has no minimum -- and won't let you create campaigns below those thresholds ## Troubleshooting ### "Plugin not found" error List your installed plugins: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins list ``` If you don't see `openclaw-adspirer`, re-run the install command from Step 1. ### "Not authenticated" error Your login session may have expired. Re-authenticate: ``` openclaw adspirer login ``` ### "No ad platforms connected" warning Run the connect command: ``` openclaw adspirer connect ``` Make sure you authorize at least one ad platform (Google, Meta, LinkedIn, or TikTok) in the OAuth flow. ### Tools not working or returning errors Check your account status at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account). Free accounts get 15 tool calls/month. If you've hit the limit, upgrade to Plus ($49/mo for 150 calls) or Pro ($99/mo for 600 calls). ### Skill file not loading The skill file is bundled with the plugin. If OpenClaw isn't following the documented workflows, try reinstalling: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins uninstall openclaw-adspirer openclaw plugins install openclaw-adspirer ``` ### "Invalid or expired API key" Your API key may have been revoked, expired, or mistyped: 1. Go to [adspirer.ai/keys](https://adspirer.ai/keys) and check if the key is still **Active** 2. If revoked or expired, generate a new key 3. Re-authenticate: `openclaw adspirer login --token sk_live_new_key_here` ### "No platform account connected" (with API key) API keys authenticate you with Adspirer, but you still need to connect your ad platforms via OAuth from a browser: 1. Go to [adspirer.ai/connections](https://adspirer.ai/connections) from any machine with a browser 2. Connect your Google Ads, Meta, LinkedIn, or TikTok accounts 3. Your remote server's API key will then have access to those accounts ### "API key authentication error" * Ensure the token starts with `sk_live_` * Check for extra whitespace or line breaks when copying * If using the environment variable, verify: `echo $ADSPIRER_API_KEY` * Try generating a new key from [adspirer.ai/keys](https://adspirer.ai/keys) ### Network permission errors If your firewall blocks the plugin, whitelist these domains: * `mcp.adspirer.com` (MCP server) * `www.adspirer.com` (OAuth and account management) ## FAQ > **What's the difference between OpenClaw and other MCP clients?** > > Other clients ([Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor)) give you access to Adspirer's tools. OpenClaw gives you a pre-configured advertising agent with a 14KB instruction manual built in. Less setup, more intelligence out of the box. > **Do I need to install skills separately?** > > No. The SKILL.md file is bundled with the plugin. Other clients require manual skill installation. OpenClaw does it automatically. > **Can I edit the skill file to customize behavior?** > > Yes. The skill file is at `node_modules/openclaw-adspirer/skills/adspirer-ads-agent/SKILL.md` (if installed via NPM) or in the OpenClaw plugins directory. Edit it to change default behaviors, add custom workflows, or modify safety rules. Changes take effect on the next OpenClaw restart. > **Can I manage multiple ad accounts?** > > Yes. Connect multiple Google Ads accounts, multiple Meta Business Managers, etc. Use the `switch_primary_account` command to change which account you're managing, or specify the account ID in your commands. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing details](https://www.adspirer.com/pricing). > **Can I use OpenClaw on a remote server or in Docker?** > > Yes. Generate an API key from [adspirer.ai/keys](https://adspirer.ai/keys), then use `openclaw adspirer login --token sk_live_...` or set the `ADSPIRER_API_KEY` environment variable. See [Remote Server Setup](#remote-server-setup). ## Related Documentation * [Claude Code Setup Guide](/docs/ai-clients/claude-code) * [Cursor Setup Guide](/docs/ai-clients/cursor) * [Codex Setup Guide](/docs/ai-clients/codex) * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; drop the folder in as a skill (\$39 one-time) # Connect Perplexity to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/perplexity Connect Perplexity to Adspirer via MCP connector. Manage Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads with 400+ tools from Perplexity Computer's AI agent. Search-powered ad management. Connect Adspirer to Perplexity Computer and combine real-time web research with 400+ advertising tools across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads. [Manage Google Ads from Perplexity Computer with Adspirer MCP](https://www.youtube.com/embed/NowmI2dn0F4) Manage Google Ads from Perplexity Computer with Adspirer MCP ## Prerequisites > [!NOTE] > > * A Perplexity **Pro**, **Max**, or **Enterprise** subscription (connectors are not available on the free tier) > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads ## Setup (2 Minutes) **1. Open Perplexity Computer** Go to [perplexity.ai](https://www.perplexity.ai) and click **Computer** in the left sidebar. You need a Pro, Max, or Enterprise subscription to access Computer and Connectors. ![Perplexity Computer home page showing Computer sidebar with Connectors option](https://mintcdn.com/adspirer/l_MofcQvSvbf4Ev6/images/perplexity/perplexity-computer.png?fit=max\&auto=format\&n=l_MofcQvSvbf4Ev6\&q=85\&s=4cfcf9d1a8bd763bb0aef4c68a96c888) Perplexity Computer — your autonomous AI agent **2. Open Connectors** Click **Connectors** in the left sidebar to see all available connectors. Then click **+ Custom connector** in the top-right corner. ![Perplexity Connectors page showing available connectors and Custom connector button](https://mintcdn.com/adspirer/l_MofcQvSvbf4Ev6/images/perplexity/perplexity-connectors.png?fit=max\&auto=format\&n=l_MofcQvSvbf4Ev6\&q=85\&s=631851dbeec1915e1f9efc9958dae87c) Connectors page — click + Custom connector to add Adspirer **3. Add Adspirer Connector** In the **Add custom connector** dialog, fill in: | Field | Value | | - | - | | **Name** | `Adspirer` | | **Description** | `AI Paid Media Agent` | | **MCP Server URL** | `https://mcp.adspirer.com/mcp` | Check the **"I understand custom connectors can introduce risks"** checkbox, then click **Add**. ![Add custom connector dialog with Adspirer name, description, and MCP server URL filled in](https://mintcdn.com/adspirer/l_MofcQvSvbf4Ev6/images/perplexity/add-connector-filled.png?fit=max\&auto=format\&n=l_MofcQvSvbf4Ev6\&q=85\&s=142966783aeb7f15fb5a24ff5e922e95) Fill in Adspirer's MCP server URL and click Add **4. Authorize Adspirer** Perplexity opens Adspirer's OAuth page. Sign in and authorize access to your ad accounts. You'll see the specific permissions being requested — view campaigns, create ads, view performance metrics, and view connected accounts. ![Adspirer OAuth authorization page showing requested permissions](https://mintcdn.com/adspirer/l_MofcQvSvbf4Ev6/images/perplexity/oauth-authorize.png?fit=max\&auto=format\&n=l_MofcQvSvbf4Ev6\&q=85\&s=42da2b024f0d458cbb46a96dfacd2e25) Authorize Adspirer to access your ad accounts **5. Verify Connection** After authorization, you'll return to the Connectors page. Adspirer appears with a green checkmark indicating it's connected and ready. ![Perplexity Connectors page showing Adspirer connected with green checkmark](https://mintcdn.com/adspirer/l_MofcQvSvbf4Ev6/images/perplexity/adspirer-connected.png?fit=max\&auto=format\&n=l_MofcQvSvbf4Ev6\&q=85\&s=cd18ca078e540d82156f78e910536296) Adspirer connected successfully — green checkmark confirms active connection **6. Add the Adspirer Skill (Recommended)** Skills teach Perplexity Computer the *right way* to use Adspirer's 400+ tools — which tools to call first, how to validate data before creating campaigns, when to ask for confirmation. Without a skill, Computer guesses the tool order. With it, Computer follows proven advertising workflows. 1. Download the SKILL.md file from GitHub: > **[Download SKILL.md from GitHub](https://github.com/amekala/ads-mcp/raw/main/shared/skills/adspirer-ads/SKILL.md)** > > Click to download the `adspirer-ads` skill file. 2. In Perplexity Computer, click **Skills** in the left sidebar 3. Click **+ Create skill** in the top-right corner 4. In the **Upload skill** dialog, drag the downloaded `SKILL.md` file or click to upload it ![Perplexity Upload skill dialog showing file requirements and drag-and-drop area](https://mintcdn.com/adspirer/I9hVLERxZr-9OzrZ/images/perplexity/upload-skill-dialog.png?fit=max\&auto=format\&n=I9hVLERxZr-9OzrZ\&q=85\&s=1ff63d12c002f799854074202a66bf47) Upload the SKILL.md file — drag and drop or click to browse 5. The skill appears as **adspirer-ads** in your Skills list. Perplexity applies it automatically when you ask about advertising. ![Perplexity skill detail showing adspirer-ads skill with SKILL.md file and description](https://mintcdn.com/adspirer/I9hVLERxZr-9OzrZ/images/perplexity/skill-detail.png?fit=max\&auto=format\&n=I9hVLERxZr-9OzrZ\&q=85\&s=9a43a45afd556fbc25dd54cde5da6124) Adspirer skill installed — Perplexity applies it automatically when needed > [!TIP] > > The skill file is maintained in the [ads-mcp GitHub repository](https://github.com/amekala/ads-mcp/blob/main/shared/skills/adspirer-ads/SKILL.md) and always reflects the latest tools and workflows. Check back for updates as new platforms and tools are added. **7. Start Managing Ads** Go back to Perplexity Computer and start a new task. Adspirer's 400+ tools are now available: ``` Check my connected ad platforms ``` You should see a table showing your connected accounts across all platforms with account IDs, names, and connection status. **8. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=perplexity)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. > [!TIP] > > You're connected. Perplexity Computer will automatically use Adspirer tools when you ask about your ad campaigns. ## MCP Server Configuration ``` Name: Adspirer Description: AI Paid Media Agent MCP Server URL: https://mcp.adspirer.com/mcp Authentication: OAuth (auto-discovered) Required Plan: Perplexity Pro, Max, or Enterprise ``` ## Why Perplexity for Advertising Perplexity combines real-time search with ad management — a unique combination: * **Search-Augmented Research** — Perplexity searches the web in real-time. Ask it to research competitors, analyze market trends, or find industry benchmarks *before* creating campaigns. No other MCP client does this natively. * **Perplexity Computer** — An autonomous agent that can plan, execute, and iterate on multi-step advertising workflows. Create a full campaign from a single prompt. * **Multi-Model Orchestration** — Computer routes subtasks to the best AI model for each job (writing ad copy, analyzing data, generating reports). * **400+ App Integrations** — Beyond Adspirer, connect Gmail, Slack, Notion, and more. Build end-to-end marketing workflows. ## What You Can Do 400+ tools across 6 ad platforms: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research with real CPC data, Search & PMax campaigns, wasted spend analysis, budget optimization | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue detection | | **LinkedIn Ads** | 55 | Sponsored content, lead gen forms, B2B targeting by job title, industry, seniority | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance analysis | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | ## Example Prompts ### Research + Campaign Creation Perplexity searches the web for competitor insights, then uses Adspirer to create a campaign with real keyword data. Research my top competitors for "AI marketing tools", analyze their Google Ads strategy, then create a Google Search campaign targeting keywords they're bidding on. Budget: \$50/day. Research keywords first, then group by intent. ### Cross-Platform Performance Audit Multi-platform audit with prioritized action list and savings estimate. Audit all my ad accounts for the last 30 days: * Google: find wasted spend (keywords with clicks but zero conversions) * Meta: check for creative fatigue (frequency > 3, declining CTR) * LinkedIn: compare CPA across audience segments Give me a prioritized action list with estimated monthly savings. ### Market Research + Campaign Web research combined with keyword data for a new campaign. I'm launching a B2B SaaS for project management. Research the market landscape — who are the top players, what are they spending on ads? Then research Google Ads keywords and create a Search campaign targeting high-intent keywords with \$40/day budget. ## Perplexity Computer: Autonomous Workflows Perplexity Computer (available on Max and Enterprise plans) can execute complex, multi-step advertising workflows autonomously: | Workflow | What Computer Does | | - | - | | **Campaign launch** | Researches competitors → finds keywords → validates assets → creates campaign (PAUSED) | | **Performance audit** | Pulls data from all platforms → identifies wasted spend → recommends optimizations | | **Market research** | Searches the web for industry trends → pulls your ad data → compares against benchmarks | | **Daily brief** | Fetches performance metrics → formats a summary → sends via email | > [!TIP] > > Perplexity Computer can chain web research with Adspirer tools in a single workflow. For example, it can search the web for competitor ad copy, then use Adspirer to create campaigns that differentiate from competitors — all from one prompt. ## FAQ > **What is Perplexity Computer?** > > Perplexity Computer is an autonomous AI agent that can plan, coordinate, and execute complex multi-step tasks. It orchestrates multiple AI models and integrates with 400+ apps. When connected to Adspirer, it gains direct access to your ad accounts and can run advertising workflows autonomously. > **Which Perplexity plans support connectors?** > > MCP connectors are available on Perplexity Pro ($20/month), Max ($200/month), and Enterprise plans. The free tier does not include connector functionality. Perplexity Computer (for autonomous workflows) requires Max or Enterprise. > **How is Perplexity different from ChatGPT or Claude for ads?** > > All three use the same Adspirer MCP server, so the 400+ advertising tools are identical. Perplexity's advantage is built-in web search — it can research competitors, market trends, and industry benchmarks in real-time, then immediately act on that research using Adspirer tools. ChatGPT and Claude don't have native real-time search. > **Can I use Adspirer with both Perplexity and other AI clients?** > > Yes. Your Adspirer account works across all platforms. Connect the same MCP URL to Perplexity, ChatGPT, Claude, Cursor, or any MCP-compatible client. Your ad account connections carry across all of them. > **Does Perplexity support Adspirer skills?** > > Yes. Perplexity Computer supports skills — upload a `SKILL.md` file via **Computer → Skills → + Create skill**. The `adspirer-ads` skill teaches Computer proven advertising workflows and is available in the [ads-mcp GitHub repo](https://github.com/amekala/ads-mcp/blob/main/shared/skills/adspirer-ads/SKILL.md). Perplexity applies skills automatically when relevant to your prompt. > **How much does this cost?** > > Adspirer pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing](https://www.adspirer.com/pricing). Perplexity's subscription is separate. > **Why does the connector dialog say 'can introduce risks'?** > > This is a standard Perplexity warning for all custom (third-party) connectors. Adspirer uses OAuth 2.1 with PKCE — the same security standard used by banking apps. Your ad platform credentials are never shared with Perplexity. See [Security](/docs/knowledge-base/security) for details. ## Related Documentation * [ChatGPT Setup](/docs/ai-clients/chatgpt) — the official Adspirer plugin for ChatGPT * [Claude Setup](/docs/ai-clients/claude) — Claude's native MCP integration * [Claude Code Setup](/docs/ai-clients/claude-code) — Terminal-based setup for developers * [Google Ads Integration](/docs/ad-platforms/google-ads) — Full Google Ads tool reference * [Agent Skills Overview](/docs/agent-skills/overview) — Teach your AI the right workflows * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account; paste its agent instructions into your Space (\$39 one-time) # Connect Windsurf to Ad Platforms | Adspirer Source: https://www.adspirer.com/docs/ai-clients/windsurf Connect Windsurf IDE to Adspirer MCP via streamable HTTP config. Manage Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads from Codeium's AI editor with 400+ tools. Manage ads from Windsurf without leaving your editor. 400+ tools, same workflow. ## Prerequisites > [!NOTE] > > * Windsurf IDE installed ([download here](https://codeium.com/windsurf)) > * An Adspirer account ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=page\&utm_content=signup)) > * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads > * Basic familiarity with JSON config files ## Setup (3 Minutes) **1. Add Adspirer to Your MCP Config** Windsurf stores MCP server configs at `~/.codeium/windsurf/mcp_config.json`. Create or edit that file: ```json ~/.codeium/windsurf/mcp_config.json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "mcpServers": { "adspirer": { "type": "streamable-http", "url": "https://mcp.adspirer.com/mcp" } } } ``` If you already have other MCP servers configured, add the `"adspirer"` entry to the `"mcpServers"` object. The `"type": "streamable-http"` is important -- it tells Windsurf to use HTTP transport with real-time progress streaming. **2. Restart Windsurf** MCP configs load on startup. Close Windsurf completely and reopen it. **3. Authenticate** Open Windsurf's AI chat (default hotkey: Cmd+Shift+I or Ctrl+Shift+I) and say: ``` Check my connected ad platforms ``` Windsurf will prompt you to authorize Adspirer. Your browser opens automatically for OAuth 2.1 sign-in. Connect your ad accounts (Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads) and approve permissions. **4. Verify the Connection** After authenticating, Windsurf should show you a table of your connected accounts with names, IDs, and connection status. If you see your ad platforms listed, you're ready to go. **5. Try It Now** > **[Sign up for Adspirer — free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=setup-cta\&utm_content=windsurf)** > > 15 free tool calls/month. No credit card required. Connect your ad accounts in 2 minutes. > [!TIP] > > You're connected. Windsurf now has access to 400+ advertising tools from the AI chat panel. ## What You Can Do 400+ tools across 6 ad platforms, accessible from Windsurf's AI chat: | Platform | Tools | Key Capabilities | | - | - | - | | **Google Ads** | 156 | Keyword research, Search & PMax campaigns, wasted spend detection, budget optimization, search term reports | | **Amazon Ads** | 61 | Sponsored Products, Brands & Display, ASIN/keyword targeting, ACOS & ROAS analytics, budget recommendations | | **LinkedIn Ads** | 55 | B2B targeting (job titles, industries, company size), sponsored content, lead gen forms, creative analysis | | **Meta Ads** | 60 | Image/video/carousel ads, audience targeting, creative fatigue detection, placement optimization | | **TikTok Ads** | 37 | In-feed campaigns, asset validation, performance tracking | | **ChatGPT Ads** | 36 | Pay-per-click chat-card ads inside ChatGPT responses, launch orchestrator, conversions (pixel + CAPI); created paused | Plus 8 automation tools for scheduling, monitoring, and cross-platform reporting. ## Example Prompts What to ask Windsurf once you're connected: ### Google Search Campaign Google Search campaign for fitness app with negative keywords. Create a Google Search campaign for my fitness app: * Product: personal training app with AI workout plans, \$14.99/mo * Target: fitness enthusiasts aged 25-45 * Budget: \$60/day * Research keywords with CPC data first * Include negative keywords for free workout searches ### Google PMax Campaign PMax campaign for e-commerce with Merchant Center integration. Set up a PMax campaign for my online store: * Product: handmade ceramic mugs, \$34 average order * Target ROAS: 400% * Product images: \[paste URLs] * Write 5 headlines and 4 descriptions * Connect to my Merchant Center feed ### Meta Ads Campaign Meta video campaign optimized for sign-ups. Launch a Meta video campaign for my meal prep service: * Target: busy professionals aged 28-42, interests in healthy eating and meal planning * Budget: \$45/day * Video URL: \[paste URL] * Write 3 primary text variations * Optimize for sign-ups ### LinkedIn Ads Campaign LinkedIn B2B campaign targeting HR leadership. Create a LinkedIn campaign for my HR tech startup: * Product: AI-powered applicant tracking system * Target: HR Directors and Talent Acquisition VPs * Company size: 500-10,000 employees * Budget: \$100/day * Goal: demo requests * Image URL: \[paste URL] ### Wasted Spend Audit Multi-platform wasted spend audit prioritized by savings. Audit all my ad accounts for the last 30 days: * Google: keywords with spend but zero conversions * Meta: ads with frequency > 4 and declining CTR * LinkedIn: audience segments with CPA above \$80 Prioritize actions by potential monthly savings. ## Agent Skills (Coming Soon) > [!NOTE] > > **Note:** Windsurf skills support is currently in development. > > Skills are instruction files that teach AI assistants the optimal workflow for using Adspirer's 400+ tools -- which tools to call first, how to validate data before creating campaigns, when to ask for user confirmation, etc. Other clients ([Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), [OpenClaw](/docs/ai-clients/openclaw)) already have skills available. Windsurf support will be added to the [GitHub repo](https://github.com/amekala/ads-mcp) soon. For now, Windsurf has full access to all 400+ Adspirer tools. You just need to be more explicit in your prompts about the workflow you want -- for example, "research keywords before suggesting a campaign" instead of assuming the AI will know to do that automatically. ## Safety Features * **All campaigns created PAUSED:** Review before they spend money * **User confirmation prompts:** Windsurf asks before actions that affect spend * **OAuth 2.1 with PKCE:** No passwords or API keys stored locally * **Connection verification:** Tools check that you're managing the correct account ## Troubleshooting ### Windsurf doesn't recognize Adspirer tools Check your MCP config file: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cat ~/.codeium/windsurf/mcp_config.json ``` Make sure the JSON is valid (no trailing commas, proper quotes). Verify the `"type"` is set to `"streamable-http"`. Restart Windsurf after any config changes. ### "Connection failed" error Your firewall or network might be blocking the MCP connection. Try: * Whitelisting `mcp.adspirer.com` in your firewall * Checking if your company VPN blocks external HTTP connections * Testing with a different network to isolate the issue ### OAuth flow not opening in browser Some browser settings block automatic redirects. Try: * Check your default browser settings (Windsurf uses your system default) * Disable browser extensions that block pop-ups * Try a different browser ### Tools returning errors or "limit exceeded" Check your account status at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account). Free accounts get 15 tool calls/month. If you've hit the limit, upgrade to Plus ($49/mo for 150 calls) or Pro ($99/mo for 600 calls). ### Config file doesn't exist If `~/.codeium/windsurf/mcp_config.json` doesn't exist, create the directory structure first: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} mkdir -p ~/.codeium/windsurf echo '{"mcpServers":{"adspirer":{"type":"streamable-http","url":"https://mcp.adspirer.com/mcp"}}}' > ~/.codeium/windsurf/mcp_config.json ``` ## FAQ > **What's the difference between Windsurf and Cursor?** > > Both are AI-powered code editors with MCP support. [Cursor](/docs/ai-clients/cursor) is built on VS Code and has mature Cursor Rules support. Windsurf is built by Codeium with a different AI model and UX. Choose based on which editor you prefer -- both work equally well with Adspirer. > **Can I use Windsurf Flow mode with Adspirer?** > > Yes. Windsurf Flow (the multi-step agentic mode) has full access to Adspirer tools. You can ask Flow to analyze campaigns, generate reports, and save the output as files in your project -- all in one autonomous task. > **Will skills be available for Windsurf?** > > Yes. Skills support is in development and will be added to the [ads-mcp GitHub repo](https://github.com/amekala/ads-mcp) soon. Follow the repo for updates. > **Can I manage multiple ad accounts?** > > Yes. Connect multiple Google Ads accounts, multiple Meta Business Managers, etc. Use the `switch_primary_account` tool to change which account you're managing, or specify the account ID in your prompts. > **How much does Adspirer cost?** > > Pricing is based on tool calls, not ad spend. Free tier: 15 calls/month. Plus: $49/mo for 150 calls. Pro: $99/mo for 600 calls. Max: \$199/mo for 3,000 calls. See [full pricing details](https://www.adspirer.com/pricing). ## Related Documentation * [Claude Code Setup Guide](/docs/ai-clients/claude-code) * [Cursor Setup Guide](/docs/ai-clients/cursor) * [Codex Setup Guide](/docs/ai-clients/codex) * [OpenClaw Setup Guide](/docs/ai-clients/openclaw) * [Google Ads Integration](/docs/ad-platforms/google-ads) * [Pricing & Plans](https://www.adspirer.com/pricing) * [All Documentation](/docs/introduction) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill and prompt book generated from your own ad account. Not available for Windsurf: nothing documents the desktop app loading a local skill. Connecting Windsurf to the Adspirer MCP server, as described on this page, is unaffected. # Audit Conversion Tracking Source: https://www.adspirer.com/docs/api-reference/audit/audit-conversion-tracking /api-reference/openapi.json post /api/v1/tools/audit_conversion_tracking/execute Review your conversion tracking setup across ad platforms. Checks Meta Pixel (event volume, CAPI status, dedup, diagnostics), LinkedIn (conversion rules, CAPI, Insight Tag), and Google Ads (conversion actions, enhanced conversions, attribution). Returns a health score (0-100), grade (A-F), detailed findings, and suggestions with self-validation steps for each platform. Note: Some checks rely on API data availability and may not capture all configurations. Where findings are inconclusive, the tool provides guidance on how to verify directly in the platform's dashboard. Parameters: - platform (optional): 'google_ads', 'meta_ads', or 'linkedin_ads'. If omitted, reviews all connected platforms. - lookback_days (optional): 7, 14, 30, 60, or 90 days (default: 30) Execution time: ~5-15 seconds (includes live API calls to ad platforms). # Get Connections Status Source: https://www.adspirer.com/docs/api-reference/general/get-connections-status /api-reference/openapi.json post /api/v1/tools/get_connections_status/execute View connected ad accounts and OAuth connections. Shows all connected ad platforms (Google Ads, TikTok Ads, Meta Ads, LinkedIn Ads) with: - Connection status and account details - Primary account indicator - Option to switch primary account - Quick links to connect new platforms Use this tool when user asks about: - "how many accounts do I have" / "how many ad accounts" - "what accounts are connected" / "connected accounts" - "which account am I using" / "current account" - "show my connections" / "list my accounts" - "connection status" / "account status" - "what platforms do I have connected" - Account count, account list, or connection overview Do not use for: - Discovering campaigns, ads, or keywords (use discover_existing_assets) - Performance data or metrics (use performance tools) - Creating or managing campaigns This is specifically for OAuth connections and account management. # List Connected Accounts Source: https://www.adspirer.com/docs/api-reference/general/list-connected-accounts /api-reference/openapi.json post /api/v1/tools/list_connected_accounts/execute List all connected ad accounts across platforms. Returns account IDs, names, and platforms for all active accounts. Use this at the start of every conversation to know which accounts are available. CRITICAL for multi-account users (agencies): - Always call this first to discover available accounts - Use the returned account IDs when calling any platform tool - If user mentions a business name, match it to an account from this list Returns for each account: - platform: google_ads, meta_ads, tiktok_ads, linkedin_ads - account_id: Platform account ID (pass to tools as customer_id/ad_account_id/advertiser_id/account_id) - account_name: Display name - account_tier: primary, secondary, or active - status: connected, needs_reauth Zero API calls — reads directly from database. # Switch Primary Account Source: https://www.adspirer.com/docs/api-reference/general/switch-primary-account /api-reference/openapi.json post /api/v1/tools/switch_primary_account/execute Activate one or more ad accounts for a platform. Activated accounts are available for all ad operations. Pass a single account_id to activate one account, or pass account_ids (list) to activate multiple accounts for multi-account management. Use this tool when: - User wants to switch to a different ad account - User says "use my other account" or "activate these accounts" - User wants to manage multiple accounts simultaneously - User specifies which accounts to work with Accepts either account_id (single) or account_ids (list of IDs from list_connected_accounts). IMPORTANT: Returns updated connections list after switching. # Add Callout Extensions Source: https://www.adspirer.com/docs/api-reference/google-ads/add-callout-extensions /api-reference/openapi.json post /api/v1/tools/add_callout_extensions/execute Add callout extensions to a campaign. Callouts are short, non-clickable highlights that appear below your ad. They communicate quick trust signals and differentiators. **IMPORTANT RULES (from google-ads-creative-guidelines.md):** - Max 25 characters each - 4-8 callouts recommended - Should NOT be CTAs (no "click", "buy", "order", "call") - Should NOT end with periods **GOOD EXAMPLES:** - "Free Shipping" - "24/7 Support" - "No Code Required" - "30 Second Setup" - "Award Winning" **BAD EXAMPLES (will be rejected):** - "Click Now" (CTA word) - "Buy Today" (CTA word) - "Free Shipping." (ends with period) **Parameters:** - campaign_id: The campaign ID (REQUIRED). Get from list_campaigns. - callouts: List of callout text strings (REQUIRED). Each max 25 chars. - customer_id: Optional Google Ads customer ID **Execution time:** 2-5 seconds **When to use:** - User wants to add callouts/highlights to their campaign - User asks about extensions or ad enhancements - After creating a campaign, suggest adding callouts **Example:** User: "Add some callouts to my campaign" Agent: 1. Uses list_campaigns to get campaign_id 2. Uses add_callout_extensions with relevant callouts # Add Demand Gen Ad Group Source: https://www.adspirer.com/docs/api-reference/google-ads/add-demand-gen-ad-group /api-reference/openapi.json post /api/v1/tools/add_demandgen_ad_group/execute Add a new ad group with targeting and ads to an EXISTING Demand Gen campaign. Use this after create_demandgen_campaign to add additional ad groups. Each ad group can have: - **Different location targeting** (e.g., US cities vs India cities vs UAE cities) - **Different audience targeting** (e.g., marketing pros vs tech founders vs agency owners) - **Same or different ad creative** (headlines, descriptions, images, videos) **Reuse Existing Audiences:** To attach an existing audience (from Google Ads UI or a previous campaign), pass: - audience_segments.existing_audience_id: numeric audience ID - audience_segments.existing_audience_resource_name: full resource name **Create New Audiences:** To create a new audience from interest segments: - audience_segments.in_market_audience_ids: [80517, 80520] - audience_segments.affinity_audience_ids: [92948] Use search_audiences to find segment IDs. **Parameters:** - campaign_id: Demand Gen campaign ID (from create_demandgen_campaign or list_campaigns) - ad_group_name: Descriptive name - Same creative fields as create_demandgen_campaign (headlines, descriptions, images, etc.) - target_locations: Location targeting specific to this ad group - audience_segments: Audience targeting specific to this ad group **Execution time:** 10-20 seconds # Add Keywords Source: https://www.adspirer.com/docs/api-reference/google-ads/add-keywords /api-reference/openapi.json post /api/v1/tools/add_keywords/execute Add keywords to an existing ad group. ⚠️ **CRITICAL: Run `research_keywords` BEFORE using this tool!** # Add Negative Keywords Source: https://www.adspirer.com/docs/api-reference/google-ads/add-negative-keywords /api-reference/openapi.json post /api/v1/tools/add_negative_keywords/execute Add negative keywords to a campaign. Negative keywords prevent your ads from showing for certain searches. They help save budget by avoiding irrelevant clicks. **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - keywords: List of negative keywords to add - customer_id: Optional **Each keyword needs:** - text: The keyword phrase (e.g., "free", "cheap", "diy") - match_type: EXACT, PHRASE, or BROAD (default: BROAD) **Campaign-level vs Ad Group-level:** This adds negative keywords at CAMPAIGN level, affecting ALL ad groups. **Common negative keywords:** - "free", "cheap", "discount" (for premium brands) - "jobs", "salary", "careers" (for product companies) - "diy", "how to", "tutorial" (for service providers) **Execution time:** 2-4 seconds **Example:** User: "Block searches containing 'free' and 'cheap'" Agent: Uses add_negative_keywords with campaign_id and keywords list # Add PMax Audience Signal Source: https://www.adspirer.com/docs/api-reference/google-ads/add-pmax-audience-signal /api-reference/openapi.json post /api/v1/tools/add_pmax_audience_signal/execute Add an audience signal to an existing Performance Max campaign. Audience signals hint Google AI about who your ideal customers are. Uses in-market segments (actively researching), affinity segments (long-term interests), and custom audiences (remarketing lists, customer match). Use search_audiences tool first to discover relevant audience segment IDs. **Parameters:** - campaign_id: The PMax campaign ID - audience_config: Dict with segment IDs **Execution time:** 2-5 seconds # Add PMax Search Themes Source: https://www.adspirer.com/docs/api-reference/google-ads/add-pmax-search-themes /api-reference/openapi.json post /api/v1/tools/add_pmax_search_themes/execute Add search themes to an existing Performance Max campaign. Search themes hint Google AI about what customers search for. Max 50 per asset group. NOT keywords — no match types, no bids, no quality scores. **Best practices:** - Derive from keyword research results, business profile, or user input - Keep themes specific but not too narrow (2-5 words ideal) - Avoid generic themes like "buy stuff" or overly specific ones like "buy red nike air max 97 size 12" **Parameters:** - campaign_id: The PMax campaign ID - search_themes: List of theme strings to add **Execution time:** 2-5 seconds # Add Sitelinks Source: https://www.adspirer.com/docs/api-reference/google-ads/add-sitelinks /api-reference/openapi.json post /api/v1/tools/add_sitelinks/execute Add sitelink extensions to a campaign. Sitelinks are clickable links to specific pages on your website. Recommended 4-6 sitelinks per campaign. **CONSTRAINTS:** - link_text max 25 characters - description1 max 35 characters (optional) - description2 max 35 characters (required if description1 is set) **EXAMPLE SITELINKS:** `{` "link_text": "How It Works", "final_url": "https://example.com/how-it-works", "description1": "See the platform in action", "description2": "Step-by-step walkthrough" `}` `{` "link_text": "Pricing", "final_url": "https://example.com/pricing", "description1": "Affordable plans for all", "description2": "Start free today" `}` **Parameters:** - campaign_id: The campaign ID (REQUIRED). Get from list_campaigns. - sitelinks: List of sitelink objects with link_text, final_url, and optional descriptions. - customer_id: Optional Google Ads customer ID **Execution time:** 2-5 seconds **When to use:** - User wants to add sitelinks to their campaign - User asks about adding more links to ads - After creating a campaign, suggest adding sitelinks **Example:** User: "Add sitelinks to my campaign" Agent: 1. Uses list_campaigns to get campaign_id 2. Uses add_sitelinks with relevant page links # Add Structured Snippets Source: https://www.adspirer.com/docs/api-reference/google-ads/add-structured-snippets /api-reference/openapi.json post /api/v1/tools/add_structured_snippets/execute Add structured snippet extensions to a campaign. Structured snippets highlight specific aspects of your products/services. **VALID HEADERS:** - AMENITIES, BRANDS, COURSES, DEGREE_PROGRAMS, DESTINATIONS - FEATURED_HOTELS, INSURANCE_COVERAGE, MODELS, NEIGHBORHOODS - SERVICE_CATALOG, SHOWS, STYLES, TYPES **RULES:** - Header must be from predefined list - 3-10 values required per snippet - Each value max 25 characters **EXAMPLES:** For SaaS/Platform: Header: "Types" Values: ["Google Ads", "Meta Ads", "LinkedIn Ads", "TikTok Ads"] For Services: Header: "Services" (maps to SERVICE_CATALOG) Values: ["Campaign Launch", "Analytics", "Optimization", "Reporting"] For Brands: Header: "Brands" Values: ["Nike", "Adidas", "Puma", "New Balance"] **Parameters:** - campaign_id: The campaign ID (REQUIRED). Get from list_campaigns. - snippets: List of `{header, values}` objects (REQUIRED). - customer_id: Optional Google Ads customer ID **Execution time:** 2-5 seconds **When to use:** - User wants to add structured snippets - User asks to highlight product types, services, or brands - After creating a campaign, suggest adding snippets **Example:** User: "Add structured snippets showing our ad platform types" Agent: 1. Uses list_campaigns to get campaign_id 2. Uses add_structured_snippets with header "Types" and relevant values # Analyze Search Terms Source: https://www.adspirer.com/docs/api-reference/google-ads/analyze-search-terms /api-reference/openapi.json post /api/v1/tools/analyze_search_terms/execute Discover keyword opportunities and optimize match types by analyzing actual search terms. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Google Ads only - NOT available for TikTok. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 3):** - Identifies OPPORTUNITY keywords: Converting search terms NOT in your keyword list - Identifies NEGATIVE keywords: Expensive terms with zero conversions - Analyzes MATCH TYPE performance: Exact vs Phrase vs Broad efficiency - Provides specific recommendations with suggested bids and match types - Ranks opportunities by profit potential (not just ROAS) **Returns comprehensive keyword intelligence:** - Top 20 opportunity keywords with suggested bids and match types - Top 20 negative keyword candidates with wasted cost breakdown - Match type performance comparison (Exact/Phrase/Broad) - Broad→Exact conversion recommendations - Total opportunity value and wasted spend amounts - Actionable recommendations for immediate implementation 🔍 **What Search Term Mining Reveals:** **Opportunity Keywords (Money Left on Table):** - Search terms that ARE converting but you're NOT bidding on them directly - These are queries triggering your ads via Broad/Phrase match, but should be added as Exact keywords - Example: User searches "enterprise security software pricing" → converts → but you only have "security software" as keyword - **Action:** Add high-converting search terms as new keywords with suggested bids **Negative Keywords (Money Wasted):** - Search terms costing >$10 with ZERO conversions - Low-intent queries like "free", "download", "crack", "how to" - Example: "free security software download" → 120 clicks, $540 spent, 0 conversions - **Action:** Add as negative keywords to stop wasting budget **Match Type Optimization:** - Compares performance of Exact vs Phrase vs Broad match - Identifies Broad keywords that should be converted to Exact for better control - Example: Broad "security software" has 45% wasted spend, but top search terms have 20x ROAS - **Action:** Convert high-performing Broad keywords to Exact match **Parameters:** - lookback_days: 7, 30, 60, 90, or 120 days (default: 30) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - analysis_type: 'opportunities', 'negatives', 'match_types', 'all', or **'raw_report'** (default: 'all') - Use **'raw_report'** when the user wants to SEE their actual search terms — the words customers type into Google - force_refresh: true to trigger immediate API collection (default: false, uses cached data) - customer_id: Optional (uses connected account if omitted) - **campaign_id**: Optional — filter search terms to a specific campaign (get from list_campaigns) - **page**: Page number for raw_report pagination (default: 1) - **page_size**: Results per page for raw_report (1-100, default: 50) - **sort_by**: Sort for raw_report: 'cost' (default), 'clicks', 'impressions', 'conversions' - **min_clicks**: Minimum clicks filter for raw_report (default: 0) **Execution time:** 1-3 seconds (cached database query) **Data source:** search_term_daily_metrics table (updated nightly, 120-day retention) **⚡ RAW REPORT PAGINATION CONTRACT:** - When using analysis_type='raw_report', results are paginated - Check `pagination.has_more` — if true, call again with next `page` - Continue until `has_more` is false, then present consolidated results - Use `campaign_id` to focus on a specific campaign's search terms **Use this tool when:** - User asks "what keywords should I add?" - User wants to find wasted spend at keyword level - User asks "what should I add as negative keywords?" - User wants to improve match type efficiency - User asks "which Broad keywords should be Exact?" - User wants to discover hidden keyword opportunities - **User asks "show me my search terms" or "what are people searching for?"** → use analysis_type='raw_report' - **User asks "show me search terms for campaign X"** → use analysis_type='raw_report' with campaign_id ⚠️ **Platform Limitation:** This tool ONLY works for Google Ads. TikTok Ads does not provide search term data due to privacy restrictions. 📊 **AFTER calling this tool, help the user understand:** **Opportunity Keywords:** - **What it means:** These are winning search terms you're missing - **Profit potential:** Shows expected additional profit if added - **Suggested action:** Add as new keywords with recommended bid and match type - **Priority:** Start with highest opportunity_value (profit potential) **Example:** Search term: "enterprise security software pricing" - 8 conversions, $240 cost, $4,800 value - Opportunity Value: $4,560 profit potential - Suggested Bid: $6.00 (based on current CPC and ROAS) - Suggested Match Type: EXACT (high intent, proven converter) - **Action:** Add this as an Exact match keyword with $6 bid **Negative Keywords:** - **What it means:** These queries waste money and never convert - **Cost:** Total wasted spend on non-converting terms - **Common patterns:** "free", "download", "crack", "review", "how to" - **Action:** Add as negative keywords (campaign or account level) **Example:** Search term: "free security software" - 120 clicks, $540 wasted, 0 conversions - Reason: Low purchase intent (free) - **Action:** Add "free" as negative keyword at campaign level **Match Type Performance:** - **Exact:** Tightest control, lowest waste, highest ROAS (recommended) - **Phrase:** Moderate flexibility, some waste, decent ROAS - **Broad:** Most volume, highest waste, lowest ROAS (use sparingly) **Example Analysis:** - Exact: 450 keywords, ROAS 4.8x, 2% wasted spend ✅ - Phrase: 280 keywords, ROAS 3.2x, 8% wasted spend ⚠️ - Broad: 120 keywords, ROAS 1.8x, 45% wasted spend 🔴 **Quick Actions:** 1. Add top 5 opportunity keywords as Exact match 2. Block top 10 negative keywords at campaign level 3. Convert high-performing Broad keywords to Exact 4. Review Phrase keywords with >10% wasted spend **Visualization Tip:** For opportunity keywords, suggest creating a scatter plot (x=ROAS, y=Spend, size=conversions) to visualize profit potential. **Implementation Steps:** 1. Review top opportunities and negatives 2. Start with 5-10 new keywords (don't overwhelm account) 3. Add negatives in batches (test impact over 7 days) 4. Convert Broad→Exact gradually (monitor volume drop) 5. Re-run analysis monthly to discover new opportunities **Best Practices:** - Focus on opportunity_value (profit) not just ROAS - Start with Exact match for all new keywords (tightest control) - Add negatives at campaign level first (easier to undo than account level) - Monitor match type distribution: Aim for 60%+ Exact, 30% Phrase, 10% Broad - Review search terms every 2 weeks during active optimization 💬 **Community**: For keyword optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS # Analyze Wasted Spend Source: https://www.adspirer.com/docs/api-reference/google-ads/analyze-wasted-spend /api-reference/openapi.json post /api/v1/tools/analyze_wasted_spend/execute Analyze wasted ad spend and identify campaigns losing money or underperforming. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1):** - Identifies campaigns LOSING money (ROAS `<` 1.0x) - Identifies campaigns UNDERPERFORMING (1.0x ≤ ROAS `<` target) - Separates true waste from opportunity cost - Provides severity-based classification (CRITICAL/HIGH/MEDIUM) - Generates actionable recommendations with expected impact - Shows top performing campaigns for budget reallocation **Returns detailed analysis:** - Total wasted spend (campaigns with ROAS `<` 1.0) - Total underperforming spend (profitable but below target) - Campaign-by-campaign breakdown with severity levels - Specific recommendations (PAUSE/REDUCE/OPTIMIZE) - Quick actions for immediate implementation - Budget reallocation suggestions **Target ROAS Resolution (3-tier priority):** 1. Account goals table (user-set or API-pulled) 2. 90-day historical average ROAS 3. Default to 2.0x if no data available **Severity Levels:** - 🚨 CRITICAL: ROAS `<` 0.5x (losing money severely) - 🔴 HIGH: ROAS `<` 1.0x (unprofitable/breakeven) - 🟡 MEDIUM: 1.0x ≤ ROAS `<` target (profitable but underperforming) **Parameters:** - lookback_days: 7, 30, 60, 90, or 120 days (default: 30) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - target_roas: Optional override (e.g., 3.0 for 3.0x ROAS) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-3 seconds (cached database query) **Data source:** campaign_daily_metrics table (updated nightly) **Use this tool when:** - User asks "where is my money going?" - User wants to identify wasted spend - User wants to optimize campaign budgets - User asks which campaigns to pause/reduce - User wants to know which campaigns are losing money 📊 **AFTER calling this tool, help the user understand:** **Wasted vs. Underperforming:** - **Wasted Spend** = Actual losses (ROAS `<` 1.0, you're losing money) - **Underperforming Spend** = Opportunity cost (profitable but below target) **Example:** - Campaign A: Spent $1000, got $600 back (ROAS 0.6x) → $400 WASTED - Campaign B: Spent $1000, got $1500 back (ROAS 1.5x, target 3.0x) → $0 wasted, but $500 opportunity cost **Quick Actions (IMPORTANT — read severity context first):** - ⏳ LEARNING campaigns → Do NOT pause. Monitor for 14+ days before judging. - ❓ INSUFFICIENT_DATA campaigns → Need more spend before analysis is meaningful. - 🚨 CRITICAL campaigns (established, 14+ days, ZERO conversions) → Consider pausing - 🚨 CRITICAL campaigns (established, 14+ days, HAS conversions) → Review performance, verify revenue in ad platform before reducing budget - 🔴 HIGH severity (established, 14+ days) → Consider reducing budget by 50-70% - 🟡 MEDIUM → Optimize targeting, ad copy, landing pages - Top performers → Consider increasing budget ⚠️ **NEVER say "pause" for a campaign that has conversions.** Say "review" or "reduce budget" instead. ⚠️ **NEVER recommend pausing a campaign in LEARNING phase.** ⚠️ **If ALL campaigns are LEARNING or INSUFFICIENT_DATA, tell the user their account is too new for waste analysis and recommend checking back in 2 weeks.** ⚠️ **Consider campaign objective: brand awareness campaigns will not have ROAS data. This is normal.** ⚠️ **When data confidence is MEDIUM or LOW, soften all recommendations and add verification prompts.** **Visualization Tip:** For 10+ campaigns, suggest creating a treemap visualization to show wasted spend by campaign size. 💬 **Community**: For optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS # Create Ad Source: https://www.adspirer.com/docs/api-reference/google-ads/create-ad /api-reference/openapi.json post /api/v1/tools/create_ad/execute Create a new Responsive Search Ad (RSA) in an existing ad group. Useful for A/B testing different ad copy or adding variation to an ad group. **Parameters:** - ad_group_id: The ad group to add the ad to (REQUIRED) - headlines: 3-15 headlines (REQUIRED, max 30 chars each) - descriptions: 2-4 descriptions (REQUIRED, max 90 chars each) - final_urls: Landing page URLs (REQUIRED, at least one) - path1: Optional display path 1 (max 15 chars) - path2: Optional display path 2 (max 15 chars) - customer_id: Optional **Execution time:** 3-5 seconds **New ad goes through Google's review process.** **Example:** User: "Create a new ad to test different messaging" Agent: 1. Gets ad_group_id from get_campaign_structure 2. Prepares headlines and descriptions 3. Creates new ad with create_ad # Create Demand Gen Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/create-demand-gen-campaign /api-reference/openapi.json post /api/v1/tools/create_demandgen_campaign/execute 🔄 LONG-RUNNING TOOL: Creates a Demand Gen campaign across ALL Google channels — YouTube, Discover, Gmail, Display, and Maps. Emits MCP progress updates during creation (typically 10-20 seconds). ⚠️ CRITICAL WARNING ⚠️ - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying 🌐 **Demand Gen Campaign Channels (ALL enabled by default):** ✅ YouTube In-Feed (search results & related videos) ✅ YouTube In-Stream (before/during/after videos) ✅ YouTube Shorts (Shorts feed) ✅ Gmail (Promotions & Social tabs) ✅ Discover (Google Discover feed) ✅ Display (Google Display Network) ❌ Maps (opt-in, disabled by default) # Create PMax Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/create-pmax-campaign /api-reference/openapi.json post /api/v1/tools/create_pmax_campaign/execute 🔄 LONG-RUNNING TOOL: Creates a Google Performance Max campaign with validated images. Emits MCP progress updates during authentication, asset upload, and campaign creation (typically 15-30 seconds). Progress stages: validate → commit. ⚠️ CRITICAL PREREQUISITES: 1. MUST have valid asset_bundle_id from validate_and_prepare_assets tool OR existing_image_ids from discover_existing_assets 2. MUST have all campaign text details from user 3. Creates REAL campaigns that cost REAL money 4. Call ONLY ONCE per campaign - do NOT retry automatically 🎥 **VIDEOS ARE OPTIONAL BUT RECOMMENDED:** - Videos significantly improve PMAX performance (higher CTR, better engagement) - **Always ask the user**: "Would you like to add YouTube videos to this campaign?" - If yes: validate with `validate_video` tool, then include `youtube_video_ids` parameter - If no: proceed without videos (campaigns work fine either way) - See STEP 3.5 below for complete video guidance ⚠️ GOOGLE ADS POLICY NOTE: Avoid keywords related to health conditions, medical treatments, financial hardship, or political topics. These may trigger policy violations. Use general service terms instead. Example: Use "senior care services" not "nursing care", "home services" not "medical services" # Create Search Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/create-search-campaign /api-reference/openapi.json post /api/v1/tools/create_search_campaign/execute 🔄 LONG-RUNNING TOOL: Creates a Google Ads Search campaign with full structure. Emits MCP progress updates during authentication and campaign creation (typically 5-10 seconds). Progress stages: validate → commit. ⚠️ CRITICAL WARNING ⚠️ - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying ⚠️ GOOGLE ADS POLICY NOTE: Avoid keywords related to health conditions, medical treatments, financial hardship, or political topics. These may trigger policy violations. Use general service terms instead. Example: Use "senior care services" not "nursing care", "home services" not "medical services" # Create YouTube Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/create-youtube-campaign /api-reference/openapi.json post /api/v1/tools/create_youtube_campaign/execute 🔄 LONG-RUNNING TOOL: Creates a YouTube Video campaign using Google Ads Demand Gen format with YouTube-only placements. Emits MCP progress updates during authentication and campaign creation (typically 10-20 seconds). Progress stages: validate → commit. ⚠️ CRITICAL WARNING ⚠️ - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying ⚠️ CRITICAL PREREQUISITE: - MUST validate the YouTube video first using validate_video tool - Video must be public or unlisted on YouTube (NOT private) 🎬 **YouTube Campaign Placements:** ✅ YouTube In-Feed (appears in search results & related videos) ✅ YouTube In-Stream (plays before/during/after videos) ✅ YouTube Shorts (appears in Shorts feed) ❌ Gmail (disabled for YouTube campaigns) ❌ Discover (disabled for YouTube campaigns) ❌ Display (disabled for YouTube campaigns) # Discover Existing Assets Source: https://www.adspirer.com/docs/api-reference/google-ads/discover-existing-assets /api-reference/openapi.json post /api/v1/tools/discover_existing_assets/execute 🔍 Discover existing assets in the Google Ads account (images, sitelinks, callouts, structured snippets). **Phase 0: Asset Discovery** - Read-only tool, safe to call anytime. # Explain Performance Anomaly Source: https://www.adspirer.com/docs/api-reference/google-ads/explain-performance-anomaly /api-reference/openapi.json post /api/v1/tools/explain_performance_anomaly/execute Explain why a performance metric changed using statistical analysis and historical context. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Uses statistical analysis only (no ML models). 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 4):** - Explains why metrics changed (ROAS, CTR, CPC, conversions, conversion rate) - Compares current period to historical averages (30/60/90-day) - Identifies contributing factors with severity levels - Detects campaign changes (paused, new, budget changes) - Finds similar historical periods (seasonality detection) - Provides actionable recommendations to address issues **Returns comprehensive anomaly explanation:** - Current metric value vs historical averages - Deviation percentages (how much it changed) - Contributing factors: - CPC changes (>15% = auction competition shifts) - Conversion rate changes (>10% = landing page/seasonality issues) - Campaign changes (paused high-performers, new campaigns, budget changes) - Day-of-week patterns (weekend vs weekday effects) - Similar historical periods for context - Assessment (normal variation vs requires action) - Specific recommendations to fix the issue 🔍 **How Anomaly Detection Works:** **Historical Comparison:** - Compares current period to 30/60/90-day averages - ±15% deviation considered "normal variation" - >15% deviation flagged as requiring attention **Contributing Factor Detection:** 1. **CPC Changes** (>15% threshold) - Increased CPC = auction competition increased - Decreased CPC = auction competition decreased or bid adjustments 2. **Conversion Rate Changes** (>10% threshold) - Decreased = landing page issues, seasonality, audience quality - Increased = landing page improved, better targeting 3. **Campaign Changes:** - Paused high-performers (ROAS > 3.0x) = lost revenue driver - New campaigns (>$1K spend) = learning phase affecting overall performance - Budget changes (>20%) = delivery and auction participation affected 4. **Day-of-Week Patterns:** - Weekend-heavy periods often show different performance - Normal for B2C (higher weekend conversion) - Normal for B2B (lower weekend conversion) 5. **Seasonality Detection:** - Finds similar historical periods (±10% metric value) - Helps identify if drop is seasonal vs real issue **Parameters:** - metric: 'roas', 'ctr', 'cpc', 'conversions', 'conversion_rate' (REQUIRED) - period_start: Start date in YYYY-MM-DD format (REQUIRED) - period_end: End date in YYYY-MM-DD format (REQUIRED, max 30 days period) - customer_id: Optional (uses connected account if omitted) **Execution time:** 2-4 seconds (statistical analysis + database queries) **Data source:** campaign_daily_metrics table (updated nightly, 120-day retention) **Analysis method:** Statistical comparison (no ML models) **Trigger:** Reactive (user asks "why?"), not proactive alerts **Use this tool when:** - User asks "why did my ROAS drop?" - User asks "why did my CTR increase?" - User notices unexpected metric changes - User wants to understand performance fluctuations - After seeing performance changes in dashboards 📊 **AFTER calling this tool, help the user understand:** **Normal vs Abnormal Variation:** - **Normal**: ±15% deviation, typical day-of-week/seasonal patterns - **Abnormal**: >15% deviation with specific contributing factors **Severity Levels:** - 🔴 **HIGH**: >25% change with clear cause (CPC spike, campaign paused) - 🟡 **MEDIUM**: 15-25% change or multiple minor factors - 🟢 **LOW**: `<`15% change, likely normal variation **Example Interpretation:** "Your ROAS dropped 33% from 4.2x to 2.8x. This was caused by two high-severity factors: 1. CPC increased 25% (auction competition spike during holiday season) 2. Your top campaign 'Brand - Exact' was paused, losing $240/day in high-ROAS revenue This is NOT normal variation - these are actionable issues. Recommendations: - Reduce bids by 10-15% to counter CPC inflation - Re-enable 'Brand - Exact' campaign if budget allows - Review landing page conversion rate (also dropped 12%)" **Similar Period Context:** If tool finds similar historical periods, explain seasonality: "Your ROAS was similarly low (2.7x) on December 18, 2024, which was also during the holiday shopping season. This suggests some of the drop is seasonal, but the campaign pause is amplifying the effect." **Quick Actions:** Based on contributing factors, prioritize: 1. **Campaign paused** → Re-enable high performers immediately 2. **CPC spike** → Adjust bids, improve Quality Score 3. **Conversion rate drop** → Review landing page, check for bugs 4. **Budget changes** → Monitor delivery as it stabilizes 5. **Weekend effect** → Normal variation, no action needed **Visualization Tip:** Suggest creating a line chart showing the metric over time with 30-day average band and annotations for detected factors (e.g., "Campaign paused here", "CPC spike started here"). **Important Notes:** - This is REACTIVE explanation, not proactive monitoring - Max 120-day historical lookback (database retention limit) - Uses simple statistics (mean, variance), no ML predictions - Focus on actionable factors user can control - Consider seasonality when interpreting results **Best Practices:** - Run this tool when you notice >15% metric changes - Compare multiple time periods to confirm trends - Cross-reference with other tools (wasted spend, budget optimizer) - Use for post-mortem analysis of performance changes - Help user distinguish normal variation from real issues 💬 **Community**: For anomaly analysis discussions, visit our Discord: https://discord.gg/dH3Qt4YS # Get Benchmark Context Source: https://www.adspirer.com/docs/api-reference/google-ads/get-benchmark-context /api-reference/openapi.json post /api/v1/tools/get_benchmark_context/execute Get industry benchmark context for AI-powered recommendations. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 5):** - Generates contextual benchmark data for the user's business - Combines business profile with industry benchmarks - Provides recommended ROAS targets based on vertical - Returns formatted context for AI prompts **Returns benchmark context:** - Business vertical and size context - Industry-specific ROAS benchmarks (typical, good, excellent) - CTR benchmarks by industry - CPC expectations for the vertical - Seasonality considerations - Custom recommendations based on profile **Industry Benchmarks Included:** | Vertical | Typical ROAS | Good ROAS | Excellent ROAS | |----------|--------------|-----------|----------------| | Retail | 4.0x | 6.0x | 8.0x | | Services | 3.0x | 5.0x | 7.0x | | Technology | 3.5x | 5.5x | 8.0x | | Healthcare | 2.5x | 4.0x | 6.0x | | Finance | 5.0x | 8.0x | 12.0x | | Education | 2.0x | 3.5x | 5.0x | **Parameters:** - **include_recommendations**: Include performance recommendations (default: true) - **customer_id**: Optional (uses connected account if omitted) **Use this tool when:** - Before providing performance analysis - When comparing user's metrics to industry standards - User asks "how am I doing compared to others?" - You need context for optimization recommendations **Integration with Other Tools:** Call this BEFORE or AFTER these tools for enhanced recommendations: - `analyze_wasted_spend` - Contextualize waste against industry norms - `optimize_budget_allocation` - Use industry-appropriate ROAS targets - `get_campaign_performance` - Compare metrics to benchmarks - `explain_performance_anomaly` - Understand if changes are industry-wide **Execution time:** 1-2 seconds (profile lookup + benchmark calculation) # Get Business Profile Source: https://www.adspirer.com/docs/api-reference/google-ads/get-business-profile /api-reference/openapi.json post /api/v1/tools/get_business_profile/execute Get the user's business profile for contextual recommendations. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 5):** - Retrieves the user's saved business profile - Returns business vertical, size, goals, target audience - Provides context for more relevant recommendations - Shows profile source (user-set, inferred, or none) **Returns business context:** - Business vertical (retail, services, technology, etc.) - Business size (small, medium, large) - Primary goal (leads, sales, awareness, traffic) - Target audience description - Geographic focus (local, regional, national, international) - Seasonality patterns - Profile confidence level **Use this tool when:** - You need business context for recommendations - Before providing industry-specific advice - User asks "what type of business am I?" - You want to personalize optimization suggestions **If no profile exists:** - Use `infer_business_profile` to automatically detect from campaign data - Or ask user to provide business details via `save_business_profile` **Execution time:** 1-2 seconds (database lookup) # Get Campaign Performance Source: https://www.adspirer.com/docs/api-reference/google-ads/get-campaign-performance /api-reference/openapi.json post /api/v1/tools/get_campaign_performance/execute Analyze Google Ads campaign performance with comprehensive insights and recommendations. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns detailed analysis:** - Campaign structure and ad group organization - Keyword performance with quality scores and match types - Ad group performance breakdown - Performance metrics (CTR, conversions, CPC, cost, ROAS) - Optimization recommendations with actionable insights - Performance trends (last 7 days) **Parameters:** - lookback_days: 7, 30, 60, 90, or 120 days (default: 30) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - customer_id: Optional (uses connected account if omitted) **Execution time:** 2-5 seconds (direct backend API call) **Data source:** Cached database (updated nightly via metrics collection) **Use this tool to:** - Review current campaign performance - Identify optimization opportunities - Get data-driven recommendations - Analyze keyword and ad effectiveness - Understand what's working and what needs improvement 📊 **AFTER calling this tool, provide these insights to the user:** **How to Interpret Metrics:** - **CTR (Click-Through Rate):** Industry average is 3-5% for search ads - Above 5%: Excellent ad relevance - Below 2%: Consider improving ad copy or targeting - **Conversion Rate:** Industry average is 2-5% - Low CR + High CTR = Landing page issue - Low CR + Low CTR = Ad/targeting issue - **CPA (Cost Per Acquisition):** Compare to your target CPA - Track the trend over time - Adjust bids if CPA is consistently too high 💡 **Optimization Tips:** - Wait at least 2 weeks before making major changes (learning phase) - Focus on high-performing keywords and pause low performers - Test different ad copy variations (A/B testing) - Adjust bids based on device/location performance - Review search terms report for negative keyword opportunities 💬 **Community**: For optimization discussions and tips, visit our Discord: https://discord.gg/dH3Qt4YS # Get Campaign Structure Source: https://www.adspirer.com/docs/api-reference/google-ads/get-campaign-structure /api-reference/openapi.json post /api/v1/tools/get_campaign_structure/execute Get campaign structure with ad groups, keywords, ads, and extensions. Supports pagination for large campaigns. This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns campaign hierarchy (paginated by ad groups):** - Campaign details (name, status, budget, bidding strategy) - Ad groups with their settings (paginated — default 5 per page) - Keywords per ad group (including match types, bids, status) - Ads per ad group (including RSA headlines/descriptions, ad strength) - Negative keywords per ad group - Campaign-level extensions and negative keywords (on page 1 only) - Pagination metadata (page, total_pages, has_more) - Summary counts (total ad groups, keywords, ads across ALL pages) **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - customer_id: Optional (uses connected account if omitted) - page: Page number, 1-based (default: 1) - page_size: Ad groups per page, 1-50 (default: 5) - ad_group_id: Optional — fetch only this single ad group (bypasses pagination) - include: What detail per ad group: 'all' (default), 'summary' (counts only), 'keywords', 'ads' **⚡ PAGINATION CONTRACT (IMPORTANT FOR AI AGENTS):** - The response includes `pagination.has_more` — if true, you MUST call again with `page` incremented - Continue calling until `has_more` is false - Then consolidate all pages and present the complete campaign structure to the user - The `summary` section is always included and shows total counts across ALL ad groups (not just the current page) - Extensions and campaign-level negative keywords are only returned on page 1 - Use `ad_group_id` to drill into a single ad group when the user asks about a specific one - Use `include='summary'` for a quick overview without nested keyword/ad data **Execution time:** 3-8 seconds per page (multiple API queries) **Use this tool when:** - User wants to update an existing campaign - User wants to see current keywords/ads - User wants to add extensions to existing campaign - User says "show me what's in this campaign" - Before making any updates to a campaign **Important IDs returned:** - campaign.id - For campaign-level updates (budget, status) - ad_groups[].id - For adding keywords/ads - keywords[].id - For keyword updates (status, bids) - ads[].id - For ad content updates **Example flow:** 1. User: "I want to update my campaign" 2. Agent: Uses list_campaigns to show all campaigns 3. User: Selects campaign "Summer Sale 2025" 4. Agent: Uses get_campaign_structure with that campaign_id 5. If has_more=true, agent calls again with page=2, page=3, etc. 6. Agent: Shows consolidated structure and asks what to update 7. User: "Change the headlines" 8. Agent: Uses update_ad_headlines with the ad_id from structure # Get Campaign Targeting Source: https://www.adspirer.com/docs/api-reference/google-ads/get-campaign-targeting /api-reference/openapi.json post /api/v1/tools/get_campaign_targeting/execute Get location/geo targeting for a Google Ads campaign. This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns location targeting details:** - Targeted locations (cities, states, countries, metros the campaign targets) - Excluded locations (negative geo targets) - Bid modifiers per location (if set) - Location type (Country, State, City, Metro, etc.) - Summary counts (targeted, excluded, total) **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-3 seconds (single API query) **Use this tool when:** - User asks "where is this campaign targeting?" or "what locations?" - User wants to see geo targeting for a campaign - User asks "what countries/cities/states does my campaign target?" - Before recommending location targeting changes - To verify location setup after campaign creation **Returns for each location:** - name: Short location name (e.g., "New York") - canonical_name: Full hierarchical name (e.g., "New York,New York,United States") - country_code: ISO country code (e.g., "US") - target_type: Location type (Country, State, City, County, Metro, etc.) - is_negative: true if this location is EXCLUDED - bid_modifier: Bid adjustment for this location (null if no modifier) **Example flow:** 1. User: "What locations does my Diamond Ring campaign target?" 2. Agent: Uses get_campaign_targeting with campaign_id 3. Returns: Targeted: United States, New York, Los Angeles; Excluded: none # Get PMax Audience Signals Source: https://www.adspirer.com/docs/api-reference/google-ads/get-pmax-audience-signals /api-reference/openapi.json post /api/v1/tools/get_pmax_audience_signals/execute Get current audience signals for a Performance Max campaign. Returns audience signal resource names and associated audience resource references. **Use when:** - User wants to see what audience signals are on their PMax campaign - Before adding new signals - To get resource_name for removal **Parameters:** - campaign_id: The PMax campaign ID **Execution time:** 1-2 seconds # Get PMax Search Themes Source: https://www.adspirer.com/docs/api-reference/google-ads/get-pmax-search-themes /api-reference/openapi.json post /api/v1/tools/get_pmax_search_themes/execute Get current search themes for a Performance Max campaign. Returns each search theme's text and approval_status (APPROVED, LIMITED, DISAPPROVED, UNDER_REVIEW). **Use when:** - User wants to see what search themes are set on their PMax campaign - Before adding new themes (to check current count — max 50) - To verify theme approval status after adding **Parameters:** - campaign_id: The PMax campaign ID (get from list_campaigns) **Execution time:** 1-2 seconds # Get Usage Status Source: https://www.adspirer.com/docs/api-reference/google-ads/get-usage-status /api-reference/openapi.json post /api/v1/tools/get_usage_status/execute Get your current usage status with interactive quota widget. This tool shows your tool call usage for the current billing period and provides upgrade options if needed. **Returns:** - Current usage (calls used / limit) - Subscription tier (Free, Plus, Pro, Enterprise) - Days until quota reset - Upgrade options with pricing **Use this tool when:** - User asks "how many calls do I have left?" - User asks about their subscription or quota - User wants to check their usage - User asks about upgrading their plan **Widget Display (ChatGPT):** In ChatGPT, this tool displays an interactive widget with: - Visual progress bar showing usage - Upgrade buttons that open Stripe checkout - Plan comparison with pricing **Note:** This tool is READ-ONLY and safe to call anytime. # Help User Upload Source: https://www.adspirer.com/docs/api-reference/google-ads/help-user-upload /api-reference/openapi.json post /api/v1/tools/help_user_upload/execute Show user instructions for uploading images to postimages.org for Performance Max campaigns. ⚠️ CALL THIS FIRST when user wants to create a PMax campaign! # Infer Business Profile Source: https://www.adspirer.com/docs/api-reference/google-ads/infer-business-profile /api-reference/openapi.json post /api/v1/tools/infer_business_profile/execute Automatically infer business profile from campaign data using AI analysis. ⚠️ IMPORTANT: This tool ANALYZES data but may SAVE a profile if confidence is high. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 5):** - Analyzes campaign names, keywords, and ad copy - Uses Claude AI to classify business type - Infers business vertical, size, goals, and audience - Returns confidence level (high, medium, low) - Auto-saves if confidence is HIGH, asks confirmation for LOW **Inference Process:** 1. Collects campaign names and keywords from Google Ads 2. Analyzes patterns (B2B vs B2C, product vs service) 3. Uses AI to classify business vertical 4. Estimates business size from ad spend 5. Identifies primary goals from campaign types **Confidence Levels:** - **HIGH** (≥0.8): Auto-saves profile, high certainty - **MEDIUM** (0.5-0.8): Saves profile, reasonable certainty - **LOW** (`<`0.5): Returns suggestion, asks user to confirm **Parameters:** - **force_save**: Set to true to save even low-confidence profiles - **customer_id**: Optional (uses connected account if omitted) **Returns:** - Inferred business profile (vertical, size, goal, audience) - Confidence level and reasoning - Whether profile was saved or needs confirmation - Suggested confirmation prompt for low-confidence results **Use this tool when:** - User doesn't have a business profile set - User asks "analyze my business" - You need business context but none exists - After user connects a new Google Ads account **Example Flow:** 1. Call `get_business_profile` - returns no profile 2. Call `infer_business_profile` - analyzes campaigns 3. If HIGH confidence: Profile saved automatically 4. If LOW confidence: Ask user to confirm with suggested prompt **Execution time:** 3-8 seconds (AI analysis + optional save) # List Campaign Extensions Source: https://www.adspirer.com/docs/api-reference/google-ads/list-campaign-extensions /api-reference/openapi.json post /api/v1/tools/list_campaign_extensions/execute List all extensions (sitelinks, callouts, structured snippets) for a campaign. Returns a summary of all extension types configured on the campaign. **Parameters:** - campaign_id: The campaign ID (REQUIRED). Get from list_campaigns. - customer_id: Optional Google Ads customer ID **Returns:** - Sitelinks: Clickable links with text, URL, and descriptions - Callouts: Non-clickable text highlights - Structured Snippets: Header + values combinations **Execution time:** 1-2 seconds (read-only) **When to use:** - User asks "what extensions do I have?" - Before adding extensions, check what already exists - Auditing campaign setup **Example:** User: "Show me the extensions on my campaign" Agent: 1. Uses list_campaigns to get campaign_id 2. Uses list_campaign_extensions to see all extensions # List Campaigns Source: https://www.adspirer.com/docs/api-reference/google-ads/list-campaigns /api-reference/openapi.json post /api/v1/tools/list_campaigns/execute List all Google Ads campaigns for the connected account. ⚠️ CRITICAL: Call this tool BEFORE creating new campaigns to ask the user: "Would you like to create a new campaign or update an existing one?" This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns:** - List of all campaigns with IDs, names, status, type, budget - 30-day performance metrics for each campaign (impressions, clicks, cost, conversions) - Total campaign count **Parameters:** - status_filter: ENABLED, PAUSED, or ALL (optional, default: ALL) - campaign_type: SEARCH, PERFORMANCE_MAX, DISPLAY, SHOPPING, or ALL (optional, default: ALL) - customer_id: Optional (uses connected account if omitted) **Execution time:** 2-5 seconds (direct Google Ads API call) **Campaign Management Guidelines:** BEFORE Starting Any Campaign Work: 1. ALWAYS use `list_campaigns` first 2. Ask user: "Would you like to create a new campaign or update an existing one?" 3. If updating, use `get_campaign_structure` to see full details User Intent Mapping: | User Says | Agent Action | |-----------|--------------| | "Create a campaign for X" | List existing first, then ask create vs update | | "Change the budget" | Get structure, then use update tools | | "Add more keywords" | Get structure, then add keywords | | "Update my ads" | Get structure, then update ad content | | "Pause the campaign" | Use pause_campaign tool | **Use this tool to:** - View all existing campaigns before creating new ones - Find campaign IDs for update operations - Get a quick overview of account structure - Identify active vs paused campaigns # Optimize Budget Allocation Source: https://www.adspirer.com/docs/api-reference/google-ads/optimize-budget-allocation /api-reference/openapi.json post /api/v1/tools/optimize_budget_allocation/execute Optimize budget allocation across campaigns using linear programming to maximize conversions. ⚠️ IMPORTANT: This tool retrieves READ-ONLY optimization recommendations. Safe to call multiple times. Does NOT automatically change budgets. 🎯 **What This Tool Does (Performance Agent - Phase 1):** - Uses linear programming to optimize budget distribution - Maximizes total conversions while respecting constraints - Provides current vs optimized allocation comparison - Categorizes campaigns into actions: PAUSE/SCALE/REDUCE/MAINTAIN - Shows expected conversion lift from optimization - Generates specific recommendations with budget amounts **Returns detailed optimization plan:** - Current allocation (what you have now) - Optimized allocation (what you should have) - Expected conversion lift (absolute and percentage) - Campaign-by-campaign actions with reasoning - Budget change amounts and percentages - Specific implementation recommendations **Optimization Algorithm:** Uses scipy linear programming with constraints: 1. Sum of budgets = total_budget (you don't overspend) 2. Only campaigns with ROAS >= target get significant budget 3. Min budget per campaign >= min_daily_budget (or $0 to pause) 4. Max change per campaign `<`= ±max_change_percentage (avoid drastic shifts) **Target ROAS Resolution (3-tier priority):** 1. User override (if target_roas parameter provided) 2. Account goals table (user-set or API-pulled) 3. 90-day historical average ROAS 4. Default to 1.0x (breakeven) if no data **Configuration Parameters:** - **total_budget**: Total monthly budget to allocate (REQUIRED) - **lookback_days**: 7, 30, 60, 90, or 120 days (default: 30) - **start_date**: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - **end_date**: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. - **target_roas**: Optional override (e.g., 3.0 for 3.0x) - **max_change_percentage**: 0.0-1.0 (default: 0.5 = ±50%) * 0.3 = Conservative (±30% change, minimal disruption) * 0.5 = Balanced (±50% change, standard optimization) * 0.7 = Aggressive (±70% change, fast scaling) - **min_daily_budget**: Minimum $ per campaign (default: $5.00, or $0.00 to allow pausing) - **customer_id**: Optional (uses connected account if omitted) **Execution time:** 1-5 seconds (depends on campaign count) **Data source:** campaign_daily_metrics table (updated nightly) **Use this tool when:** - User wants to optimize budget allocation - User asks "how should I allocate my budget?" - User wants to maximize conversions with current spend - User wants data-driven budget recommendations - After running wasted spend analysis (natural next step) 📊 **AFTER calling this tool, help the user understand:** **Campaign Actions:** - **PAUSE**: Campaigns below target ROAS, losing money (ROAS `<` target) - **SCALE**: High performers, increase budget by X% (top conversion rates) - **REDUCE**: Underperformers, decrease budget by X% (low efficiency) - **MAINTAIN**: Steady performers, keep current budget (±5% change) **Expected Impact:** - Current conversions: What you get now - Optimized conversions: What you could get - Conversion lift: Additional conversions (+X%) **Example Interpretation:** "Implementing this optimization will increase your conversions by 45 (+18.8%) without spending more money. You should scale 'Brand - Exact' campaign by $2,250/month and pause 'Display - Broad' to free up $3,000/month." **Implementation Steps:** 1. Review recommended changes carefully 2. Start with campaigns marked CRITICAL (pause/scale first) 3. Apply changes gradually if user is risk-averse 4. Monitor performance for 7-14 days after changes 5. Re-run optimization monthly for continuous improvement **Important Notes:** - This is a RECOMMENDATION tool, not automated budget application - User must review and apply changes manually in Google Ads - Avoid large changes (>50%) for campaigns in learning phase (`<`7 days) - Consider seasonality when interpreting results - Re-optimize every 30 days as performance changes **Visualization Tip:** For 5+ campaigns, suggest creating a grouped bar chart showing current vs optimized budgets side-by-side. **Best Practices:** - Start conservative (max_change_percentage=0.3) for first optimization - Increase aggressiveness (0.5-0.7) as you gain confidence - Use longer lookback_days (60-90) during seasonal changes - Set realistic target_roas (start with 1.0x breakeven, increase gradually) 💬 **Community**: For optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS # Pause Ad Source: https://www.adspirer.com/docs/api-reference/google-ads/pause-ad /api-reference/openapi.json post /api/v1/tools/pause_ad/execute Pause an ad to stop it from showing. This is REVERSIBLE using resume_ad. **Parameters:** - ad_id: The ad ID to pause (REQUIRED) - ad_group_id: The ad group ID (REQUIRED) - customer_id: Optional **Execution time:** 1-2 seconds **When to use:** - User says "pause this ad", "stop this ad" - User wants to A/B test by pausing one ad - Ad is underperforming and needs a break - Making changes before re-enabling **Example:** User: "Pause my underperforming ad" Agent: 1. Uses get_campaign_structure to find ad_id and ad_group_id 2. Uses pause_ad to stop the ad # Pause Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/pause-campaign /api-reference/openapi.json post /api/v1/tools/pause_campaign/execute Quickly pause a running campaign. Pausing a campaign stops all ads from showing immediately. This is REVERSIBLE using resume_campaign. **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-2 seconds **Returns:** - Campaign name - Before status (e.g., ENABLED) - After status (PAUSED) - Confirmation message **When to use:** - User says "pause the campaign", "stop the ads", "turn it off" - User wants to temporarily stop spending - User needs to make changes before ads continue **Example:** User: "Pause my summer sale campaign" Agent: Uses pause_campaign with the campaign_id # Remove Keywords Source: https://www.adspirer.com/docs/api-reference/google-ads/remove-keywords /api-reference/openapi.json post /api/v1/tools/remove_keywords/execute Remove keywords from an ad group. **Parameters:** - ad_group_id: The ad group containing the keywords (REQUIRED) - keyword_ids: List of keyword IDs to remove (REQUIRED) - customer_id: Optional **Get keyword_ids from:** Use get_campaign_structure to see all keywords with their IDs. **WARNING: This is PERMANENT and IRREVERSIBLE.** Keywords removed cannot be recovered. Always confirm with the user first. **Execution time:** 2-4 seconds **Example:** User: "Remove the underperforming keywords" Agent: 1. Uses get_campaign_structure to show keywords 2. Confirms with user which ones to remove 3. Uses remove_keywords with the keyword_ids # Remove Negative Keywords Source: https://www.adspirer.com/docs/api-reference/google-ads/remove-negative-keywords /api-reference/openapi.json post /api/v1/tools/remove_negative_keywords/execute Remove negative keywords from a campaign. ⚠️ **WARNING: This is PERMANENT and IRREVERSIBLE.** Once removed, the negative keywords cannot be recovered. **Parameters:** - campaign_id: The campaign ID (REQUIRED) - keyword_ids: List of negative keyword IDs to remove (REQUIRED) - customer_id: Optional **Get keyword IDs from:** Use `get_campaign_structure` to see all campaign negative keywords with their IDs. Look for the "Campaign Negative Keywords" section. **When to use:** - Remove accidentally added negative keywords - Clean up obsolete negative keywords - Fix over-blocking that's limiting traffic **Execution time:** 2-4 seconds **Example:** User: "Remove the negative keyword 'discount' I added by mistake" Agent: 1. Uses get_campaign_structure to find the keyword ID 2. Uses remove_negative_keywords with campaign_id and keyword_ids # Remove PMax Audience Signal Source: https://www.adspirer.com/docs/api-reference/google-ads/remove-pmax-audience-signal /api-reference/openapi.json post /api/v1/tools/remove_pmax_audience_signal/execute Remove a specific audience signal from a Performance Max campaign. Use get_pmax_audience_signals first to get the signal_resource_name. **Parameters:** - campaign_id: The PMax campaign ID - signal_resource_name: Resource name from get_pmax_audience_signals **Execution time:** 2-5 seconds # Remove PMax Search Themes Source: https://www.adspirer.com/docs/api-reference/google-ads/remove-pmax-search-themes /api-reference/openapi.json post /api/v1/tools/remove_pmax_search_themes/execute Remove specific search themes from a Performance Max campaign. Matches themes by text (case-insensitive). Use get_pmax_search_themes first to see current themes. **Parameters:** - campaign_id: The PMax campaign ID - themes_to_remove: List of theme text strings to remove **Execution time:** 2-5 seconds # Research Keywords Source: https://www.adspirer.com/docs/api-reference/google-ads/research-keywords /api-reference/openapi.json post /api/v1/tools/research_keywords/execute Research high-intent keywords using Google Keyword Planner API. ⚠️ IMPORTANT: This is a READ-ONLY tool. Safe to call multiple times. 🎯 **What This Tool Does:** - Researches keywords via Google Keyword Planner API - Returns keywords with real CPC data, search volume, and competition metrics - Groups keywords by commercial intent (HIGH/MEDIUM/LOW based on dynamic CPC thresholds) - Selects top 15-20 keywords optimized for conversions - Provides budget recommendations based on actual keyword costs **When to Use:** - BEFORE creating a Google Search campaign - When you need data-driven keyword insights - To understand keyword costs and search volume - To get budget recommendations **Parameters:** - business_description (required): What the business sells/offers - website_url (optional): Business website for better keyword suggestions - target_location (optional): Geographic target (default: "United States") - seed_keywords (optional): 5-10 seed keywords (will auto-extract if not provided) - customer_id (optional): Google Ads account ID **Returns:** - Keyword table with dynamic CPC thresholds (adapts to any industry) - HIGH/MEDIUM/LOW intent grouping - Budget recommendations (Conservative/Moderate/Aggressive) - Top 15-20 recommended keywords for campaign **Execution time:** 3-8 seconds (calls live Google Ads API) 📊 **Example Usage:** 1. User: "I want to create a campaign for my plumbing business" 2. YOU call: research_keywords with business_description="Emergency plumbing services" 3. Tool returns: Keyword table with 100+ keywords, 20 recommended, budget suggestions 4. YOU show user: The keyword table and ask if they want modifications 5. User approves or requests changes 6. YOU call: create_search_campaign with approved keywords 💡 **Dynamic Thresholds:** This tool automatically adapts CPC thresholds to any industry: - Plumbing: HIGH ≥$6, MEDIUM $3-6, LOW `<`$3 - Legal: HIGH ≥$95, MEDIUM $45-95, LOW `<`$45 - E-commerce: HIGH ≥$2, MEDIUM $0.50-2, LOW `<`$0.50 All keywords returned will use **BROAD match** (Google's 2025 recommendation with Smart Bidding). --- 📊 **CRITICAL: AFTER calling this tool, YOU MUST explain these insights to the user:** **1. Keyword Discovery Summary:** - "I found [X] keywords from Google Keyword Planner for your [business type] business" - "I analyzed real search data and CPC costs from Google Ads" - "Here are the top 20 keywords I recommend based on commercial intent" **2. Seed Keywords Used:** - "I used these seed keywords: [list the seeds from the response]" - "Google expanded these into [X] keyword suggestions" **3. CPC Cost Analysis (CRITICAL - Discuss this with user!):** - "The median CPC for your industry is $[X]" - "Keywords range from $[LOW] to $[HIGH] per click" - "HIGH intent keywords (top 25% most expensive) cost $[threshold]+ per click" - "These are keywords where advertisers pay more = higher commercial value" **4. Budget Recommendations (CRITICAL - Explain all 3 tiers!):** - "Based on the keyword costs, here are my budget recommendations:" - "💰 Conservative ($[X]/day): Safe starting budget based on median CPC, expect ~[Y] clicks/day" - "💰 Moderate ($[X]/day): Balanced budget based on average CPC, expect ~[Y] clicks/day" - "💰 Aggressive ($[X]/day): Maximum budget to compete for all keywords, expect ~[Y] clicks/day" - "I recommend starting with $[conservative]-[moderate]/day" **5. Keyword Selection Explanation:** - "I selected these 20 keywords by prioritizing:" - " • HIGH intent keywords (expensive = high commercial value)" - " • High search volume (more potential customers)" - " • Mix of broad and specific terms" - "All keywords will use BROAD match - Google's 2025 recommendation for maximum reach with Smart Bidding" **6. Ask for User Feedback:** - "Would you like to modify this keyword selection?" - "Options: Add specific keywords, remove keywords, use only HIGH intent, or proceed with recommendations" **DO NOT just show the raw table without explanation!** **Users need YOU to interpret the data and provide strategic guidance!** # Resume Ad Source: https://www.adspirer.com/docs/api-reference/google-ads/resume-ad /api-reference/openapi.json post /api/v1/tools/resume_ad/execute Resume a paused ad to start showing it again. Only works on PAUSED ads (not REMOVED). **Parameters:** - ad_id: The ad ID to resume (REQUIRED) - ad_group_id: The ad group ID (REQUIRED) - customer_id: Optional **Execution time:** 1-2 seconds **When to use:** - User says "resume", "turn it back on", "enable" - User finished making changes - User wants to reactivate a paused A/B test variant **Example:** User: "Turn my paused ad back on" Agent: 1. Uses get_campaign_structure to find the paused ad 2. Uses resume_ad to enable it # Resume Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/resume-campaign /api-reference/openapi.json post /api/v1/tools/resume_campaign/execute Resume a paused campaign. Resuming a campaign makes ads start showing again. Only works on PAUSED campaigns (not REMOVED). **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-2 seconds **Returns:** - Campaign name - Before status (e.g., PAUSED) - After status (ENABLED) - Confirmation message **When to use:** - User says "resume", "turn it back on", "start it again" - User wants to re-enable a paused campaign - User finished making changes and wants ads to run **Example:** User: "Turn my campaign back on" Agent: Uses resume_campaign with the campaign_id # Save Business Profile Source: https://www.adspirer.com/docs/api-reference/google-ads/save-business-profile /api-reference/openapi.json post /api/v1/tools/save_business_profile/execute Save or update the user's business profile with provided details. ⚠️ IMPORTANT: This tool WRITES data. Use when user confirms their business profile. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 5):** - Saves user's business profile to database - Updates existing profile if one exists - Sets profile source as 'user_confirmed' or 'user_mcp' - Enables personalized recommendations going forward **Required Parameters:** - **business_vertical**: retail, services, technology, healthcare, finance, education, travel, food_beverage, automotive, real_estate - **business_size**: small (`<`$50K/month), medium ($50K-$500K/month), large (>$500K/month) - **primary_goal**: leads, sales, awareness, traffic, engagement, app_installs **Optional Parameters:** - **target_audience**: Free-text description (e.g., "B2B enterprise clients") - **geographic_focus**: local, regional, national, international - **seasonality**: none, holiday_heavy, summer_peak, winter_peak, q4_heavy, back_to_school - **customer_id**: Optional (uses connected account if omitted) **Use this tool when:** - User provides their business details - User confirms an inferred profile - User wants to update their business profile - After asking user clarifying questions about their business **Example Usage:** User: "I run a small local plumbing business targeting homeowners" → Call save_business_profile with: - business_vertical: "services" - business_size: "small" - primary_goal: "leads" - target_audience: "homeowners" - geographic_focus: "local" **Execution time:** 1-2 seconds (database write) # Search Audiences Source: https://www.adspirer.com/docs/api-reference/google-ads/search-audiences /api-reference/openapi.json post /api/v1/tools/search_audiences/execute Search for available audience segments (in-market, affinity, custom). Use this tool to discover audience segment IDs for: - **PMax campaigns:** Use IDs with `add_pmax_audience_signal` (audience signals/hints) - **Demand Gen / YouTube campaigns:** Pass IDs via `audience_segments` parameter in `create_demandgen_campaign` or `create_youtube_campaign` (direct targeting) **Audience types:** - **In-market:** Users actively researching products/services (e.g., "Business Software") - **Affinity:** Users with long-term interests (e.g., "Technology Enthusiasts") - **Custom:** Your account's existing remarketing/customer match lists **Parameters:** - query: Search term (e.g., "advertising services", "SaaS tools") **Execution time:** 2-5 seconds # Select Google Campaign Type Source: https://www.adspirer.com/docs/api-reference/google-ads/select-google-campaign-type /api-reference/openapi.json post /api/v1/tools/select_google_campaign_type/execute **USE THIS TOOL FIRST WHEN:** User wants to create a Google Ads campaign but hasn't specified the campaign type (Search, Performance Max, or YouTube). **IMPORTANT:** This tool should be called BEFORE any keyword research, asset discovery, or campaign creation when the user says things like: - "Create a Google Ads campaign" - "I want to run Google Ads" - "Set up a Google advertising campaign" - "Help me create ads on Google" - "I want to advertise on Google" - "Create a campaign" - "Run ads" This tool guides the user to select their campaign TYPE, then provides a detailed workflow for that specific type. **Campaign Types Available:** 1. **search** - Text ads in Google Search results (best for high-intent keywords, lead gen, local services) 2. **pmax** - Performance Max across all Google channels (best for ecommerce, brand awareness, multi-channel reach) 3. **youtube** - Video ads on YouTube (best for video content, brand storytelling, product demos) **Returns:** - What the campaign type is best for - Step-by-step workflow with which tools to call - Requirements (character limits, assets needed, etc.) - Natural follow-up question to start the creation flow **Do NOT use this tool if:** - User specifically asks for "search campaign" or "text ads" → go directly to research_keywords then create_search_campaign - User specifically asks for "PMax" or "Performance Max" → go directly to discover_existing_assets then create_pmax_campaign - User specifically asks for "YouTube campaign" or "video campaign" → go directly to validate_video then create_youtube_campaign - User is asking about performance/analytics → use get_campaign_performance - User is asking about existing campaigns → use list_campaigns **Parameters:** - campaign_type: 'search', 'pmax', or 'youtube' **Execution time:** Instant (no API call) # Suggest Ad Content Source: https://www.adspirer.com/docs/api-reference/google-ads/suggest-ad-content /api-reference/openapi.json post /api/v1/tools/suggest_ad_content/execute Generate AI-suggested headlines and descriptions based on campaign keywords. Analyzes campaign keywords and generates optimized ad content following creative guidelines: - 15 headlines across 3 categories (What It Is, Benefits, Pain/Proof/CTA) - 4 descriptions with value props and CTAs - All validated for character limits **Parameters:** - campaign_id: The campaign to analyze (REQUIRED) - business_description: Optional context about the business - key_benefits: Optional list of benefits (e.g., ["fast setup", "no dashboard"]) - proof_points: Optional proof points (e.g., [`{"number": "2000+", "metric": "campaigns"}`]) - pain_points: Optional pain points (e.g., ["manual ads", "complex UI"]) - customer_id: Optional **Returns:** - suggested_headlines: 15 headlines ready to use - suggested_descriptions: 4 descriptions ready to use - headline_categories: Headlines organized by category - keyword_themes: Top themes from campaign keywords **Use this when:** - User wants fresh ad copy ideas - User asks "what should my headlines be?" - Starting a new A/B test - Refreshing stale ad content **Execution time:** 3-5 seconds **Example:** User: "Suggest some better headlines for my campaign" Agent: 1. Uses suggest_ad_content to generate ideas 2. Shows suggestions organized by category 3. User picks favorites 4. Uses update_ad_headlines to apply selected headlines # Update Ad Content Source: https://www.adspirer.com/docs/api-reference/google-ads/update-ad-content /api-reference/openapi.json post /api/v1/tools/update_ad_content/execute Combined update for ad content (headlines, descriptions, and/or final URLs). Use this for efficiency when updating multiple ad elements at once. Single API call with combined field mask. **Parameters:** - ad_id: The ad ID to update (REQUIRED) - ad_group_id: The ad group ID (REQUIRED) - headlines: Optional list of 3-15 headlines (max 30 chars each) - descriptions: Optional list of 2-4 descriptions (max 90 chars each) - final_urls: Optional list of landing page URLs - customer_id: Optional At least one of headlines, descriptions, or final_urls is required. **Execution time:** 2-4 seconds **Example:** User: "Update both headlines and descriptions for my ad" Agent: Uses update_ad_content with both headlines and descriptions in one call # Update Ad Descriptions Source: https://www.adspirer.com/docs/api-reference/google-ads/update-ad-descriptions /api-reference/openapi.json post /api/v1/tools/update_ad_descriptions/execute Update descriptions for a Responsive Search Ad (RSA). **Parameters:** - ad_id: The ad ID to update (REQUIRED - get from get_campaign_structure) - ad_group_id: The ad group ID (REQUIRED) - descriptions: List of 2-4 descriptions (REQUIRED) - customer_id: Optional **Description Rules:** - Max 90 characters per description - 2-4 descriptions required - Descriptions should expand on headlines - Include specific details and CTAs - Formula: [Value Prop]. [Specific Detail]. [CTA]. **Execution time:** 2-4 seconds **WARNING:** Updated ads go through Google's review process. **Example:** User: "Make my ad descriptions more action-oriented" Agent: 1. Uses get_campaign_structure to find ad_id 2. Shows current descriptions 3. Prepares new descriptions with CTAs 4. Gets approval and updates # Update Ad Headlines Source: https://www.adspirer.com/docs/api-reference/google-ads/update-ad-headlines /api-reference/openapi.json post /api/v1/tools/update_ad_headlines/execute Update headlines for a Responsive Search Ad (RSA). # Update Bid Strategy Source: https://www.adspirer.com/docs/api-reference/google-ads/update-bid-strategy /api-reference/openapi.json post /api/v1/tools/update_bid_strategy/execute Change campaign bidding strategy. **Available Strategies:** - MAXIMIZE_CLICKS: Get as many clicks as possible within budget - MAXIMIZE_CONVERSIONS: Get as many conversions as possible - TARGET_CPA: Set a target cost per acquisition (requires target_cpa) - TARGET_ROAS: Set a target return on ad spend (requires target_roas) **Parameters:** - campaign_id: The campaign ID (REQUIRED) - strategy: MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, or TARGET_ROAS (REQUIRED) - target_cpa: Required if strategy is TARGET_CPA. In dollars, e.g., 25.00 for $25 CPA - target_roas: Required if strategy is TARGET_ROAS. Multiplier, e.g., 4.0 for 400% ROAS - customer_id: Optional (uses connected account if omitted) **IMPORTANT:** - TARGET_CPA requires conversion tracking to be set up - TARGET_ROAS requires conversion value tracking - Changing strategy may take 1-2 weeks to stabilize performance - Confirm with user before changing **Execution time:** 2-4 seconds **Example:** User: "I want to target $30 CPA" Agent: 1. Confirms: "I'll change the bidding strategy to TARGET_CPA with a $30 target. This may take 1-2 weeks to optimize. Proceed?" 2. Uses update_bid_strategy with strategy=TARGET_CPA, target_cpa=30.00 # Update Campaign Source: https://www.adspirer.com/docs/api-reference/google-ads/update-campaign /api-reference/openapi.json post /api/v1/tools/update_campaign/execute Update an existing campaign's settings. **Can update:** - name: Campaign name - status: ENABLED or PAUSED - budget_amount: Daily budget in dollars **IMPORTANT:** - Confirm with user BEFORE making changes - Use list_campaigns first to get campaign_id - At least one field (name, status, or budget_amount) is required **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - name: New campaign name (optional) - status: ENABLED or PAUSED (optional) - budget_amount: Daily budget in dollars, e.g., 50.00 for $50/day (optional) - customer_id: Optional (uses connected account if omitted) **Execution time:** 2-4 seconds **Example:** User: "Increase the budget to $100/day" Agent: 1. Uses list_campaigns to find the campaign 2. Confirms with user: "I'll update 'Summer Sale' budget from $50 to $100/day. Proceed?" 3. Uses update_campaign with campaign_id and budget_amount=100.00 # Update Keyword Source: https://www.adspirer.com/docs/api-reference/google-ads/update-keyword /api-reference/openapi.json post /api/v1/tools/update_keyword/execute Update keyword bid or status. **Parameters:** - keyword_id: The keyword to update (REQUIRED - get from get_campaign_structure) - ad_group_id: The ad group containing the keyword (REQUIRED) - cpc_bid_micros: New bid in micros (1 USD = 1,000,000). Example: 2500000 = $2.50 - status: ENABLED or PAUSED - customer_id: Optional **Can update:** - Bid amount (cpc_bid_micros) - Status (ENABLED/PAUSED) **CANNOT update (immutable):** - Keyword text - Match type **Execution time:** 2-3 seconds **Example:** User: "Increase the bid on 'running shoes' to $3" Agent: 1. Uses get_campaign_structure to find the keyword_id 2. Uses update_keyword with cpc_bid_micros=3000000 # Validate And Prepare Assets Source: https://www.adspirer.com/docs/api-reference/google-ads/validate-and-prepare-assets /api-reference/openapi.json post /api/v1/tools/validate_and_prepare_assets/execute 🔄 LONG-RUNNING TOOL: Validates multiple images from URLs for Performance Max campaigns. Emits MCP progress updates while downloading and validating 5-10 images (typically 5-15 seconds). Progress stages: download → validate → commit. ⚠️ CRITICAL: This tool accepts IMAGE URLS (from postimages.org), NOT base64 or file paths! # Validate Video Source: https://www.adspirer.com/docs/api-reference/google-ads/validate-video /api-reference/openapi.json post /api/v1/tools/validate_video/execute Validate video for ad campaigns (unified tool for all platforms). ⚠️ IMPORTANT: This is a READ-ONLY validation tool. Safe to call multiple times. 🎯 **What This Tool Does:** - Validates videos for Google Ads PMAX or TikTok campaigns - For PMAX: Validates YouTube video (privacy, duration, embeddable) - For TikTok: Validates public video URL is accessible - Returns metadata (title, duration, privacy, thumbnail) **DOES NOT upload videos** - user must already have video uploaded: - PMAX: Video must be on YouTube (public or unlisted) - TikTok: Video must be on public hosting (Google Drive, Vimeo, etc.) **Parameters:** - video_url_or_id (required): YouTube URL/ID (PMAX) or public video URL (TikTok) - platform (required): 'pmax' or 'tiktok' **For PMAX:** Accepts YouTube formats: - Full URL: https://youtube.com/watch?v=dQw4w9WgXcQ - Short URL: https://youtu.be/dQw4w9WgXcQ - Shorts: https://youtube.com/shorts/dQw4w9WgXcQ - Direct ID: dQw4w9WgXcQ (11 characters) Validates: - Video exists and is accessible - Privacy is Public or Unlisted (NOT Private) - Embeddable is enabled - Duration ≥10 seconds (PMAX requirement) Returns: - Video title - Duration - Privacy status - Thumbnail URL - Video ID **For TikTok:** Accepts public video file URLs: - Google Drive: https://drive.google.com/file/d/ABC123/view - Vimeo: https://vimeo.com/video/123456 - Dropbox: https://dropbox.com/s/abc/video.mp4 - Any publicly accessible video URL Validates: - URL is accessible (HTTP 200) - Content-Type is video/* (when available) Returns: - URL validation status - Content-Type - File size (if available) **Execution Time:** 1-3 seconds (YouTube Data API call or HTTP request) **When to Use:** - BEFORE creating a campaign with videos - To verify video meets platform requirements - To get video metadata (title, duration) **Example Usage:** ``` User: "I want to use this YouTube video in my PMAX campaign: dQw4w9WgXcQ" YOU: [Call validate_video with video_url_or_id="dQw4w9WgXcQ", platform="pmax"] Response: Video validated, title="Product Demo", duration=45s, ready for use ``` ``` User: "Can I use this video for TikTok ads: https://drive.google.com/file/d/ABC/view" YOU: [Call validate_video with video_url_or_id="https://drive...", platform="tiktok"] Response: URL validated, accessible, ready for campaign ``` **Error Handling:** - Private videos: Clear error asking user to change privacy to Public/Unlisted - Short videos (`<`10s for PMAX): Error with duration requirement - Invalid URLs: Error with accessibility details - Not embeddable: Error asking user to enable embedding # Adspirer REST API for Ads Automation Source: https://www.adspirer.com/docs/api-reference/introduction HTTP access to Adspirer's 400+ tools. Create campaigns and pull performance for Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads from n8n, Zapier, or Make. The Adspirer REST API exposes every tool the [MCP server](/docs/mcp) does, over plain HTTP. Use it from any client that can't speak SSE — n8n, Zapier, Make, GitHub Actions, Python scripts, cron jobs, or your own backend. > **[Get your API key](https://adspirer.ai/keys?utm_source=docs\&utm_medium=api-reference\&utm_content=intro)** > > Generate a key at `adspirer.ai/keys`, then call any of the endpoints below with a bearer token. Free tier includes 15 calls — enough to test everything. | | | | :- | :- | | **Base URL** | `https://api.adspirer.ai` | | **Interactive sandbox** | [api.adspirer.ai/docs](https://api.adspirer.ai/docs) (Swagger UI) | | **Raw OpenAPI spec** | [api.adspirer.ai/openapi.json](https://api.adspirer.ai/openapi.json) | ## Use cases Real patterns teams ship on the REST API today. Each one is just a few HTTP calls — the hard part is already done for you. > **Slack ChatOps for campaigns** > > Team member posts a campaign brief in `#campaign-activation` → n8n parses it → REST API creates the campaign `PAUSED` → bot confirms in the thread. Nobody needs a Meta / Google login. > **Daily account briefings** > > Every morning, pull CPL / ROAS / spend for each account manager's book of business and deliver a Slack digest. Alert states (🟢 on-track, 🟡 watch, 🔴 red) computed against targets you store in a Google Sheet. > **Portfolio rollups for owners** > > Weekly health summary across every client account — who's over/under target, budget utilization, top / bottom 5 performers, per-manager breakdown. > **Alert thresholds & auto-pause** > > Watch CPL vs target, flag breaches, pause underperforming ad sets on a rule. [`create_monitor`](/docs/api-reference/monitoring/create-monitor) handles the poll loop on our side so you don't run a cron. > **SaaS product embedding** > > Your app creates a starter campaign for every new customer during onboarding. `Idempotency-Key` makes signup retries safe even under network flakiness. > **Headless CI / scheduled ops** > > Launch seasonal campaigns from GitHub Actions, kick off end-of-month reports from cron, trigger pause / resume on holiday calendars. No browser, no OAuth dance — just an API key. ### How they wire up Each pattern is a small variation on the same two primitives: read-only tools for data, write tools for changes. | Pattern | Ingress | Adspirer calls | Egress | | :- | :- | :- | :- | | Slack ChatOps | Slack webhook → n8n | `create_meta_image_campaign`, `add_meta_ad_set`, `add_meta_ad` | Slack thread reply | | Daily briefings | Cron (n8n / Zapier / cron) | `get_campaign_performance`, `analyze_wasted_spend` | Slack DM per manager | | Portfolio rollups | Cron, weekly | `get_campaign_performance` across accounts | Email / Notion / Slack | | Auto-pause guardrail | `create_monitor` (Adspirer-hosted) | `pause_campaign` or `update_campaign` (lower the daily budget) on breach | Slack alert + action log | | SaaS onboarding | Your app's signup hook | `create_search_campaign` with `Idempotency-Key` | Campaign ID stored in your DB | | Scheduled ops | GitHub Actions / cron | Whatever the job needs | Job log + Slack status | > [!TIP] > > **Agency pattern**: pass `ad_account_id`, `customer_id`, or `advertiser_id` on every call to route to the right client account. One API key can manage hundreds of connected accounts from a single backend. ## Why use the REST API? You're already using ChatGPT, Claude, or Cursor with Adspirer's MCP server — and that's great for interactive work. But there are jobs an AI conversation can't do: * **Your agent shuts off when you close the tab.** A cron that pulls daily performance at 9am needs to run without a human watching. * **No-code automation tools don't speak MCP.** n8n, Zapier, and Make only know HTTP. MCP uses SSE. * **Your backend wants to embed campaign creation.** A SaaS onboarding flow that creates a starter campaign for every new customer can't open a chat with Claude. * **Multi-step workflows need to be deterministic.** "If CTR drops below 2%, pause the campaign" belongs in code, not a prompt. The REST API gives you the same tools, over plain HTTP that every automation platform understands. ## How it relates to MCP Same backend. Same auth. Same quota. Same write-guards. Only the transport differs. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[ChatGPT / Claude / Cursor] -->|MCP over SSE| B[Adspirer backend] C[n8n / Zapier / curl / your code] -->|REST over HTTP| B B --> D[Google Ads] B --> E[Meta Ads] B --> F[LinkedIn Ads] B --> G[TikTok Ads] ``` One logical endpoint per tool: `POST /api/v1/tools//execute`. Call `add_meta_ad` from a chat via MCP or from a cron via REST — the result, the quota cost, and the log entry are identical. ## Quickstart **curl** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://api.adspirer.ai/api/v1/tools/list_connected_accounts/execute \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{"arguments": {}}' ``` **Python** ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} import requests r = requests.post( "https://api.adspirer.ai/api/v1/tools/list_connected_accounts/execute", headers={"Authorization": "Bearer sk_live_..."}, json={"arguments": {}}, ) r.raise_for_status() print(r.json()["data"]) ``` **Node (fetch)** ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} const res = await fetch( "https://api.adspirer.ai/api/v1/tools/list_connected_accounts/execute", { method: "POST", headers: { "Authorization": "Bearer sk_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ arguments: {} }), }, ); const { data } = await res.json(); console.log(data); ``` **n8n** Use the **HTTP Request** node: | Field | Value | | :- | :- | | Method | `POST` | | URL | `https://api.adspirer.ai/api/v1/tools//execute` | | Authentication | `Header Auth` → name `Authorization`, value `Bearer sk_live_...` | | Body Content Type | `JSON` | | Body | `{ "arguments": { ... } }` | Add an `Idempotency-Key` header (UUID) on write operations so retries collapse into one call. ## Core concepts ### Authentication Every call requires an API key generated at [adspirer.ai/keys](https://adspirer.ai/keys). Pass it as a bearer token — keys are prefixed `sk_live_`. Treat them as secrets; never commit them. Keys provide the same access as OAuth tokens used by MCP clients — same tools, same quotas. ### Request envelope Every endpoint takes a `POST` with tool-specific input wrapped in an `arguments` object: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "arguments": { "ad_set_id": "120203456789", "headline": "Spring sale", "primary_text": "Up to 40% off" } } ``` ### Response envelope Success: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "success": true, "tool": "add_meta_ad", "data": { "ad_id": "120203456789", "quota": { "used": 42, "limit": 150, "tier": "plus", "period_end": "2026-05-01" } } } ``` Error: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "success": false, "is_error": true, "error": "ad_set_id is required" } ``` ### Quota & billing Every successful billable call decrements your monthly tool-call allowance. The current counter is attached to every 200 response under `data.quota`. When the limit is hit, the API returns `HTTP 402` with a `quota` block including `upgrade_url`. Read-only diagnostic tools never consume quota: `get_usage_status`, `list_connected_accounts`, `get_connections_status`. See [Pricing](/docs/knowledge-base/pricing) for tier limits. ### Idempotency Write operations accept an `Idempotency-Key` header. A repeated call with the same key returns the cached result rather than executing twice. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl https://api.adspirer.ai/api/v1/tools/add_meta_ad/execute \ -H "Authorization: Bearer sk_live_..." \ -H "Idempotency-Key: 4a1c2d3e-..." \ -H "Content-Type: application/json" \ -d '{"arguments": {...}}' ``` > [!TIP] > > **Strongly recommended for n8n, Zapier, and any retry-prone client.** Generate a fresh UUID per logical operation — not per retry — so retries collapse into one write. ### Multi-account users If you've connected multiple accounts on the same platform (e.g. an agency with 10 Meta ad accounts), specify the account on every call: * `ad_account_id` — Meta Ads * `customer_id` — Google Ads * `advertiser_id` — TikTok Ads, LinkedIn Ads * `account_id` — generic fallback Omitting the field returns `HTTP 400` with a list of valid IDs. Use [`list_connected_accounts`](/docs/api-reference/general/list-connected-accounts) to discover them. ### HTTP status codes | Status | Meaning | | :- | :- | | `200` | Success. Parse `data`. | | `400` | Tool-level error. Surface `error` to users. Includes multi-account prompts and validation failures. | | `401` | Invalid or missing API key. | | `402` | Adspirer quota exhausted. Response includes `upgrade_url`. | | `404` | Unknown `tool_name` in the URL. | | `409` | Idempotency key reused with different arguments. | | `429` | Upstream ad platform rate-limited us (Meta / Google / etc.). Retry with backoff. | | `500` | Unexpected server error. Report to [support](/docs/knowledge-base/support). | ### No streaming This endpoint is plain request/response JSON. **No SSE, no chunked streaming.** Safe to use from n8n Cloud, Zapier, Make, curl, Python `requests`, Node `fetch`, Go `net/http`, and every mainstream HTTP library. ## Tool coverage > **[Google Ads](/docs/api-reference/google-ads/create-search-campaign)** > > 51 tools — campaigns, ad groups, keywords, extensions, Performance Max, Demand Gen > **[Meta Ads](/docs/api-reference/meta-ads/add-meta-ad)** > > 36 tools — image, video, carousel, DCO, audiences, placements > **[LinkedIn Ads](/docs/api-reference/linkedin-ads/add-linkedin-campaign-to-group)** > > 45 tools — campaigns, creatives, audiences, conversion tracking > **[TikTok Ads](/docs/api-reference/tiktok-ads/add-tiktok-ad)** > > 29 tools — campaigns, ad groups, ads, geo, optimization events > **[Monitoring & Reporting](/docs/api-reference/monitoring/create-monitor)** > > 13 tools — cross-platform performance, wasted spend, search terms > **[Account Management](/docs/api-reference/general/list-connected-accounts)** > > 3 tools — list connected accounts, connection status, usage > [!NOTE] > > The endpoint reference above is being expanded to the full **400+ tool** surface. **Amazon Ads** (61 tools) and **ChatGPT Ads** (50 tools), plus the newest **Google Shopping/App**, **Meta Advantage+ Catalog**, and **LinkedIn** tools, are all available over the same REST transport today — every MCP tool has a matching `POST /api/v1/tools/{tool_name}/execute` endpoint. See the [Tool Catalog](/docs/agent-skills/tools) for the complete, current list while the interactive reference pages are regenerated. ## Architecture patterns ### Slack ChatOps — campaign creation from a message ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} sequenceDiagram participant U as Team member participant S as Slack channel participant N as n8n workflow participant A as api.adspirer.ai participant M as Meta Ads U->>S: Posts campaign brief S->>N: Webhook (message + thread ts) N->>N: Parse brief → campaign params N->>A: POST /browse_meta_targeting/execute A-->>N: audience options N->>A: POST /discover_meta_assets/execute A-->>N: available creatives N->>A: POST /create_meta_image_campaign/execute
(Idempotency-Key) A->>M: Create campaign (PAUSED) A-->>N: campaign_id N->>S: Reply in thread: "✅ created, review here" ``` Every campaign is created **PAUSED** — the requester reviews and activates manually. The `Idempotency-Key` header means a retry from n8n never creates a duplicate campaign. ### Daily briefings — scheduled read-only reports ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} sequenceDiagram participant C as Cron (8am) participant N as n8n / worker participant A as api.adspirer.ai participant G as Google Sheet (CPL targets) participant S as Slack C->>N: Trigger N->>G: Read account list + CPL targets loop For each account N->>A: POST /get_campaign_performance/execute
{lookback_days: 1, ad_account_id} A-->>N: metrics N->>N: Compute alert state (🟢🟡🔴) end N->>S: DM each account manager
with their accounts' digest ``` Read-only tools (`get_*`, `list_*`, `analyze_*`) don't consume quota. At \~3 calls per account per briefing, 100 accounts = 300 calls / morning. ### Guarded auto-pause — Adspirer-hosted monitor ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} sequenceDiagram participant You as Your backend participant A as api.adspirer.ai participant P as Ad platform You->>A: POST /create_monitor/execute
{condition: CPL > target+$20 for 2 days,
action: pause_ad_set} A->>A: Poll schedule (every 6h) loop Every 6h A->>P: Fetch performance A->>A: Evaluate condition alt Breach A->>P: Pause ad set A->>You: Webhook / email alert end end ``` You don't run the cron — Adspirer does. Use this when you want rules to fire without babysitting an n8n workflow. ### SaaS onboarding — embedded create ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # New customer signs up → create a starter Search campaign import uuid, requests resp = requests.post( "https://api.adspirer.ai/api/v1/tools/create_search_campaign/execute", headers={ "Authorization": f"Bearer {os.environ['ADSPIRER_KEY']}", "Idempotency-Key": f"signup-{customer.id}", # stable per customer }, json={"arguments": { "customer_id": customer.google_ads_customer_id, "campaign_name": f"{customer.brand} — starter", "budget_daily": 20, "keywords": customer.seed_keywords, }}, timeout=60, ) resp.raise_for_status() customer.starter_campaign_id = resp.json()["data"]["campaign_id"] ``` Reusing `signup-{customer.id}` as the key means signup retries never double-create. ## What's excluded from REST These exist in MCP but are intentionally omitted from the REST surface — call the underlying tools directly instead: * **Unified aggregators** (`ads_query`, `ads_optimize`, `ads_create`, `ads_manage`, `account_info`) — LLM-convenience wrappers that dispatch to real tools. * **Federated router meta-tools** (`google_ads`, `meta_ads`, `linkedin_ads`, `tiktok_ads`, `monitoring_and_reporting`) — MCP-transport workaround for Claude Desktop's tool-list size limit. Irrelevant for REST. ## FAQ > **Do REST and MCP share the same quota?** > > Yes. Both transports decrement the same monthly allowance on your Adspirer plan. A call made from ChatGPT (MCP) and a call made from a curl script (REST) count the same. > **Can I use the REST API from a browser?** > > Technically yes, but don't. An API key in browser JavaScript is visible to anyone who opens DevTools. Call the REST API from your backend, or use the MCP server for user-facing AI experiences. > **How do I handle rate limiting from Meta / Google / etc.?** > > If an upstream ad platform rate-limits us, you'll see `HTTP 429`. Back off and retry — typically 30–60 seconds is enough. Adspirer's internal rate limits (`HTTP 402` for quota) are separate from upstream limits. > **Is there a webhook or subscription API?** > > Not yet. For "run every X hours" style jobs, use `create_monitor` — it polls on our side and emits alerts you can wire into Slack or email. For true push-based webhooks, [book a call](https://www.adspirer.com/book-demo). > **Can I use the same API key from multiple machines?** > > Yes. Keys aren't pinned to a device. Just be aware that concurrent calls share one quota — if you parallelize heavily, you may hit `HTTP 402` sooner. > **What happens if my key leaks?** > > Revoke it immediately at [adspirer.ai/keys](https://adspirer.ai/keys) and generate a new one. Revoked keys stop working within seconds. ## Related * [How MCP Works](/docs/mcp) — the protocol the REST API mirrors * [Core Workflows](/docs/agent-skills/workflows) — step-by-step tool sequences for common jobs * [Tool Catalog](/docs/agent-skills/tools) — the full 400+ tool reference * [Pricing](/docs/knowledge-base/pricing) — quota tiers and overage billing * [Security](/docs/knowledge-base/security) — how API keys, OAuth, and session data are handled # Add LinkedIn Campaign To Group Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/add-linkedin-campaign-to-group /api-reference/openapi.json post /api/v1/tools/add_linkedin_campaign_to_group/execute **USE THIS TOOL WHEN:** User wants to add a new campaign with DIFFERENT targeting/audience to an EXISTING campaign group. This is the LinkedIn equivalent of Meta's add_ad_set. LinkedIn hierarchy: Campaign Group → Campaign → Creative. - Different audiences = different Campaigns in the SAME Campaign Group. - Different creatives = different Creatives in the SAME Campaign. **Common scenarios:** - Audience testing: Same ad format, different targeting per campaign - Geographic split: Same creative, different locations per campaign - Multi-market: Same product, different countries - Scaling: Adding new audiences to existing campaign group **CRITICAL:** Each create_linkedin_*_campaign creates a new Campaign Group (unless campaign_group_id is passed). To add more campaigns to the SAME group, you MUST use this tool or pass campaign_group_id to create tools. NEVER call create_linkedin_*_campaign without campaign_group_id for the same group. **KEY DISTINCTION:** - Different audience/targeting → use THIS tool (new campaign in same group) - Different copy/creative, same audience → use add_linkedin_creative / add_linkedin_video_creative instead **Supports all 4 ad types:** image, video, carousel, text. Each campaign has INDEPENDENT: targeting, budget, schedule. Shared from campaign group: objective, group name. **Workflow:** 1. Create initial campaign → get campaign_group_id + campaign_id 2. Call this tool with campaign_group_id for each additional audience 3. Use add_linkedin_creative to add more creatives within any campaign Execution time: 15-120 seconds (depends on ad type) # Add LinkedIn Carousel Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/add-linkedin-carousel-creative /api-reference/openapi.json post /api/v1/tools/add_linkedin_carousel_creative/execute User wants to add another carousel ad variation to an existing carousel campaign. Add a new carousel creative to a carousel campaign for A/B testing. LinkedIn recommends 4+ carousel ad variations per campaign for optimal performance. **DO NOT USE to create a new campaign.** For new campaigns: - Image → create_linkedin_image_campaign - Video → create_linkedin_video_campaign - Carousel → create_linkedin_carousel_campaign - Text → create_linkedin_text_campaign **DO NOT USE for different audiences.** For different targeting: → Use add_linkedin_campaign_to_group instead. Required Parameters: - campaign_id: Carousel campaign to add creative to - organization_id: Organization for ad authoring - cards: Array of 2-10 carousel cards (image_urn/url, headline, landing_page_url) - introductory_text: Main ad text (max 255 chars) - landing_page_url: Overall landing page URL Optional Parameters: - creative_name: Descriptive name (e.g. "Product Showcase - Carousel Ad 2") - call_to_action: CTA label (default: LEARN_MORE) - account_id: LinkedIn Ad Account ID AD POLICY: NEVER use "LinkedIn" in ad copy. Execution time: 5-15 seconds # Add LinkedIn Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/add-linkedin-creative /api-reference/openapi.json post /api/v1/tools/add_linkedin_creative/execute **USE THIS TOOL WHEN:** User wants to add another IMAGE ad/creative to an EXISTING LinkedIn image campaign. **DO NOT USE to create a new campaign.** For new campaigns: - Image → `create_linkedin_image_campaign` - Video → `create_linkedin_video_campaign` - Carousel → `create_linkedin_carousel_campaign` - Text → `create_linkedin_text_campaign` **DO NOT USE for different audiences/targeting.** For different audiences: → Use `add_linkedin_campaign_to_group` instead (creates a new campaign in the same group). **KEY DISTINCTION:** - Same audience, different creative/copy → use THIS tool - Different audience/targeting → use `add_linkedin_campaign_to_group` instead **Common scenarios:** - A/B test ad copy: Different headlines, introductory text, or CTAs - A/B test images: Different images for same audience - LinkedIn recommends 4+ ads per campaign for optimal performance Required Parameters: - campaign_id: Campaign to add creative to - organization_id: Organization for ad authoring - image_urn: Image asset URN - introductory_text: Main ad copy - landing_page_url: Destination URL AD POLICY: NEVER use "LinkedIn" in ad copy. NEVER mention competitor platforms. Execution time: 5-10 seconds # Add LinkedIn Text Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/add-linkedin-text-creative /api-reference/openapi.json post /api/v1/tools/add_linkedin_text_creative/execute **USE THIS TOOL WHEN:** User wants to add another text ad to an EXISTING TEXT_AD campaign. **DO NOT USE to create a new campaign.** For new campaigns → `create_linkedin_text_campaign`. **DO NOT USE for image/video/carousel campaigns** → use `add_linkedin_creative` or `add_linkedin_video_creative`. **DO NOT USE for different audiences** → use `add_linkedin_campaign_to_group` instead. **KEY DISTINCTION:** - Same audience, different headline/description → use THIS tool - Different audience/targeting → use `add_linkedin_campaign_to_group` LinkedIn recommends 3-4 text ad variations per campaign. Required Parameters: - campaign_id: TEXT_AD campaign to add creative to - headline: Text ad headline (max 25 chars) - description: Text ad description (max 75 chars) - landing_page_url: Destination URL (HTTPS) AD POLICY: NEVER use "LinkedIn" in headline or description. Execution time: 3-5 seconds # Add LinkedIn Video Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/add-linkedin-video-creative /api-reference/openapi.json post /api/v1/tools/add_linkedin_video_creative/execute **USE THIS TOOL WHEN:** User wants to add another video ad to an EXISTING LinkedIn video campaign. **DO NOT USE to create a new campaign.** For new campaigns → `create_linkedin_video_campaign`. **DO NOT USE for image campaigns** → use `add_linkedin_creative` instead. **DO NOT USE for text ads** → use `add_linkedin_text_creative` instead. **DO NOT USE for different audiences** → use `add_linkedin_campaign_to_group` instead. **KEY DISTINCTION:** - Same audience, different video/copy → use THIS tool - Different audience/targeting → use `add_linkedin_campaign_to_group` LinkedIn recommends 3-4 video ad variations per campaign. Required Parameters: - campaign_id: Video campaign to add creative to - organization_id: Organization for ad authoring - video_urn: Video asset URN (urn:li:video:...) - introductory_text: Main ad copy (max 600 chars) - landing_page_url: Destination URL (HTTPS) AD POLICY: NEVER use "LinkedIn" in ad copy. Execution time: 5-10 seconds # Analyze LinkedIn Creative Performance Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/analyze-linkedin-creative-performance /api-reference/openapi.json post /api/v1/tools/analyze_linkedin_creative_performance/execute User asks about ad/creative performance, wants to identify winning/losing ad variations, or asks about creative fatigue. Analyzes LinkedIn creative/ad performance: Returns: - Top performing creatives by engagement rate - Underperforming creatives needing attention - Creative fatigue indicators (running too long) - Video performance (views, completion rates) - Engagement breakdown per creative - Recommendations for creative refresh Creative Metrics: - Impressions, clicks, CTR - Engagement rate (likes, comments, shares) - Lead generation (forms, completions) - Video metrics (views, quartile completions) - Days running (for fatigue detection) Parameters: - lookback_days: Number of days to analyze (7-120). Default: 30 - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - campaign_id: Optional filter to specific campaign - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "Which LinkedIn ads are performing best?" - "Show me creative performance on LinkedIn" - "Are any LinkedIn creatives fatigued?" - "Which ads should I refresh on LinkedIn?" Execution time: 2-3 seconds # Analyze LinkedIn Wasted Spend Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/analyze-linkedin-wasted-spend /api-reference/openapi.json post /api/v1/tools/analyze_linkedin_wasted_spend/execute User asks about wasted ad spend, unprofitable campaigns, where their LinkedIn budget is being wasted, or wants to identify underperformers. Identifies LinkedIn campaigns and B2B segments wasting money: Campaign Analysis: - Campaigns losing money (ROAS `<` 1.0 = actual loss) - Campaigns underperforming (ROAS below target = opportunity cost) - Severity classification (CRITICAL, HIGH, MEDIUM) - Wasted spend calculation per campaign B2B Demographic Waste: - Seniority levels with poor ROAS - Industries not converting - Company sizes wasting budget - Job functions underperforming Creative Waste: - Fatigued creatives (14-day threshold) - Low engagement creatives - High spend but low lead creatives Returns: - Total wasted spend and percentage - Campaigns to pause/reduce - Segments to exclude - Quick actions with monthly savings estimates Parameters: - lookback_days: Number of days to analyze (7-120). Default: 30 - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - target_roas: Override target ROAS threshold - include_demographic_breakdown: Include B2B segment waste. Default: true - include_creative_analysis: Include creative-level waste. Default: true - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "Where am I wasting money on LinkedIn?" - "Which LinkedIn campaigns are losing money?" - "Show me LinkedIn wasted spend" - "Which B2B segments should I stop targeting?" - "How can I reduce LinkedIn ad waste?" Execution time: 4-6 seconds **Quick Actions (IMPORTANT — read severity context first):** - ⏳ LEARNING campaigns → Do NOT pause. Monitor for 14+ days before judging. - ❓ INSUFFICIENT_DATA campaigns → Need more spend before analysis is meaningful. - 🚨 CRITICAL campaigns (established, 14+ days, ZERO conversions) → Consider pausing - 🚨 CRITICAL campaigns (established, 14+ days, HAS conversions) → Review performance, verify revenue in ad platform before reducing budget - 🔴 HIGH severity (established, 14+ days) → Consider reducing budget by 50-70% - 🟡 MEDIUM → Optimize targeting, ad copy, landing pages ⚠️ **NEVER say "pause" for a campaign that has conversions.** Say "review" or "reduce budget" instead. ⚠️ **NEVER recommend pausing a campaign in LEARNING phase.** ⚠️ **If ALL campaigns are LEARNING or INSUFFICIENT_DATA, tell the user their account is too new for waste analysis and recommend checking back in 2 weeks.** ⚠️ **Consider campaign objective: brand awareness campaigns will not have ROAS data. This is normal.** ⚠️ **When data confidence is MEDIUM or LOW, soften all recommendations and add verification prompts.** # Associate LinkedIn Conversion Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/associate-linkedin-conversion /api-reference/openapi.json post /api/v1/tools/associate_linkedin_conversion/execute User wants to add conversion tracking to a campaign. Associate an existing conversion with a campaign. Parameters: - campaign_id: Campaign to associate conversion with - conversion_id: Conversion ID to associate Execution time: 2-3 seconds # Batch Update LinkedIn Campaigns Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/batch-update-linkedin-campaigns /api-reference/openapi.json post /api/v1/tools/batch_update_linkedin_campaigns/execute User wants to update multiple LinkedIn campaigns at once (bulk operations). Batch update status, budget, or other settings across multiple campaigns simultaneously. Parameters: - campaign_ids: List of campaign IDs to update (1-50, required) - status: New status for all campaigns (ACTIVE, PAUSED, or ARCHIVED) - daily_budget: New daily budget for all campaigns (minimum $10) - total_budget: New total budget for all campaigns - account_id: Optional LinkedIn Ad Account ID Example Prompts: - "Pause all my LinkedIn campaigns" - "Set all campaigns to $20/day budget" - "Archive campaigns 123, 456, and 789" - "Activate these 5 campaigns" - "Update budget for all my LinkedIn ads" - "Bulk pause my campaigns" Execution time: 5-15 seconds (depends on number of campaigns) # Clone LinkedIn Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/clone-linkedin-campaign /api-reference/openapi.json post /api/v1/tools/clone_linkedin_campaign/execute User wants to duplicate, copy, or clone a LinkedIn campaign. Clone an existing campaign with optional overrides for name, budget, locations, and creatives. Parameters: - source_campaign_id: Campaign ID to clone (required) - new_name: Name for the cloned campaign (default: '`{original}` - Copy') - daily_budget: Override daily budget for the clone - locations: Override location targeting for the clone - status: Status for new campaign (default: PAUSED for safety) - copy_creatives: Copy creatives from source (default: True) - account_id: Optional LinkedIn Ad Account ID The cloned campaign is always created as PAUSED for safety. Activate it when ready. Example Prompts: - "Clone my LinkedIn campaign" - "Duplicate campaign 12345 with a new name" - "Copy my campaign but change the budget to $30/day" - "Create a copy of my campaign for a different region" - "Replicate campaign with different targeting" Execution time: 5-10 seconds # Create LinkedIn Carousel Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/create-linkedin-carousel-campaign /api-reference/openapi.json post /api/v1/tools/create_linkedin_carousel_campaign/execute **USE THIS TOOL WHEN:** User wants to create a LinkedIn CAROUSEL ad campaign (2-10 swipeable image cards). **DO NOT USE for image ads** → use `create_linkedin_image_campaign` instead. **DO NOT USE for video ads** → use `create_linkedin_video_campaign` instead. **DO NOT USE for text ads** → use `create_linkedin_text_campaign` instead. **REQUIRED:** Either `campaign_group_name` (creates new group) or `campaign_group_id` (adds to existing group). IMPORTANT: This creates the campaign with 1 creative (Variation 1). Campaign is created in PAUSED status. Carousel Specifications: - 2-10 cards required (3-5 is the sweet spot) - All images must be 1080x1080 (1:1 aspect ratio) - Each card has: image, headline (max 45 chars), landing page URL - Introductory text max: 255 characters Required Parameters: - campaign_name, daily_budget, organization_id - introductory_text (up to 255 chars), landing_page_url (overall) - cards: Array of 2-10 cards, each with image (urn or url), headline, landing_page_url - locations (targeting) - campaign_group_name OR campaign_group_id Default Objective: WEBSITE_VISIT AD POLICY: NEVER use "LinkedIn" in ad copy. NEVER mention competitor platforms. **After Creation — IMPORTANT:** - This tool created 1 campaign + 1 creative. Campaign Group ID is returned. - To add MORE carousel creatives (A/B test text): use `add_linkedin_carousel_creative` with the campaign_id - To add MORE campaigns (different audience): use `add_linkedin_campaign_to_group` with the campaign_group_id - NEVER call this create tool again without campaign_group_id — that creates a SEPARATE campaign group Execution time: 15-60 seconds (includes image uploads) # Create LinkedIn Image Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/create-linkedin-image-campaign /api-reference/openapi.json post /api/v1/tools/create_linkedin_image_campaign/execute ⚠️ STOP - DO NOT CALL THIS TOOL DIRECTLY! This tool creates REAL LinkedIn campaigns that cost REAL money. # Create LinkedIn Text Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/create-linkedin-text-campaign /api-reference/openapi.json post /api/v1/tools/create_linkedin_text_campaign/execute **USE THIS TOOL WHEN:** User wants to create a LinkedIn TEXT ad campaign (desktop right rail/top banner). **DO NOT USE for image ads** → use `create_linkedin_image_campaign` instead. **DO NOT USE for video ads** → use `create_linkedin_video_campaign` instead. **DO NOT USE for carousel ads** → use `create_linkedin_carousel_campaign` instead. **REQUIRED:** Either `campaign_group_name` (creates new group) or `campaign_group_id` (adds to existing group). IMPORTANT: This creates the campaign with 1 creative (Variation 1). Campaign is created in PAUSED status. Text Ad Specifications: - Headline: max 25 characters (required) - Description: max 75 characters (required) - Image: 100x100 pixels (optional) - Landing page URL: HTTPS (required) - Desktop-only placement (right rail, top banner) Required Parameters: - campaign_name, daily_budget, organization_id - headline (max 25 chars), description (max 75 chars) - landing_page_url, locations (targeting) - campaign_group_name OR campaign_group_id Optional: image_urn or image_url (100x100 image) Default Objective: WEBSITE_VISIT Note: VIDEO_VIEW and LEAD_GENERATION objectives are NOT supported for text ads. AD POLICY: NEVER use "LinkedIn" in ad copy. NEVER mention competitor platforms. **After Creation — IMPORTANT:** - This tool created 1 campaign + 1 creative. Campaign Group ID is returned. - To add MORE text ad creatives (A/B test headlines): use `add_linkedin_text_creative` with the campaign_id - To add MORE campaigns (different audience): use `add_linkedin_campaign_to_group` with the campaign_group_id - NEVER call this create tool again without campaign_group_id — that creates a SEPARATE campaign group Execution time: 10-20 seconds # Create LinkedIn Video Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/create-linkedin-video-campaign /api-reference/openapi.json post /api/v1/tools/create_linkedin_video_campaign/execute **USE THIS TOOL WHEN:** User wants to create a LinkedIn VIDEO ad campaign. **DO NOT USE for image ads** → use `create_linkedin_image_campaign` instead. **DO NOT USE for carousel ads** → use `create_linkedin_carousel_campaign` instead. **DO NOT USE for text ads** → use `create_linkedin_text_campaign` instead. **REQUIRED:** Either `campaign_group_name` (creates new group) or `campaign_group_id` (adds to existing group). IMPORTANT: This creates the campaign with 1 creative (Variation 1). Campaign is created in PAUSED status. Video Specifications: - Format: MP4 (H.264 codec) - File size: 75KB - 500MB - Duration: 3 seconds - 30 minutes (recommended: 15-30 seconds) - Aspect ratios: 16:9, 1:1, 4:5, 9:16 Video Source (one required): - video_urn: Existing video URN from discover_linkedin_assets - video_url: Public URL to download and upload MP4 video Required Parameters: - campaign_name, daily_budget, organization_id, headline - introductory_text (up to 600 chars), landing_page_url - locations (targeting), video source (urn or url) - campaign_group_name OR campaign_group_id Default Objective: VIDEO_VIEW (optimizes for video views) AD POLICY: NEVER use "LinkedIn" in ad copy. NEVER mention competitor platforms. **After Creation — IMPORTANT:** - This tool created 1 campaign + 1 creative. Campaign Group ID is returned. - To add MORE creatives (A/B test copy): use `add_linkedin_video_creative` with the campaign_id - To add MORE campaigns (different audience): use `add_linkedin_campaign_to_group` with the campaign_group_id - NEVER call this create tool again without campaign_group_id — that creates a SEPARATE campaign group Execution time: 30-120 seconds (includes video upload and processing) # Delete LinkedIn Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/delete-linkedin-creative /api-reference/openapi.json post /api/v1/tools/delete_linkedin_creative/execute User wants to delete, archive, or remove a LinkedIn ad/creative. Archive or permanently delete a LinkedIn creative. Parameters: - creative_id: Creative ID to archive or delete (required) - account_id: Optional LinkedIn Ad Account ID - permanent: If True, permanently deletes (irreversible). If False, archives (default, recoverable). What happens: - Default (permanent=False): Creative is archived and can be restored later - permanent=True: Creative is permanently deleted and cannot be recovered Example Prompts: - "Delete creative 12345" - "Archive my LinkedIn ad" - "Remove creative from my campaign" - "Permanently delete ad 12345" Execution time: 2-3 seconds # Discover LinkedIn Assets Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/discover-linkedin-assets /api-reference/openapi.json post /api/v1/tools/discover_linkedin_assets/execute User wants to find existing images/videos in their LinkedIn account to reuse. Discover previously uploaded image and video assets for a LinkedIn Ad Account. IMPORTANT: - Call `get_linkedin_organizations` FIRST to get both organization_id AND account_id - The account_id is REQUIRED to find images uploaded via the new LinkedIn API What this tool does: - Queries LinkedIn for existing assets in the ad account - Returns images and videos with URNs, dimensions, and status - Assets can be reused in new campaigns without re-uploading Parameters: - organization_id: LinkedIn Organization (Company Page) ID (required) - account_id: LinkedIn Ad Account (Sponsored Account) ID (REQUIRED for image discovery!) - Get this from `get_linkedin_organizations` response - Without this, images uploaded via new API won't be found - asset_type: Filter by type - 'image', 'video', or 'all' (default: all) - limit: Maximum assets to return (default: 50, max: 100) Returns: - List of images with asset_urn, dimensions, status - List of videos with asset_urn, dimensions, duration, status - Total count of assets found Use this tool to: - Find existing images to reuse (saves time and ensures consistency) - Check what video assets are available for Video Ad campaigns - Avoid uploading duplicate assets Workflow: 1. Call `get_linkedin_organizations` first - get organization_id AND account_id 2. Call `discover_linkedin_assets` with both IDs 3. Use returned `asset_urn` in `create_linkedin_image_campaign` Execution time: 3-5 seconds # Explain LinkedIn Anomaly Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/explain-linkedin-anomaly /api-reference/openapi.json post /api/v1/tools/explain_linkedin_anomaly/execute User asks why their LinkedIn metrics changed, wants to understand a performance drop/spike, or says something like "My LinkedIn leads dropped 40%, why?" Explains significant metric changes with contributing factors: LinkedIn-Specific Factors Analyzed: - CPM changes (auction dynamics, competition) - CTR changes (creative effectiveness) - Audience saturation (B2B pools are smaller) - Seniority targeting shifts - Industry performance shifts - Company size targeting changes - Campaign changes (paused, new, budget) - B2B seasonal patterns (holidays, fiscal quarters) - Creative fatigue (14-day threshold) Returns: - Metric change summary (current vs previous) - Severity assessment (CRITICAL, HIGH, MEDIUM, LOW) - Contributing factors ranked by impact - Historical context (30/60/90 day averages) - Similar periods for comparison - Actionable recommendations - LinkedIn B2B-specific insights Parameters: - metric: Metric to analyze (required). Options: roas, ctr, cpc, cpm, conversions, conversion_rate, leads, engagement_rate, lead_form_completion_rate - period_start: Start date (YYYY-MM-DD format, required) - period_end: End date (YYYY-MM-DD format, required) - comparison_period_start: Optional comparison start date - comparison_period_end: Optional comparison end date - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "Why did my LinkedIn ROAS drop last week?" - "Explain the LinkedIn CTR decline in December" - "My LinkedIn leads dropped 40%, what happened?" - "Why did LinkedIn CPC increase?" Execution time: 4-6 seconds # Explain LinkedIn Objectives Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/explain-linkedin-objectives /api-reference/openapi.json post /api/v1/tools/explain_linkedin_objectives/execute User asks about LinkedIn campaign objectives or which one to choose. Explain all LinkedIn campaign objectives and recommend the best one. What this tool does: - Explains all 8 LinkedIn objectives in detail - Shows typical costs and expected results - Provides personalized recommendation based on user's goal - Helps user decide which objective to use Parameters: - business_type: Type of business (optional) - goal: What user wants to achieve (optional) Example Prompts: - "What objectives can I choose for LinkedIn?" - "Which objective should I use for my SaaS?" - "Explain LinkedIn campaign objectives" - "I want to get signups, which objective?" Execution time: `<`1 second # Generate LinkedIn Ad Creatives Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/generate-linkedin-ad-creatives /api-reference/openapi.json post /api/v1/tools/generate_linkedin_ad_creatives/execute User needs ad copy for LinkedIn campaigns. Generate multiple LinkedIn ad creative variations with different angles. What this tool does: - Creates 4 ad variations (problem-focused, solution-focused, social proof, curiosity) - Generates introductory text (600 char max) - Creates headlines (70 char max) - Suggests appropriate CTAs - Adds UTM tracking to landing pages Parameters: - business_name: Name of the business (required) - business_description: What the business does (required) - target_audience: Who to target (required) - value_proposition: Main benefit (required) - landing_page_url: Where to send traffic (required) - campaign_objective: Campaign goal (optional, default: WEBSITE_VISIT) - tone: Voice style (optional: professional, casual, urgent, inspirational) - include_stats: Include statistics (optional) - stats_to_include: Stats to use (optional) Returns: - 4 complete ad creative variations - Each with: intro text, headline, CTA, landing URL with UTM Example Prompts: - "Generate ad copy for my LinkedIn campaign" - "Create ad variations for my B2B SaaS" - "Help me write LinkedIn ads for my marketing tool" Execution time: `<`1 second # Get LinkedIn Audience Insights Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/get-linkedin-audience-insights /api-reference/openapi.json post /api/v1/tools/get_linkedin_audience_insights/execute User asks about B2B audience demographics, which professional segments perform best, targeting optimization, or wants to understand their LinkedIn audience breakdown. THIS IS LINKEDIN'S KILLER FEATURE - Professional demographic analysis: Returns B2B audience performance breakdown by: - Seniority (Entry, Senior, Manager, Director, VP, C-Suite) - Industry (Technology, Finance, Healthcare, etc.) - Company Size (1-10, 11-50, 51-200, 201-500, 501-1000, 1000+) - Job Function (Marketing, Sales, IT, Engineering, HR, etc.) Each segment includes: - Impressions, clicks, spend, conversions - CTR, CPL, ROAS, engagement rate - Category: SCALE, MAINTAIN, REDUCE, or EXCLUDE Identifies: - Best performing segments (to scale) - Underperforming segments (to reduce/exclude) - Wasted spend on B2B segments - Targeting optimization recommendations Parameters: - lookback_days: Number of days to analyze (7-120). Default: 30 - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - breakdown_types: Optional list of specific breakdowns. Default: all types - target_roas: Override target ROAS for categorization - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "Which seniority levels convert best on LinkedIn?" - "Show me LinkedIn audience breakdown by industry" - "What company sizes are we reaching on LinkedIn?" - "Am I reaching decision-makers on LinkedIn?" - "Which B2B segments should I exclude?" Execution time: 4-6 seconds # Get LinkedIn Campaign Performance Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/get-linkedin-campaign-performance /api-reference/openapi.json post /api/v1/tools/get_linkedin_campaign_performance/execute User asks about LinkedIn Ads performance, campaign metrics, B2B engagement, ROAS, or wants to understand how their LinkedIn campaigns are performing. Returns comprehensive LinkedIn Ads performance metrics including: - Account summary (total spend, impressions, clicks, CTR, conversions, ROAS) - LinkedIn-specific metrics (engagements, leads, cost per lead) - Campaign breakdown with performance categorization - Trend data (daily metrics, week-over-week, month-over-month changes) - Actionable recommendations Parameters: - lookback_days: Number of days to analyze (7, 14, 30, 60, 90). Default: 30 - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - include_campaigns: Include per-campaign breakdown. Default: true - include_trends: Include trend analysis. Default: true - include_comprehensive: Include creative/engagement analysis. Default: true - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "How are my LinkedIn ads performing?" - "Show me LinkedIn campaign performance for the last 30 days" - "What's my LinkedIn ROAS this month?" - "Which LinkedIn campaigns are performing best?" Execution time: 3-5 seconds # Get LinkedIn Campaign Structure Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/get-linkedin-campaign-structure /api-reference/openapi.json post /api/v1/tools/get_linkedin_campaign_structure/execute User wants full details about a specific LinkedIn campaign. Get complete campaign structure including creatives, targeting, and configuration. Returns: - Campaign details (name, status, objective, budget, schedule) - All creatives/ads linked to campaign - Full targeting criteria with resolved names - Conversion tracking setup - Campaign Manager link Parameters: - campaign_id: Campaign ID to fetch (required) - account_id: Optional LinkedIn Ad Account ID Example Prompts: - "Show me details for campaign 123456" - "What's the targeting for my LinkedIn campaign?" - "How many ads are in my campaign?" Execution time: 3-5 seconds # Get LinkedIn Campaign Targeting Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/get-linkedin-campaign-targeting /api-reference/openapi.json post /api/v1/tools/get_linkedin_campaign_targeting/execute User wants to copy targeting from one campaign to another. Get targeting criteria from a campaign in a format ready for reuse. Returns: - All targeting URNs with human-readable names - Format ready to pass to create_linkedin_image_campaign Use Case: 1. Get targeting from successful campaign 2. Use those URNs in a new campaign Execution time: 2-3 seconds # Get LinkedIn Engagement Metrics Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/get-linkedin-engagement-metrics /api-reference/openapi.json post /api/v1/tools/get_linkedin_engagement_metrics/execute User asks specifically about LinkedIn engagement, social actions, lead generation metrics, or video performance. Returns detailed LinkedIn engagement breakdown: - Social engagement (likes, comments, shares, follows, reactions) - Lead generation (one-click leads, form opens, completion rates) - Video metrics (views, starts, completions, watch rates) - Viral metrics (organic share impressions, clicks) - Engagement rate calculations and benchmarks Parameters: - lookback_days: Number of days to analyze (7-120). Default: 30 - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "Show me LinkedIn engagement metrics" - "How many leads did we generate on LinkedIn?" - "What's our LinkedIn video completion rate?" - "Are people sharing our LinkedIn ads?" Execution time: 2-3 seconds # Get LinkedIn Organizations Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/get-linkedin-organizations /api-reference/openapi.json post /api/v1/tools/get_linkedin_organizations/execute Fetch the LinkedIn Organizations (Company Pages) AND Ad Accounts the user can manage. IMPORTANT: Call this tool during campaign creation discovery phase to get both organization_id AND account_id. What this tool does: - Queries LinkedIn for all Company Pages the user has admin access to - Queries LinkedIn for all Ad Accounts the user can access - Returns organization IDs, names, AND ad account IDs - No parameters required - uses connected LinkedIn account Returns: - List of organizations with ID, name, and LinkedIn URL - List of ad accounts with ID, name, status, and linked organization - Both IDs needed for different operations Use this tool to: - Get the organization_id automatically (no need to ask user!) - Get the account_id for asset discovery (required for finding images/videos!) - Verify user has access to a Company Page - Find which page to use for Sponsored Content After getting organizations & accounts: - Use the `account_id` in `discover_linkedin_assets` to find existing images/videos - Use the `organization_id` in whichever campaign creation tool the user selected: - `create_linkedin_image_campaign` (Single Image) - `create_linkedin_video_campaign` (Video) - `create_linkedin_carousel_campaign` (Carousel) - `create_linkedin_text_campaign` (Text Ad) - Assets are tied to ad accounts, not organizations - that's why account_id is needed Execution time: 2-3 seconds # List LinkedIn Campaign Groups Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/list-linkedin-campaign-groups /api-reference/openapi.json post /api/v1/tools/list_linkedin_campaign_groups/execute User wants to see their LinkedIn campaign groups (also called campaign folders or groups). List all campaign groups with their status, budget, and campaign count. Parameters: - account_id: Optional LinkedIn Ad Account ID - status_filter: Filter by status (ACTIVE, PAUSED, ARCHIVED, or ALL) Returns: - All campaign groups with name, ID, status, budget, and campaign count Example Prompts: - "Show me my LinkedIn campaign groups" - "List all campaign groups" - "What campaign groups do I have?" - "Show active campaign groups" Execution time: 2-3 seconds # List LinkedIn Campaigns Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/list-linkedin-campaigns /api-reference/openapi.json post /api/v1/tools/list_linkedin_campaigns/execute User wants to see all their LinkedIn campaigns with performance metrics. List all LinkedIn campaigns with summary metrics (clicks, impressions, cost, CTR). Returns: - All campaigns grouped by status (Active, Paused, Other) - 30-day performance metrics for each campaign - Campaign Manager links Parameters: - account_id: Optional LinkedIn Ad Account ID - status_filter: Filter by status (ACTIVE, PAUSED, ALL) - limit: Maximum campaigns to return (default: 50) - lookback_days: Days for metrics (default: 30) Example Prompts: - "Show me my LinkedIn campaigns" - "List all active LinkedIn campaigns" - "What are my LinkedIn campaign metrics?" Execution time: 3-5 seconds # List LinkedIn Conversions Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/list-linkedin-conversions /api-reference/openapi.json post /api/v1/tools/list_linkedin_conversions/execute User wants to see available conversion tracking options. List all conversion rules for a LinkedIn ad account. Returns: - All conversions with ID, name, type, status - Attribution windows - Can be used to select conversions for campaigns Execution time: 2-3 seconds # List LinkedIn Creatives Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/list-linkedin-creatives /api-reference/openapi.json post /api/v1/tools/list_linkedin_creatives/execute User wants to see all ads in a LinkedIn campaign. List all creatives/ads for a specific campaign. Returns: - All creatives with ID, status, review status - Text preview and CTA - Campaign ID Execution time: 2-3 seconds # Manage LinkedIn Conversions Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/manage-linkedin-conversions /api-reference/openapi.json post /api/v1/tools/manage_linkedin_conversions/execute User wants to manage LinkedIn conversion tracking - list, create, associate conversions, or set up full conversion tracking. All-in-one conversion management tool with 4 actions: Actions: - `list`: Show all conversions for the account - `create`: Create a new conversion rule - `associate`: Link a conversion to a campaign - `setup`: Full setup - create conversion + associate with campaign in one step Parameters: - action: 'list', 'create', 'associate', or 'setup' (required) - name: Conversion name (for 'create' and 'setup') - type: Conversion type - LEAD, PURCHASE, SIGN_UP, KEY_PAGE_VIEW, etc. (default: LEAD) - url: URL for conversion rule matching - value: Fixed conversion value in USD - conversion_id: Conversion ID (for 'associate') - campaign_id: Campaign ID (for 'associate' and 'setup') - landing_page_url: Landing page URL (for 'setup') - account_id: Optional LinkedIn Ad Account ID Example Prompts: - "Show me my LinkedIn conversions" - "Set up conversion tracking for my campaign" - "Create a lead conversion for sign-ups" - "Associate conversion 123 with campaign 456" - "Track purchases on my landing page" - "Help me set up LinkedIn conversion tracking" Execution time: 2-5 seconds # Optimize LinkedIn Budget Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/optimize-linkedin-budget /api-reference/openapi.json post /api/v1/tools/optimize_linkedin_budget/execute User asks how to allocate their LinkedIn budget, wants budget optimization recommendations, or asks "How should I split my LinkedIn spend?" Uses linear programming to optimize budget allocation across campaigns: Optimization Process: 1. Analyzes historical campaign performance 2. Calculates efficiency scores (conversions or leads per dollar) 3. Uses scipy linear programming to find optimal allocation 4. Respects constraints (max change %, min budget, total budget) Returns: - Current vs Optimized budget allocation - Expected impact (conversion/lead lift) - Campaigns to SCALE, MAINTAIN, REDUCE, or PAUSE - Projected improvement percentage Constraints Applied: - Total budget = user specified amount - Max change per campaign (default 50%) - Min daily budget (LinkedIn minimum $10, default $20) - Only allocate to profitable campaigns (ROAS > 1.0) Parameters: - total_budget: Total monthly budget to allocate (required, > 0) - lookback_days: Historical data period (7-120). Default: 30 - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - target_roas: Target ROAS for optimization - max_change_percentage: Max budget change (0.3-0.7). Default: 0.5 - min_daily_budget: Minimum daily budget. Default: $20 - optimization_goal: 'conversions' or 'leads'. Default: conversions - ad_account_id: Required for multi-account users. Get from list_connected_accounts Example Prompts: - "How should I allocate $30K across LinkedIn campaigns?" - "Optimize my LinkedIn budget for leads" - "Which LinkedIn campaigns should get more budget?" - "How can I improve LinkedIn campaign efficiency?" Execution time: 4-6 seconds # Pause LinkedIn Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/pause-linkedin-campaign /api-reference/openapi.json post /api/v1/tools/pause_linkedin_campaign/execute User wants to pause an active LinkedIn campaign. Pause a campaign to stop serving impressions. Parameters: - campaign_id: Campaign ID to pause (required) - account_id: Optional LinkedIn Ad Account ID What happens: - Campaign status changes to PAUSED - No new impressions will be served - Campaign can be resumed later Execution time: 2-3 seconds # Pause LinkedIn Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/pause-linkedin-creative /api-reference/openapi.json post /api/v1/tools/pause_linkedin_creative/execute User wants to pause a specific ad within a campaign. Pause an individual creative/ad without affecting other ads in the campaign. Parameters: - creative_id: Creative ID to pause (required) - account_id: Optional LinkedIn Ad Account ID Use Case: - Pause underperforming ads - A/B test by pausing certain variations - Temporarily disable specific content Execution time: 2-3 seconds # Research Business For LinkedIn Targeting Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/research-business-for-linkedin-targeting /api-reference/openapi.json post /api/v1/tools/research_business_for_linkedin_targeting/execute User wants targeting recommendations based on their business. Analyze a business to derive appropriate LinkedIn targeting recommendations. What this tool does: - Analyzes business website URL and description - Identifies likely target audience based on business vertical - Recommends seniority levels, job functions, industries, company sizes - Suggests job titles and interests to search for Parameters: - website_url: Business website URL (required) - business_description: What the business does (optional) - ideal_customer_description: Who they want to reach (optional) - competitors: List of competitor names/websites (optional) Returns: - Recommended seniority URNs (copy directly) - Recommended company size URNs (copy directly) - Industry recommendations - Job function recommendations - Job title suggestions (use with search_linkedin_targeting) - Interest suggestions Example Prompts: - "Suggest LinkedIn targeting for my marketing SaaS" - "Who should I target for my HR software on LinkedIn?" - "Help me set up LinkedIn targeting for my B2B product" Execution time: 1-2 seconds # Resume LinkedIn Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/resume-linkedin-campaign /api-reference/openapi.json post /api/v1/tools/resume_linkedin_campaign/execute User wants to resume a paused LinkedIn campaign. Resume a paused campaign to start serving impressions again. Parameters: - campaign_id: Campaign ID to resume (required) - account_id: Optional LinkedIn Ad Account ID What happens: - Campaign status changes to ACTIVE - Impressions will start serving - Learning phase resumes Execution time: 2-3 seconds # Resume LinkedIn Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/resume-linkedin-creative /api-reference/openapi.json post /api/v1/tools/resume_linkedin_creative/execute User wants to resume a paused ad. Resume a paused creative/ad to include it in campaign rotation. Parameters: - creative_id: Creative ID to resume (required) - account_id: Optional LinkedIn Ad Account ID Execution time: 2-3 seconds # Search LinkedIn Targeting Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/search-linkedin-targeting /api-reference/openapi.json post /api/v1/tools/search_linkedin_targeting/execute User needs to find targeting URNs for LinkedIn campaigns. Search for targeting entities like job titles, industries, skills, locations, etc. Facet Types: - job_titles, industries, skills, locations - seniorities, company_sizes, job_functions - interests, degrees, fields_of_study - employers, groups Returns: - List of matching entities with URNs and names - URNs can be used in campaign targeting Example Prompts: - "Find LinkedIn targeting for software engineers" - "Search for marketing job titles on LinkedIn" - "Find LinkedIn industry targeting for SaaS" Execution time: 2-3 seconds # Select LinkedIn Campaign Type Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/select-linkedin-campaign-type /api-reference/openapi.json post /api/v1/tools/select_linkedin_campaign_type/execute User wants to create a LinkedIn ad campaign but hasn't specified the campaign type (image, video, carousel, or text). IMPORTANT: This tool should be called BEFORE any asset discovery or campaign creation when the user says things like: - "Create a LinkedIn campaign" - "Run LinkedIn ads" - "I want to advertise on LinkedIn" - "Set up a LinkedIn advertising campaign" - "Help me create ads on LinkedIn" This tool asks the user what TYPE of campaign they want to create, then provides guidance on the next steps including creative quantity best practices. Campaign Types Available: 1. image — Single image ad in the feed (most common, 4-5 ad variations recommended) 2. video — Video ad in the feed (good for demos, storytelling, 3-4 variations recommended) 3. carousel — 2-10 swipeable image cards (good for multi-product showcase, 3-5 cards recommended) 4. text — Simple desktop right-rail/top-banner ad (budget-friendly, 3-4 variations recommended) Returns: - Confirmation of selected campaign type - Specific requirements and creative specs for that type - Recommended number of ad variations per LinkedIn best practices - Next steps and which tool to use Do NOT use this tool if: - User specifically asks for "image campaign" / "single image" - go directly to image workflow - User specifically asks for "video campaign" / "video ad" - go directly to video workflow - User specifically asks for "carousel" / "multiple images" - go directly to carousel workflow - User specifically asks for "text ad" / "simple ad" - go directly to text workflow - User is asking about performance/analytics - use performance analysis tools Parameters: - campaign_type: 'image', 'video', 'carousel', or 'text' Execution time: Instant (no API call) # Update LinkedIn Campaign Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/update-linkedin-campaign /api-reference/openapi.json post /api/v1/tools/update_linkedin_campaign/execute User wants to modify LinkedIn campaign settings. Update campaign budget, schedule, targeting, or other settings. Updatable Fields: - name: Campaign name - daily_budget: Daily budget in account currency (min 10) - total_budget: Lifetime budget - status: ACTIVE, PAUSED, or ARCHIVED - start_date / end_date: Schedule - locations, industries, seniorities, job_titles, company_sizes: Targeting Parameters: - campaign_id: Campaign ID to update (required) - account_id: Optional LinkedIn Ad Account ID - [any updatable field]: New value Execution time: 2-3 seconds # Update LinkedIn Campaign Budget Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/update-linkedin-campaign-budget /api-reference/openapi.json post /api/v1/tools/update_linkedin_campaign_budget/execute User wants to change a LinkedIn campaign's budget (daily or total). Update campaign daily budget, total/lifetime budget, or remove budget caps. Parameters: - campaign_id: Campaign ID to update (required) - daily_budget: New daily budget in USD (minimum $10) - total_budget: New total/lifetime budget - remove_total_budget: Remove total budget cap (make unlimited) - account_id: Optional LinkedIn Ad Account ID Use this instead of `update_linkedin_campaign` when the user ONLY wants to change budget. Example Prompts: - "Increase my LinkedIn campaign budget to $50/day" - "Set total budget to $5000 for campaign 12345" - "Change daily budget to $25" - "Remove the budget cap on my campaign" - "Double my LinkedIn ad spend" Execution time: 2-3 seconds # Update LinkedIn Campaign Group Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/update-linkedin-campaign-group /api-reference/openapi.json post /api/v1/tools/update_linkedin_campaign_group/execute User wants to modify a LinkedIn campaign group (rename, change status, update budget). Update campaign group name, status, total budget, or end date. Parameters: - campaign_group_id: Campaign group ID to update (required) - name: New name for the group - status: New status (ACTIVE, PAUSED, or ARCHIVED) - total_budget: New total budget - end_date: New end date in ISO format - account_id: Optional LinkedIn Ad Account ID Note: Changes to a campaign group affect all campaigns within it. Example Prompts: - "Rename my campaign group to Q2 2026" - "Pause campaign group 12345" - "Set the budget for my campaign group" - "Update my LinkedIn campaign group" Execution time: 2-3 seconds # Update LinkedIn Campaign Schedule Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/update-linkedin-campaign-schedule /api-reference/openapi.json post /api/v1/tools/update_linkedin_campaign_schedule/execute User wants to change a LinkedIn campaign's end date or schedule. Update the campaign end date. Parameters: - campaign_id: Campaign ID to update (required) - end_date: New end date in ISO format, e.g. '2026-04-15T00:00:00Z' (required) - account_id: Optional LinkedIn Ad Account ID Example Prompts: - "Extend my campaign until April 15" - "Change the end date of campaign 12345" - "Set my LinkedIn campaign to end next month" - "Push the campaign deadline to June" Execution time: 2-3 seconds # Update LinkedIn Campaign Targeting Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/update-linkedin-campaign-targeting /api-reference/openapi.json post /api/v1/tools/update_linkedin_campaign_targeting/execute User wants to add or remove targeting criteria from a LinkedIn campaign. Smart targeting update - incrementally add or remove targeting facets without replacing everything. Parameters: - campaign_id: Campaign ID to update targeting for (required) - add_locations / remove_locations: Location URNs to add/remove - add_industries / remove_industries: Industry URNs to add/remove - add_seniorities / remove_seniorities: Seniority URNs to add/remove - add_job_titles / remove_job_titles: Job title URNs to add/remove - add_company_sizes / remove_company_sizes: Company size URNs to add/remove - replace_all: If True, replaces ALL targeting (default: False, incremental) - account_id: Optional LinkedIn Ad Account ID Use `search_linkedin_targeting` first to find the correct URNs for targeting criteria. Example Prompts: - "Add New York to my campaign targeting" - "Remove the finance industry from targeting" - "Target VP and C-suite in my campaign" - "Change targeting to include tech companies" - "Add software engineers to my ad targeting" Execution time: 3-5 seconds # Update LinkedIn Creative Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/update-linkedin-creative /api-reference/openapi.json post /api/v1/tools/update_linkedin_creative/execute User wants to edit a LinkedIn ad/creative. Update ad copy, headline, CTA, or status. Updatable Fields: - status: ACTIVE or PAUSED - introductory_text: Main ad copy (max 600 chars) - headline: Ad headline (max 70 chars) - call_to_action: CTA button label - landing_page_url: Destination URL Note: LinkedIn may re-review the creative after content changes. Execution time: 2-3 seconds # Validate And Prepare LinkedIn Assets Source: https://www.adspirer.com/docs/api-reference/linkedin-ads/validate-and-prepare-linkedin-assets /api-reference/openapi.json post /api/v1/tools/validate_and_prepare_linkedin_assets/execute User provides image URLs to validate BEFORE creating LinkedIn image campaign. Validate and prepare new image assets for LinkedIn ad campaigns. IMPORTANT: - Call `get_linkedin_organizations` FIRST to get organization_id AND account_id - Include `account_id` when calling this tool - it's REQUIRED for images to be discoverable later! LinkedIn Image Requirements: - Horizontal (Sponsored Content): 1200x627 pixels - Square (Sponsored Content): 1080x1080 pixels - Vertical (Stories/Mobile): 1200x1500 pixels - Carousel cards: 1080x1080 pixels (each card) - Maximum file size: 8MB - Formats: JPEG, PNG, GIF (non-animated) Parameters: - image_urls: List of public image URLs (e.g., from postimages.org, imgbb.com) - organization_id: LinkedIn Organization (Company Page) ID - account_id: LinkedIn Ad Account ID - REQUIRED for images to be discoverable via `discover_linkedin_assets`! - ad_type: Target ad type (single_image_horizontal, single_image_square, single_image_vertical, carousel) Returns: - Validation results for each image - asset_bundle_id (valid for 60 minutes) - Image URNs for reference Execution time: 5-15 seconds (downloads, validates, and uploads images) Workflow: 1. Call `get_linkedin_organizations` - get organization_id AND account_id 2. Call `validate_and_prepare_linkedin_assets` with BOTH organization_id AND account_id 3. Use returned `asset_bundle_id` in `create_linkedin_image_campaign` Why account_id matters: - Without account_id, images are uploaded but NOT associated with your ad account - This means `discover_linkedin_assets` won't find them later - Always include account_id to make images reusable! # Add Meta Ad Source: https://www.adspirer.com/docs/api-reference/meta-ads/add-meta-ad /api-reference/openapi.json post /api/v1/tools/add_meta_ad/execute User wants to add another ad/creative variation to an EXISTING ad set. DO NOT USE to create a new campaign. For new campaigns: - Video campaign - `create_meta_video_campaign` - Image campaign - `create_meta_image_campaign` - Carousel campaign - `create_meta_carousel_campaign` Common scenarios: - A/B test ad copy: Different headlines, primary text, or CTAs for the same audience - A/B test creatives: Different images or videos for the same audience - Format testing within one audience: Image vs video ad in the same ad set - Dynamic Creative (DCO): Multiple images + text variations in one ad — Meta auto-optimizes KEY DISTINCTION — add_meta_ad vs add_meta_ad_set: - Same audience, different creative/copy - use THIS tool (add_meta_ad) - Different audience/targeting - use `add_meta_ad_set` instead (creates a new ad set) Ads in the same ad set SHARE: targeting, budget, schedule, pixel tracking. Each ad has its OWN: creative (image/video/carousel), headline, primary text, CTA, landing page. IMPORTANT: You need an ad_set_id from a previously created ad set. Use `list_meta_ad_sets` first if you don't have the ad_set_id. Supports all 3 ad types + Dynamic Creative: - `image`: Different image + copy variation - `video`: Different video + copy variation - `carousel`: Different card set + copy variation - **Dynamic Creative (DCO)**: Pass `image_urls` (2-10 images), `headlines` (up to 5), `primary_texts` (up to 5), `descriptions` (up to 5). Meta tests ALL combinations and optimizes delivery automatically. Dynamic Creative Optimization (DCO) workflow: 1. Create ad set with `is_dynamic_creative=true` via `add_meta_ad_set` 2. Call this tool with `image_urls` (list of 2-10 image URLs), plus optional `headlines`, `primary_texts`, `descriptions` arrays 3. Meta will test all image × headline × text combinations and optimize 4. DCO ad sets support only 1 ad — if the ad set already has is_dynamic_creative enabled, this tool auto-detects it Note: Cannot mix image_urls (DCO) with image_url (single image) or placement-specific images. Standard workflow: 1. Get ad_set_id from prior campaign creation or `list_meta_ad_sets` 2. Write variant ad copy (different headline/primary_text/image) 3. Call this tool with ad_set_id + new creative + copy # Add Meta Ad Set Source: https://www.adspirer.com/docs/api-reference/meta-ads/add-meta-ad-set /api-reference/openapi.json post /api/v1/tools/add_meta_ad_set/execute User wants to add a new ad set to an EXISTING campaign. Common scenarios: - Audience testing: Same ad format, different targeting/interests per ad set (e.g., "4 ad sets with different interests") - Multi-format: Different ad types (image + video + carousel) under one campaign - Budget split: Same creative, different budgets per audience segment - Scaling: Adding new audiences/markets to an existing campaign - Geographic split: Same ad, different locations per ad set - Dynamic Creative (DCO): Set is_dynamic_creative=true, then use add_meta_ad with image_urls/headlines/primary_texts CRITICAL: Each `create_meta_*_campaign` creates a NEW campaign. To add more ad sets to the SAME campaign, you MUST use this tool. NEVER call create_meta_*_campaign again for the same campaign. IMPORTANT: You need a campaign_id from a previously created campaign. Use `get_meta_campaign_details` first if you don't have the campaign_id. Supports all 3 ad types: - `image`: Provide image_url, existing_image_hash, or asset_bundle_id - `video`: Provide video_url or existing_video_id - `carousel`: Provide cards array (2-10 cards) Dynamic Creative Optimization (DCO): - Set `is_dynamic_creative=true` when creating the ad set - Then use `add_meta_ad` with `image_urls` (2-10), `headlines` (up to 5), `primary_texts` (up to 5) to add a DCO ad - Meta automatically tests all asset combinations and optimizes delivery - DCO ad sets support only 1 ad — one ad with multiple asset variations Each ad set has INDEPENDENT: targeting, budget, schedule, pixel/conversion tracking. Shared from campaign: objective, campaign name. **CBO (Advantage Campaign Budget) campaigns:** If the campaign uses CBO (campaign_budget_optimization=true when created), you MUST: - Set `campaign_budget_optimization: true` on this tool call - Do NOT set `budget_daily` (budget is managed at campaign level) - Optionally set `daily_min_spend_target` and `daily_spend_cap` to control spend distribution If the campaign does NOT use CBO, `budget_daily` is required as usual. Workflow: 1. Create initial campaign with `create_meta_*_campaign` - get campaign_id 2. Call this tool with the campaign_id for each additional ad set 3. Use `add_meta_ad` to add more ad copies/creatives within any ad set # Analyze Meta Ad Performance Source: https://www.adspirer.com/docs/api-reference/meta-ads/analyze-meta-ad-performance /api-reference/openapi.json post /api/v1/tools/analyze_meta_ad_performance/execute User wants detailed analysis of specific Meta ads, creative performance, or wants to identify winning/losing ad variations. This tool provides ad-level and creative-level insights for Meta campaigns. Returns: - Top performing ads by CTR and conversion rate - Underperforming ads that need attention - Creative fatigue indicators (high frequency, declining CTR) - Video completion metrics (25%, 50%, 75%, 100% watched) - Creative optimization recommendations When to use this tool: - "Which of my Meta ads are performing best?" - "Are any of my Facebook ads fatigued?" - "Show me my Instagram video ad performance" - "Which creatives should I pause?" - "Analyze my ad variations" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - campaign_id: Optional - filter to specific campaign - include_video_metrics: true (default) or false - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 1-3 seconds (cached database query) Data source: ad_group_daily_metrics table (Meta ad sets stored as ad groups) Creative fatigue detection: - High frequency (>4.0) with declining CTR - CTR dropped >20% from first week - Same creative running >14 days without refresh # Analyze Meta Audiences Source: https://www.adspirer.com/docs/api-reference/meta-ads/analyze-meta-audiences /api-reference/openapi.json post /api/v1/tools/analyze_meta_audiences/execute User asks about Meta/Facebook/Instagram audience performance by demographics, age group or gender targeting optimization, audience saturation, or which demographic segments to target or exclude. This tool provides deep analysis of audience segment performance and detects audience saturation to optimize demographic targeting for Meta Ads. Returns: - Age group performance breakdown (18-24, 25-34, 35-44, 45-54, 55-64, 65+) - Gender performance breakdown (male, female, unknown) - Age + Gender combination analysis - Segments categorized as SCALE/MAINTAIN/REDUCE/EXCLUDE based on ROAS - Audience saturation score (0-100) with contributing factors - Best performing segments to scale - Underperforming segments to reduce/exclude - Targeting optimization recommendations - Quick actionable items When to use this tool: - "Which age groups perform best for my Meta ads?" - "Should I target men or women on Facebook?" - "Is my Meta audience saturated?" - "Which demographics should I exclude?" - "Analyze my Instagram audience performance" - "Best demographic targeting for my Facebook campaigns" - "Age and gender breakdown for my Meta ads" - "Are my lookalike audiences exhausted?" - "Which audience segments are wasting money?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - breakdown_type: 'age', 'gender', 'age_gender', or 'all' (default) - include_saturation: Include saturation analysis (default: True) - target_roas: Optional override (default: from account goals or 2.0x) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: meta_audience_daily_metrics table (demographic-level daily metrics) ROAS Thresholds for Segment Recommendations: - 🚀 SCALE (ROAS ≥ 1.5x target): Increase budget to this segment - ➖ MAINTAIN (ROAS 0.75x-1.5x target): Keep current allocation - ⚠️ REDUCE (ROAS 0.5x-0.75x target): Decrease budget - 🔴 EXCLUDE (ROAS `<` 0.5x target): Remove from targeting Saturation Score Factors (weighted): - Frequency Score (35%): How often users see ads (>3 indicates fatigue) - CTR Decline Score (30%): Week-over-week CTR changes - CPA Increase Score (25%): Rising cost per acquisition - Reach Saturation Score (10%): Audience reach exhaustion Saturation Levels: - ✅ HEALTHY (`<`40): Audience is fresh, continue scaling - 🟡 AT_RISK (40-69): Monitor frequency, prepare new audiences - 🔴 SATURATED (≥70): Expand targeting or refresh creatives Common Insights: - Age 25-44 typically has highest ROAS for e-commerce - Gender targeting varies significantly by product category - High frequency (>4) combined with declining CTR indicates saturation - Lookalike audiences can exhaust within 4-8 weeks at high spend # Analyze Meta Wasted Spend Source: https://www.adspirer.com/docs/api-reference/meta-ads/analyze-meta-wasted-spend /api-reference/openapi.json post /api/v1/tools/analyze_meta_wasted_spend/execute User asks about Meta/Facebook/Instagram ad spend efficiency, wasted money, underperforming campaigns, placement optimization, or creative fatigue. This tool identifies Meta Ads campaigns and placements that are wasting money by performing below target ROAS or below breakeven (ROAS `<` 1.0). It extends the base wasted spend detector with Meta-specific features: Returns: - Campaign-level wasted spend analysis (ROAS `<` 1.0 = actual losses) - Underperforming spend analysis (1.0 `<`= ROAS `<` target = opportunity cost) - Placement-level breakdown (which placements are wasting money: Feed, Stories, Reels, etc.) - Creative fatigue detection (high frequency + declining CTR) - Actionable recommendations for campaigns, placements, and creatives - Quick action items When to use this tool: - "Where am I wasting money on Meta/Facebook ads?" - "Which Meta placements should I exclude?" - "Are any of my Facebook creatives fatigued?" - "How can I reduce wasted ad spend on Instagram?" - "Which Meta campaigns are losing money?" - "What's my Meta ROAS by placement?" Parameters: - lookback_days: 7, 30 (default), 60, 90, or 120 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - target_roas: Optional override (e.g., 3.0 for 3.0x ROAS) - include_placements: true (default) - Include placement-level analysis - include_fatigue: true (default) - Include creative fatigue analysis - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: campaign_daily_metrics + meta_placement_daily_metrics + meta_ad_creative_metrics tables Key definitions: - Wasted Spend (ROAS `<` 1.0): Actual money lost - for every $1 spent, getting back `<`$1 - Underperforming (1.0 `<`= ROAS `<` target): Profitable but below target - opportunity cost - Creative Fatigue: Ads with frequency >4x (cold traffic) or >7x (retargeting) showing declining CTR Meta-specific placement optimization: - Audience Network often has lowest ROAS - consider excluding - Instagram Stories/Reels typically perform differently than Feed - Facebook Marketplace can waste spend if not relevant **Quick Actions (IMPORTANT — read severity context first):** - ⏳ LEARNING campaigns → Do NOT pause. Monitor for 14+ days before judging. - ❓ INSUFFICIENT_DATA campaigns → Need more spend before analysis is meaningful. - 🚨 CRITICAL campaigns (established, 14+ days, ZERO conversions) → Consider pausing - 🚨 CRITICAL campaigns (established, 14+ days, HAS conversions) → Review performance, verify revenue in ad platform before reducing budget - 🔴 HIGH severity (established, 14+ days) → Consider reducing budget by 50-70% - 🟡 MEDIUM → Optimize targeting, ad copy, landing pages ⚠️ **NEVER say "pause" for a campaign that has conversions.** Say "review" or "reduce budget" instead. ⚠️ **NEVER recommend pausing a campaign in LEARNING phase.** ⚠️ **If ALL campaigns are LEARNING or INSUFFICIENT_DATA, tell the user their account is too new for waste analysis and recommend checking back in 2 weeks.** ⚠️ **Consider campaign objective: brand awareness campaigns will not have ROAS data. This is normal.** ⚠️ **When data confidence is MEDIUM or LOW, soften all recommendations and add verification prompts.** # Browse Meta Targeting Source: https://www.adspirer.com/docs/api-reference/meta-ads/browse-meta-targeting /api-reference/openapi.json post /api/v1/tools/browse_meta_targeting/execute User wants to browse all targeting options in a specific category without a search query. This tool retrieves all options in a Meta targeting category for exploration and discovery. Returns: - List of all targeting options in the category - IDs, names, and audience sizes - Useful for discovering targeting options when user doesn't have a specific query When to use this tool: - "Show me all available behaviors for Meta targeting" - "What interest categories are available?" - "Browse demographic targeting options" - "List all life events I can target" - "What income targeting options exist?" Categories Available: - interests: All interest targeting categories - behaviors: All behavior targeting options - demographics: All demographic targeting options - life_events: All life event targeting options - industries: Industry targeting options - income: Income bracket targeting options - family_statuses: Family status targeting options Parameters: - category: Category to browse (required) - limit: Maximum results (1-500, default: 100) - locale: Locale for results (default: en_US) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 1-3 seconds Data source: Meta Marketing API Targeting Search # Create Meta Carousel Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/create-meta-carousel-campaign /api-reference/openapi.json post /api/v1/tools/create_meta_carousel_campaign/execute User wants to create a Meta (Facebook/Instagram) carousel ad campaign with multiple images. REQUIRED: You MUST call `select_meta_campaign_type` first and complete ALL phases it describes (audience targeting research via `search_meta_targeting`/`browse_meta_targeting`, asset discovery via `discover_meta_assets`, and user approval) BEFORE calling this tool. IMPORTANT: This tool creates REAL campaigns that will spend money once activated. Campaign is created in PAUSED status for review. DO NOT USE for single image - use `create_meta_image_campaign` instead. DO NOT USE for video - use `create_meta_video_campaign` instead. This tool creates a complete Meta carousel campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Multiple Image Uploads (one per card) 4. Ad Creative (carousel with child_attachments) 5. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook carousel ad" - "Launch an Instagram carousel campaign" - "Create a multi-product ad" - "Set up an ad with multiple images" Required Parameters: - campaign_name: Name for the campaign - budget_daily: Daily budget in USD (min $1, recommend $5-20 for testing) - primary_text: Main ad text (recommended 125 chars for optimal display, longer text shows with "See More") - cards: Array of 2-10 cards (see card structure below) Card Structure (each card requires): - image_url OR image_hash: Image source (one required) - landing_page_url: Where users go when clicking this card - headline: Card headline (max 45 chars) - description: Optional card description (max 20 chars) - call_to_action: Optional per-card CTA override Optional Parameters: - facebook_page_id: Auto-detected from connected account - instagram_account_id: Enable Instagram placements - call_to_action: Default CTA for all cards (LEARN_MORE by default) - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS - locations: Country codes (default: ['US']) - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - multi_share_optimized: Let Meta optimize card order (default: true) - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) After Creation — IMPORTANT: - This tool created 1 campaign + 1 ad set + 1 ad. - To add MORE ad sets (different targeting, audiences, or formats), use `add_meta_ad_set` with the returned campaign_id - To add MORE ads to the same ad set (A/B test copy/creative), use `add_meta_ad` with the returned ad_set_id - NEVER call this create tool again for the same campaign — that creates a SEPARATE campaign # Create Meta DCO Ad Source: https://www.adspirer.com/docs/api-reference/meta-ads/create-meta-dco-ad /api-reference/openapi.json post /api/v1/tools/create_meta_dco_ad/execute User wants Meta to automatically TEST MULTIPLE IMAGES and find the best combination. This is Dynamic Creative Optimization (DCO). Meta tests all combinations of images × headlines × primary texts and optimizes delivery automatically. USE THIS TOOL when the user says ANY of these: - "test these images" / "test multiple images" - "let Meta find the winner" / "let Meta optimize" - "Dynamic Creative" / "DCO" - "which image performs best" - Provides multiple images and wants Meta to choose the best - "test combinations" / "mix and match" - "10 images × 5 headlines" DO NOT USE add_meta_ad multiple times for this — that creates separate ads (A/B test). DCO is ONE ad with multiple assets that Meta mixes and optimizes. Prerequisites: 1. You need an ad_set_id with is_dynamic_creative=true 2. If the user doesn't have one, first call `add_meta_ad_set` with `is_dynamic_creative=true` 3. Then call this tool with the image_urls and text variations Asset limits (from Meta): - Images: 2-10 (required) - Headlines: up to 5 (optional) - Primary texts: up to 5 (optional) - Descriptions: up to 5 (optional) - Total assets: max 30 DCO ad sets support only 1 ad — do NOT add more ads to a DCO ad set. Example: 5 images × 3 headlines × 2 primary texts = 30 combinations, Meta finds the winner. # Create Meta Image Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/create-meta-image-campaign /api-reference/openapi.json post /api/v1/tools/create_meta_image_campaign/execute User wants to create a Meta (Facebook/Instagram) single-image ad campaign. REQUIRED: You MUST call `select_meta_campaign_type` first and complete ALL phases it describes (audience targeting research via `search_meta_targeting`/`browse_meta_targeting`, asset discovery via `discover_meta_assets`, and user approval) BEFORE calling this tool. IMPORTANT: This tool creates REAL campaigns that will spend money once activated. Campaign is created in PAUSED status for review. DO NOT USE for video ads - use `create_meta_video_campaign` instead. DO NOT USE for carousel/multi-image - use `create_meta_carousel_campaign` instead. This tool creates a complete Meta campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Ad Creative (image, text, CTA) 4. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook ad campaign" - "Launch an Instagram image ad" - "Set up a Meta traffic campaign" - "Create an ad with this image" Required Parameters: - campaign_name: Name for the campaign - budget_daily: Daily budget in USD (min $1, recommend $5-20 for testing) - primary_text: Main ad text (recommended 125 chars for optimal display, longer text shows with "See More") - headline: Headline below image (max 255 chars, recommended 40) - landing_page_url: Where users go when clicking Image Source (choose ONE): - asset_bundle_id: From `validate_and_prepare_meta_assets` (recommended for new images) - existing_image_hash: From `discover_meta_assets` (for reusing existing images) - image_url: Direct URL (uploaded during creation - use validate_and_prepare for better error handling) Optional Parameters: - facebook_page_id: Auto-detected from connected account. Only provide if multiple pages. - instagram_account_id: Auto-detected if linked. Enable Instagram placements. - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS - call_to_action: LEARN_MORE (default), SHOP_NOW, SIGN_UP, etc. - locations: Country codes (default: ['US']) or location objects from search_meta_targeting - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) - story_image_url: Different image for Stories/Reels (9:16, 1080x1920px). Uses asset_feed_spec. - right_column_image_url: Different image for Right Column (1.91:1, 1200x628px). Uses asset_feed_spec. Multi-Placement Creatives: If the user wants different images for different placements (Feed, Stories, Right Column), provide story_image_url and/or right_column_image_url. The main image will be used for Feed. This uses Meta's asset_feed_spec with asset_customization_rules instead of object_story_spec. After Creation — IMPORTANT: - This tool created 1 campaign + 1 ad set + 1 ad. - To add MORE ad sets (different targeting, audiences, or formats), use `add_meta_ad_set` with the returned campaign_id - To add MORE ads to the same ad set (A/B test copy/creative), use `add_meta_ad` with the returned ad_set_id - NEVER call this create tool again for the same campaign — that creates a SEPARATE campaign # Create Meta Video Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/create-meta-video-campaign /api-reference/openapi.json post /api/v1/tools/create_meta_video_campaign/execute User wants to create a Meta (Facebook/Instagram) video ad campaign. REQUIRED: You MUST call `select_meta_campaign_type` first and complete ALL phases it describes (audience targeting research via `search_meta_targeting`/`browse_meta_targeting`, asset discovery via `discover_meta_assets`, and user approval) BEFORE calling this tool. IMPORTANT: This tool creates REAL campaigns that will spend money once activated. Campaign is created in PAUSED status for review. DO NOT USE for image ads - use `create_meta_image_campaign` instead. DO NOT USE for carousel - use `create_meta_carousel_campaign` instead. This tool creates a complete Meta video campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Video Upload (handles large files with chunked upload) 4. Ad Creative (video, text, CTA) 5. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook video ad campaign" - "Launch an Instagram video ad" - "Set up a Meta Reels campaign" - "Create an ad with this video" Required Parameters: - campaign_name: Name for the campaign - budget_daily: Daily budget in USD (min $1, recommend $5-20 for testing) - primary_text: Main ad text (recommended 125 chars for optimal display, longer text shows with "See More") - landing_page_url: Where users go when clicking Video Source (choose ONE): - video_url: Public video URL (will be uploaded during creation) - existing_video_id: Existing Meta video ID (for reusing previously uploaded videos) Optional Parameters: - facebook_page_id: Auto-detected from connected account - instagram_account_id: Enable Instagram placements - thumbnail_url: Custom thumbnail image (Meta auto-generates if not provided) - headline: Headline below video (optional for video ads) - description: Description text (max 255 chars, recommended 30) - call_to_action: WATCH_MORE (default), LEARN_MORE, SHOP_NOW, etc. - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS - locations: Country codes (default: ['US']) - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - optimize_for_reels: true for vertical (9:16) videos - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) Video Specifications: - Formats: MP4, MOV (recommended: MP4 H.264) - Max size: 4GB (recommended under 1GB) - Duration: 1 sec - 240 min (recommended 15-60 sec) - Feed: 1:1 or 4:5 aspect ratio - Stories/Reels: 9:16 aspect ratio After Creation — IMPORTANT: - This tool created 1 campaign + 1 ad set + 1 ad. - To add MORE ad sets (different targeting, audiences, or formats), use `add_meta_ad_set` with the returned campaign_id - To add MORE ads to the same ad set (A/B test copy/creative), use `add_meta_ad` with the returned ad_set_id - NEVER call this create tool again for the same campaign — that creates a SEPARATE campaign # Detect Meta Creative Fatigue Source: https://www.adspirer.com/docs/api-reference/meta-ads/detect-meta-creative-fatigue /api-reference/openapi.json post /api/v1/tools/detect_meta_creative_fatigue/execute User asks about creative fatigue, ad refresh timing, frequency management, declining CTR, when to replace ads, or audience exhaustion on Meta/Facebook/Instagram. This tool analyzes all Meta Ads creatives for fatigue indicators using frequency-CTR correlation analysis and provides a fatigue score (0-100) for each ad. Returns: - Fatigue score (0-100) for each ad based on weighted factors - Severely fatigued ads (score ≥80) - immediate action required - At-risk ads (score 50-79) - plan refresh within 7-14 days - Healthy ads count - Daily spend being wasted on fatigued creatives - Projected monthly waste - Refresh schedule recommendations - Contributing factors for each fatigued ad When to use this tool: - "Are any of my Meta/Facebook/Instagram ads fatigued?" - "When should I refresh my creatives?" - "Why is my CTR declining?" - "Which ads have high frequency?" - "How much am I wasting on fatigued ads?" - "What's my ad refresh schedule?" - "Are my retargeting ads showing too often?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - frequency_threshold_cold: 2.0-8.0 (default: 4.0) - threshold for cold traffic audiences - frequency_threshold_retargeting: 4.0-10.0 (default: 7.0) - threshold for retargeting audiences - ctr_decline_threshold: 0.10-0.50 (default: 0.20 = 20%) - CTR decline to flag as fatigued - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: meta_ad_creative_metrics table (ad-level daily metrics with frequency, CTR, video completion) Fatigue Score Calculation: The fatigue score (0-100) is calculated using weighted factors: - Frequency (40%): impressions/reach ratio vs threshold - CTR Decline (35%): % drop in CTR vs previous period - Days Running (25%): creative age vs optimal refresh timing Severity Levels: - 🔴 Score ≥80: Severely fatigued - PAUSE immediately and replace - 🟡 Score 50-79: At risk - prepare replacement within 7-14 days - ✅ Score `<`50: Healthy - continue monitoring Best practices: - Cold traffic: Refresh creatives when frequency reaches 3-4x - Retargeting: Can tolerate higher frequency (up to 6-7x) - Create 3-5 variations per ad set for automatic rotation - Monitor weekly for frequency and CTR trends # Discover Meta Assets Source: https://www.adspirer.com/docs/api-reference/meta-ads/discover-meta-assets /api-reference/openapi.json post /api/v1/tools/discover_meta_assets/execute User wants to browse existing images in their Meta Ad Library for reuse in new campaigns. This tool retrieves existing images that have been uploaded to Meta's Ad Library, allowing users to reuse them in new campaigns without uploading again. Returns: - List of existing images with their hashes - Image dimensions and thumbnails - Created timestamps - Instructions for using images in campaigns When to use this tool: - "Show me my existing Meta ad images" - "What images do I already have in Meta?" - "I want to reuse an existing image for my campaign" - "List my Facebook ad library images" - Before uploading new images - check if they already exist Parameters: - ad_account_id: Required for multi-account users. Get from list_connected_accounts - limit: Max images to return (default 50, max 100) Execution time: 2-5 seconds Data source: Meta Ad Library API (live) Workflow: 1. Use `discover_meta_assets` to find existing images 2. Copy the `image_hash` from an image you want to use 3. Use that hash with `create_meta_image_campaign` via the `existing_image_hash` parameter # Duplicate Meta Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/duplicate-meta-campaign /api-reference/openapi.json post /api/v1/tools/duplicate_meta_campaign/execute User wants to duplicate/copy an existing Meta campaign with all its ad sets, ads, and settings. IMPORTANT: This creates a NEW real campaign in Meta Ads. The duplicate starts in PAUSED status by default for review. This tool copies the entire campaign structure including: - Campaign settings (objective, budget strategy) - All ad sets (targeting, budgets, schedules) - All ads (creatives, text, CTAs) Returns: - Original and new campaign IDs - New campaign status - Ads Manager URL for the new campaign - Next steps for review and activation When to use this tool: - "Duplicate my campaign" - "Copy campaign [ID]" - "Create a copy of this campaign" - "I want to A/B test with a copy of my campaign" - "Clone my campaign with different targeting" Parameters: - campaign_id: The Meta Campaign ID to duplicate (required) - new_name: Name for the new campaign (optional, defaults to original + " - Copy") - status: Status for new campaign — 'PAUSED' (default, recommended) or 'ACTIVE' Execution time: 10-30 seconds (depends on campaign size) Creates: New real campaign in Meta Ads Common use cases: 1. A/B Testing: Duplicate, then modify targeting or creative on the copy 2. Seasonal variants: Copy a proven campaign, update copy and dates 3. New market expansion: Duplicate, change location targeting 4. Budget testing: Copy, change budget levels Workflow: 1. Use `list_meta_campaigns` to find the campaign ID 2. Use `duplicate_meta_campaign` to create the copy 3. Use `update_meta_campaign` or `update_meta_ad_set` to modify the copy 4. Use `resume_meta_campaign` when ready to launch # Explain Meta Anomaly Source: https://www.adspirer.com/docs/api-reference/meta-ads/explain-meta-anomaly /api-reference/openapi.json post /api/v1/tools/explain_meta_anomaly/execute User asks why Meta/Facebook/Instagram performance dropped or changed, what happened to their ROAS/CTR/CPM, or wants to understand why a metric changed during a specific period. This tool analyzes why a specific metric changed during a specified period by comparing it to historical baselines and identifying contributing factors. It detects Meta-specific causes including creative fatigue, audience saturation, placement mix shifts, and auction competition. Returns: - Current metric value vs historical averages (30/60/90-day) - Deviation percentages from baselines - Contributing factors ranked by estimated impact - Factor explanations with details - Similar historical periods with comparable changes - Assessment of anomaly severity (CRITICAL/WARNING/MINOR/NORMAL) - Specific recommendations based on detected factors - Quick actionable items When to use this tool: - "Why did my Meta ROAS drop?" - "What happened to my Facebook CTR this week?" - "Why is my Instagram CPM so high?" - "Explain my Meta performance change" - "My conversions dropped last week - why?" - "Why did my frequency spike?" - "What caused my ROAS to decline 40%?" - "Diagnose my Meta performance problem" Parameters: - metric: Required - 'roas', 'ctr', 'cpc', 'cpm', 'conversions', 'conversion_rate', 'frequency', or 'reach' - period_start: Required - Start date (YYYY-MM-DD format) - period_end: Required - End date (YYYY-MM-DD format, must be ≤30 days from start) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 3-8 seconds (statistical analysis across multiple periods) Data source: campaign_daily_metrics + meta_placement_daily_metrics + meta_ad_creative_metrics tables Contributing Factors Detected: - CPM Change: Auction competition fluctuations (holidays, competitor activity) - CTR Change: Creative performance (fatigue, messaging, targeting) - Conversion Rate Change: Landing page or offer issues - Frequency Change: Audience saturation (Meta-specific) - Creative Fatigue: High frequency + declining CTR (Meta-specific) - Placement Mix Change: Shift in placement distribution (Meta-specific) - Campaign Changes: Paused/new campaigns affecting overall performance Severity Levels: - 🔴 CRITICAL (≥40% deviation): Immediate action required - 🟡 WARNING (25-40% deviation): Review recommended - 🟢 MINOR (15-25% deviation): Monitor situation - ✅ NORMAL (`<`15% deviation): Within normal variation Similar Historical Periods: Finds past periods with comparable deviations to provide context (e.g., "similar drop occurred during Black Friday 2024") Best for: - Diagnosing sudden performance drops - Understanding seasonal patterns - Identifying actionable causes vs. external factors - Prioritizing optimization efforts # Get Meta Ad Creatives Source: https://www.adspirer.com/docs/api-reference/meta-ads/get-meta-ad-creatives /api-reference/openapi.json post /api/v1/tools/get_meta_ad_creatives/execute User wants to see their Meta ad creatives, ad copy, media URLs, or creative performance. Returns ad-level data including full creative content and media URLs alongside performance metrics. When to use this tool: - "Show me my Meta ad creatives" - "What ads are running and how are they performing?" - "Show me the headlines and images for my ads" - "Which ad creatives are performing best?" - "What's the creative content for campaign X?" - "Show me ad performance with creative details" - "Get me the image URLs for my ads" - "Export my ad copy" - "What images and videos are my ads using?" Returns per ad — ALWAYS display ALL of these fields when present: - Ad copy: headline, primary_text, description, call_to_action_type - Media URLs: image_url (direct CDN link to ad image), thumbnail_url, video_url (playable video source), video_id - Landing page: landing_page_url - Carousel cards: carousel_cards array with per-card image_url, headline, description, landing_page_url - Performance: spend, impressions, clicks, CTR, CPC, reach, frequency - Video engagement: 25%, 50%, 75%, 100% watched (for video ads) - Creative metadata: creative_type (image/video/carousel/dynamic_creative), first_seen_date IMPORTANT: Always show the full image_url, thumbnail_url, video_url, and landing_page_url values — these are direct CDN links users need to download/export their creative media. Do not summarize or omit URLs. Parameters: - lookback_days: Number of days to analyze (7, 14, 30, 60, 90). Default: 30 - campaign_id: Optional filter to specific campaign - ad_set_id: Optional filter to specific ad set - ad_account_id: Required for multi-account users. Get from list_connected_accounts - start_date/end_date: Optional custom date range (overrides lookback_days) - limit: Max ads per page (default 20, max 50). Use for pagination. - offset: Number of ads to skip (default 0). Use with limit to page through results. Pagination: Results are paginated. Response includes total_ads count and has_more flag. To get next page, increase offset by limit. Execution time: 1-3 seconds Data source: Cached database (collected daily) # Get Meta Audience Insights Source: https://www.adspirer.com/docs/api-reference/meta-ads/get-meta-audience-insights /api-reference/openapi.json post /api/v1/tools/get_meta_audience_insights/execute User asks about audience demographics, which placements perform best, device breakdown, or targeting optimization for Meta ads. This tool provides audience and placement analysis for Meta campaigns. Returns: - Age group performance (18-24, 25-34, 35-44, 45-54, 55-64, 65+) - Gender performance breakdown - Placement breakdown (Facebook Feed, Instagram Feed, Stories, Reels, Messenger) - Device breakdown (Mobile, Desktop, Tablet) - Best performing audience segments - Targeting recommendations When to use this tool: - "What age group performs best for my Meta ads?" - "Should I target men or women?" - "Which placements should I use?" - "Do my Instagram Stories ads perform well?" - "Mobile vs desktop performance on Facebook?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - breakdown_type: 'age', 'gender', 'placement', 'device', or 'all' (default) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 1-3 seconds (cached database query) Data source: Cached database (aggregate metrics only - detailed breakdown requires live API) Common insights: - Meta audiences typically skew mobile (70-85%) - Instagram tends to perform better with 18-34 age groups - Facebook Feed often has highest reach but Stories may have better engagement - Reels placement growing rapidly in 2024-2025 # Get Meta Campaign Details Source: https://www.adspirer.com/docs/api-reference/meta-ads/get-meta-campaign-details /api-reference/openapi.json post /api/v1/tools/get_meta_campaign_details/execute User wants to see detailed information about a specific Meta campaign, including its full structure (ad sets, ads, targeting, budgets). This tool retrieves comprehensive details about a single campaign. With `include_hierarchy=true`, it shows the complete campaign tree: Campaign - Ad Sets - Ads. Returns: - Campaign settings (name, status, objective, budget, bid strategy, schedule) - Performance summary (impressions, clicks, spend, reach, CTR, CPC) - Ads Manager URL - When include_hierarchy=true: Full structure with all ad sets and their ads, targeting details, hierarchy stats When to use this tool: - "Show me details for campaign [ID]" - "What's the structure of my campaign?" - "How many ad sets and ads does this campaign have?" - "What targeting is set on my campaign?" - "Show me the full campaign hierarchy" - After `list_meta_campaigns` when user wants to drill into a specific campaign Parameters: - campaign_id: The Meta Campaign ID (required) - include_hierarchy: Include ad sets and ads (default: false, set true for full view) Execution time: 3-10 seconds (longer with hierarchy due to multiple API calls) Data source: Meta Marketing API (live) Workflow: 1. Use `list_meta_campaigns` to find campaign IDs 2. Use `get_meta_campaign_details` with `include_hierarchy=true` to see everything 3. Use `update_meta_ad_set` or `update_meta_ad` to make changes to specific items # Get Meta Campaign Performance Source: https://www.adspirer.com/docs/api-reference/meta-ads/get-meta-campaign-performance /api-reference/openapi.json post /api/v1/tools/get_meta_campaign_performance/execute User asks about Meta/Facebook/Instagram ad performance, campaign metrics, ROAS, spend analysis, or wants to understand how their Meta ads are performing. This tool retrieves comprehensive campaign performance metrics from Meta Ads. Returns: - Account summary (total spend, impressions, reach, conversions, ROAS) - Campaign breakdown with status and objectives - Top performing campaigns by ROAS - Meta-specific metrics (reach, frequency, reach/impressions ratio) - Optimization recommendations When to use this tool: - "How are my Meta ads performing?" - "What's my Facebook campaign ROAS?" - "Show me Instagram ad performance" - "Which Meta campaigns are doing best?" - "Analyze my Meta ad spend" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - include_recommendations: true (default) or false - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 1-3 seconds (cached database query) Data source: campaign_daily_metrics table (updated nightly) Note: Unlike Google Ads, Meta does not have keyword or search term data. Meta uses interest-based targeting. # Get Meta Lead Form Submissions Source: https://www.adspirer.com/docs/api-reference/meta-ads/get-meta-lead-form-submissions /api-reference/openapi.json post /api/v1/tools/get_meta_lead_form_submissions/execute User wants to see lead submissions, lead data, or leads collected from a Meta lead form. Retrieves individual lead submissions for a specific lead form, including contact details and associated ad/campaign information. When to use this tool: - "Show me the leads from form X" - "Get my lead form submissions" - "Download my Meta leads" - "Show lead data from my campaign" - "How many leads did I get?" Returns per lead: - Submission timestamp - Field data (name, email, phone, etc. — varies by form) - Source: organic or paid (with campaign name and ad name) - Lead ID Parameters: - form_id: Lead form ID (required — get from list_meta_lead_forms) - ad_account_id: Required for multi-account users. Get from list_connected_accounts - limit: Maximum leads to return (default: 100) Permission: Requires 'leads_retrieval' scope. If the user gets a permission error, they need to disconnect and reconnect their Meta account to grant the updated permissions. Execution time: 2-5 seconds Data source: Meta Marketing API (live) # List Meta Ad Sets Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-ad-sets /api-reference/openapi.json post /api/v1/tools/list_meta_ad_sets/execute User wants to see the ad sets within a specific Meta campaign, including their targeting, budgets, and optimization settings. This tool retrieves ad sets for a given campaign with their status, budget, optimization goal, and billing event. Returns: - Ad set list with name, ID, status, budget, optimization goal, billing event - Next step guidance for editing ad sets or viewing ads When to use this tool: - "Show me the ad sets in campaign [ID]" - "What ad sets are running in my campaign?" - "List the ad groups for this campaign" - "Which ad sets are active/paused?" - Before using `update_meta_ad_set` when user doesn't know the ad set ID Parameters: - campaign_id: Campaign ID to list ad sets for (required) - status: Filter by status (optional) - limit: Max ad sets to return (default: 100) - ad_account_id: Optional Execution time: 2-5 seconds Data source: Meta Marketing API (live) Workflow: 1. Use `list_meta_campaigns` to find campaign IDs 2. Use `list_meta_ad_sets` with campaign_id to see ad sets 3. Use `update_meta_ad_set` to edit targeting, budget, or placements 4. Use `list_meta_ads` with ad_set_id to see individual ads # List Meta Ads Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-ads /api-reference/openapi.json post /api/v1/tools/list_meta_ads/execute User wants to see the individual ads within a specific Meta ad set, including their status and creative information. This tool retrieves ads for a given ad set with their name, status, and creative ID. Returns: - Ad list with name, ID, status, creative ID - Next step guidance for editing ads When to use this tool: - "Show me the ads in ad set [ID]" - "What ads are running in this ad set?" - "List the individual ads" - "Which ads are active/paused?" - Before using `update_meta_ad` when user doesn't know the ad ID Parameters: - ad_set_id: Ad Set ID to list ads for (required for direct listing) - campaign_id: Campaign ID (will guide user to use ad_set_id) - status: Filter by status (optional) - limit: Max ads to return (default: 100) Execution time: 2-5 seconds Data source: Meta Marketing API (live) Workflow: 1. Use `list_meta_ad_sets` to find ad set IDs 2. Use `list_meta_ads` with ad_set_id to see ads 3. Use `update_meta_ad` to pause/resume or swap creative Alternative: Use `get_meta_campaign_details` with `include_hierarchy=true` to see the full campaign tree at once. # List Meta Campaigns Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-campaigns /api-reference/openapi.json post /api/v1/tools/list_meta_campaigns/execute User wants to see their existing Meta/Facebook/Instagram campaigns, browse campaign structure, or find a campaign ID. This tool retrieves all campaigns in the connected Meta ad account with their status, objective, budget, and creation date. Returns: - Campaign list with name, ID, status, objective, budget - Status summary (how many ACTIVE, PAUSED, etc.) - Next step guidance for drilling into campaign details When to use this tool: - "Show me my Meta campaigns" - "List my Facebook ad campaigns" - "What campaigns do I have running?" - "Which campaigns are active?" - "Find my campaign for [product/brand]" - "I need to find a campaign ID" - Before using update/pause/resume tools when user doesn't know the campaign ID Parameters: - status: Filter by status (comma-separated: 'ACTIVE', 'PAUSED', 'DELETED', 'ARCHIVED') - effective_status: Filter by effective status (includes inherited states like 'CAMPAIGN_PAUSED') - objective: Filter by objective (OUTCOME_TRAFFIC, OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS) - limit: Max campaigns to return (default: 100) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds Data source: Meta Marketing API (live) Workflow: 1. Use `list_meta_campaigns` to find campaigns 2. Use `get_meta_campaign_details` with a campaign ID to see full structure 3. Use `update_meta_campaign` or `update_meta_ad_set` to make changes # List Meta Custom Audiences Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-custom-audiences /api-reference/openapi.json post /api/v1/tools/list_meta_custom_audiences/execute User wants to browse, list, or select Custom Audiences for targeting — DB lists, lookalike audiences, remarketing segments, website visitors, engagement audiences. Returns all Custom Audiences for the ad account with ID, name, type (subtype), approximate size, and delivery status. Workflow: 1. Call this tool to discover available custom audiences 2. Use audience IDs with campaign creation tools via `custom_audiences` parameter 3. Optionally use `excluded_custom_audiences` to exclude specific audiences When to use: - Before creating campaigns that need custom audience targeting - When user asks "which audiences do I have?" or "show me my lookalike audiences" - When setting up remarketing or DB-list campaigns # List Meta Instagram Accounts Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-instagram-accounts /api-reference/openapi.json post /api/v1/tools/list_meta_instagram_accounts/execute User wants to run ads on Instagram, asks about Instagram accounts, or you need to find the instagram_account_id before campaign creation. Returns Instagram accounts that are: 1. Authorized for ads on the ad account (from Business Manager) 2. Linked to Facebook Pages (from Page settings) Workflow: 1. Call this tool to discover available Instagram accounts 2. Use the Instagram account ID with campaign creation tools via `instagram_account_id` parameter When to use: - Before any campaign creation to enable Instagram placements - When user asks "which Instagram accounts can I use?" - When an Instagram association fails and user needs to find the right account # List Meta Lead Forms Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-lead-forms /api-reference/openapi.json post /api/v1/tools/list_meta_lead_forms/execute User wants to see their Meta lead generation forms, list lead forms, or find a lead form ID. Lists all lead generation forms for a Facebook Page associated with the ad account. When to use this tool: - "Show me my Meta lead forms" - "List my Facebook lead generation forms" - "What lead forms do I have?" - "Find my lead form ID" - "Show lead forms for my page" Returns per form: - Form name, status (ACTIVE/ARCHIVED), leads count - Creation date - Form questions (field names and types) - Form ID (needed for get_meta_lead_form_submissions and campaign creation with lead_form_id) Parameters: - page_id: Facebook Page ID (optional — auto-resolved from ad account if not provided) - ad_account_id: Required for multi-account users. Get from list_connected_accounts - limit: Maximum forms to return (default: 50) Note: Lead forms belong to Facebook Pages, not ad accounts. If you don't have the page_id, just omit it and the tool will auto-resolve from the ad account's promotable pages. Permission: Requires 'leads_retrieval' scope. If the user gets a permission error, they need to disconnect and reconnect their Meta account to grant the updated permissions. Execution time: 2-5 seconds Data source: Meta Marketing API (live) # List Meta Pixels Source: https://www.adspirer.com/docs/api-reference/meta-ads/list-meta-pixels /api-reference/openapi.json post /api/v1/tools/list_meta_pixels/execute User wants conversion tracking, asks about Meta Pixels, or before creating OUTCOME_SALES campaigns. Returns all Meta Pixels for the ad account with their status and last fired time. Workflow: 1. Call this tool to discover available pixels 2. Use the pixel ID with campaign creation tools via `pixel_id` parameter 3. Optionally specify `pixel_event_name` (default: PURCHASE) When to use: - Before creating OUTCOME_SALES campaigns (pixel_id is required for conversion tracking) - When user asks "which pixels do I have?" - When setting up conversion tracking for campaigns # Optimize Meta Budget Source: https://www.adspirer.com/docs/api-reference/meta-ads/optimize-meta-budget /api-reference/openapi.json post /api/v1/tools/optimize_meta_budget/execute User asks about Meta/Facebook/Instagram budget optimization, reallocating ad spend, maximizing conversions with their budget, or wants data-driven budget recommendations. This tool uses linear programming (scipy.optimize) to find the optimal budget allocation across Meta Ads campaigns or ad sets to maximize conversions while respecting constraints. Returns: - Optimal budget allocation for each campaign/ad set - Expected conversion lift from reallocation - Campaigns to scale up (high ROAS performers) - Campaigns to reduce (below target ROAS) - Campaigns to consider pausing (ROAS `<` 1.0) - Actionable recommendations - CBO (Campaign Budget Optimization) notes When to use this tool: - "How should I allocate my Meta budget?" - "Optimize my Facebook ad spend for conversions" - "Which Instagram campaigns should I increase budget?" - "Reallocate my $5000 Meta budget" - "Maximize conversions with my current spend" - "What's the optimal budget split across campaigns?" Parameters: - total_budget: Total daily budget to allocate (required, e.g., 5000.00) - lookback_days: 7, 14, 30 (default), 60, or 90 days for analysis - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - target_roas: Optional override (default: from account goals or 2.0x) - max_change_percentage: Max budget change per item (default: 0.5 = 50%) - min_daily_budget: Minimum budget per item (default: 5.00) - optimization_level: 'campaign' (default) or 'ad_set' - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query + optimization) Data source: campaign_daily_metrics + ad_group_daily_metrics tables Key concepts: - Linear Programming: Mathematical optimization to maximize objective (conversions) subject to constraints - Efficiency Score: Conversions per dollar spent - used to prioritize allocation - Max Change Constraint: Prevents dramatic shifts (e.g., ±50% max from current) - Target ROAS: 3-tier resolution: account_goals - 90-day historical - default 2.0x Meta-specific considerations: - CBO campaigns: Budget set at campaign level, Meta distributes to ad sets - ABO campaigns: Budget set at ad set level, more granular control - Learning Phase: New campaigns need 50+ conversions before optimization # Optimize Meta Placements Source: https://www.adspirer.com/docs/api-reference/meta-ads/optimize-meta-placements /api-reference/openapi.json post /api/v1/tools/optimize_meta_placements/execute User asks about Meta/Facebook/Instagram placement performance, which placements work best, Feed vs Stories vs Reels, should they use Audience Network, or wants placement optimization recommendations. This tool analyzes placement-level performance (Feed, Stories, Reels, Audience Network, Messenger, etc.) and provides optimization recommendations including budget reallocation suggestions. Returns: - Placement ROAS ranking (sorted by performance) - Placements categorized as SCALE/MAINTAIN/REDUCE/EXCLUDE - Budget reallocation recommendations between placements - Expected ROAS improvement from optimization - Optimal placement mix for campaign objective - Savings from excluding underperforming placements - Actionable recommendations and quick actions When to use this tool: - "Which Meta placements should I use?" - "Should I exclude Audience Network?" - "Instagram Stories vs Reels - which is better?" - "Feed vs Stories performance comparison" - "Where should I allocate my Meta ad budget?" - "Which placements are wasting money?" - "What's the optimal placement mix for conversions?" - "Facebook Marketplace performance?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - objective: 'conversions' (default), 'traffic', or 'awareness' - for optimal mix recommendations - target_roas: Optional override (default: from account goals or 2.0x) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: meta_placement_daily_metrics table (placement-level daily metrics) ROAS Thresholds for Recommendations: - ✅ SCALE (ROAS ≥3.0x): Increase budget by 20-30% - ➖ MAINTAIN (ROAS 1.5-3.0x): Keep current budget - ⚠️ REDUCE (ROAS 1.0-1.5x): Reduce budget by 30-50% - 🔴 EXCLUDE (ROAS `<`1.0x): Remove from campaigns Meta Placements Analyzed: - Facebook: Feed, Stories, Reels, Marketplace, Search Results - Instagram: Feed, Stories, Reels, Explore - Messenger: Inbox, Stories - Audience Network: All placements Common Insights: - Audience Network often has lowest ROAS for conversion campaigns - consider excluding - Instagram Feed and Reels typically have highest conversion rates - Stories are great for awareness but may have lower conversion rates - Facebook Marketplace can be effective for e-commerce # Pause Meta Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/pause-meta-campaign /api-reference/openapi.json post /api/v1/tools/pause_meta_campaign/execute User wants to pause a running Meta campaign. IMPORTANT: Pausing a campaign stops all ad delivery immediately. No more budget will be spent until resumed. Returns: - Confirmation that campaign is paused - Campaign details - Ads Manager URL When to use this tool: - "Pause my Meta campaign" - "Stop my Facebook ads" - "Pause campaign 123456" - "Turn off my Instagram campaign" Parameters: - campaign_id: The Meta Campaign ID to pause (required) Execution time: 2-5 seconds Effect: Campaign status changes to PAUSED immediately # Resume Meta Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/resume-meta-campaign /api-reference/openapi.json post /api/v1/tools/resume_meta_campaign/execute User wants to resume a paused Meta campaign. IMPORTANT: Resuming a campaign restarts ad delivery. Budget will start being spent again. Returns: - Confirmation that campaign is active - Campaign details - Ads Manager URL When to use this tool: - "Resume my Meta campaign" - "Turn on my Facebook ads" - "Reactivate campaign 123456" - "Start my paused Instagram campaign" Parameters: - campaign_id: The Meta Campaign ID to resume (required) Execution time: 2-5 seconds Effect: Campaign status changes to ACTIVE immediately # Search Meta Targeting Source: https://www.adspirer.com/docs/api-reference/meta-ads/search-meta-targeting /api-reference/openapi.json post /api/v1/tools/search_meta_targeting/execute User wants to find targeting options for their Meta (Facebook/Instagram) ad campaigns. This tool searches the Meta Marketing API to find targeting options including interests, behaviors, demographics, locations, and more. Returns: - List of targeting options with IDs, names, and audience sizes - Category/path information for interests and behaviors - Location details including country, region for geo-targeting When to use this tool: - "Find interests related to fitness" - "What targeting options are available for travel?" - "Search for locations in California" - "Find behaviors for online shoppers" - "What demographics can I target?" - "Find job titles for marketing professionals" - "Search for schools like Harvard" Search Types Available: - interest: Topics and activities (e.g., 'fitness', 'cooking', 'travel') - behavior: User behaviors (e.g., 'frequent travelers', 'online shoppers') - demographic: Demographics (e.g., 'new parents', 'college educated') - life_event: Life events (e.g., 'recently moved', 'newly engaged') - location: Geo-targeting (e.g., 'New York', 'California', '90210') - locale: Language targeting (e.g., 'Spanish', 'French') - employer: Employer targeting (e.g., 'Google', 'Microsoft') - job_title: Job title targeting (e.g., 'Software Engineer') - school: Education school targeting (e.g., 'Harvard', 'Stanford') - major: Education major targeting (e.g., 'Computer Science') Parameters: - search_type: Type of targeting to search (required) - query: Search query string (required) - limit: Maximum results (1-100, default: 50) - locale: Locale for results (default: en_US) - location_types: For location search - filter by types (country, region, city, zip) - country_code: For location search - filter by country (e.g., 'US') - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 1-3 seconds Data source: Meta Marketing API Targeting Search # Select Meta Campaign Type Source: https://www.adspirer.com/docs/api-reference/meta-ads/select-meta-campaign-type /api-reference/openapi.json post /api/v1/tools/select_meta_campaign_type/execute User wants to create a Meta (Facebook/Instagram) ad campaign but hasn't specified the campaign type (image, video, or carousel). IMPORTANT: This tool should be called BEFORE any asset discovery or campaign creation when the user says things like: - "Create a Meta campaign" - "Create a Facebook ad" - "I want to run Instagram ads" - "Set up a Meta advertising campaign" - "Help me create ads on Facebook" This tool asks the user what TYPE of campaign they want to create, then provides guidance on the next steps. Campaign Types Available: 1. image - Single image ad (most common, good for static visuals) 2. video - Video ad including Reels (good for engagement, storytelling) 3. carousel - 2-10 swipeable cards (good for showcasing multiple products) Do NOT use this tool if: - User specifically asks for "image campaign" - use create_meta_image_campaign - User specifically asks for "video campaign" or "Reels" - use create_meta_video_campaign - User specifically asks for "carousel campaign" - use create_meta_carousel_campaign - User is asking about performance/analytics - use performance analysis tools Parameters: - campaign_type: 'image', 'video', or 'carousel' # Update Meta Ad Source: https://www.adspirer.com/docs/api-reference/meta-ads/update-meta-ad /api-reference/openapi.json post /api/v1/tools/update_meta_ad/execute User wants to update an individual Meta ad — pause/resume it, rename it, or swap its creative. IMPORTANT: This tool modifies REAL ads in Meta Ads Manager. Changes take effect immediately. Returns: - Confirmation of updates applied - Summary of changes - Ads Manager URL for the ad When to use this tool: - "Pause this ad" - "Resume ad [ID]" - "Rename this ad" - "Swap the creative on this ad" - "Change the image on this ad" (via creative swap) - "Turn off the underperforming ad" Parameters: - ad_id: The Meta Ad ID to update (required) - status: ACTIVE, PAUSED, DELETED, ARCHIVED (optional) - name: New ad name (optional) - creative_id: New creative ID for creative swap (optional) At least one update field must be provided. Execution time: 2-5 seconds Modifies: Real ad in Meta Ads Workflow for creative swap: 1. Use `discover_meta_assets` to find existing images/creatives 2. Get the creative ID you want to use 3. Use `update_meta_ad` with `creative_id` to swap Workflow for pausing underperformers: 1. Use `analyze_meta_ad_performance` to identify underperforming ads 2. Use `list_meta_ads` to get ad IDs 3. Use `update_meta_ad` with `status=PAUSED` # Update Meta Ad Set Source: https://www.adspirer.com/docs/api-reference/meta-ads/update-meta-ad-set /api-reference/openapi.json post /api/v1/tools/update_meta_ad_set/execute User wants to edit an existing Meta ad set's targeting, budget, bid, placements, schedule, or optimization settings. IMPORTANT: This tool modifies REAL ad sets in Meta Ads Manager. Changes take effect immediately. This is the primary tool for: - Changing audience targeting (age, gender, interests, locations) - Excluding placements (e.g., remove Audience Network) - Adjusting budgets at the ad set level - Changing bid amounts - Pausing/resuming specific ad sets - Modifying optimization goals Returns: - Confirmation of updates applied - Summary of all changes made - Ads Manager URL for the ad set When to use this tool: - "Change the targeting on my ad set" - "Exclude Audience Network from placements" - "Update the budget on this ad set to $50/day" - "Pause this ad set" - "Change the age range to 25-45" - "Add interest targeting for fitness" - "Exclude custom audience from this ad set" - "Change bid to $5" - "Update the optimization goal" Parameters: - ad_set_id: The Meta Ad Set ID to update (required) - status: ACTIVE, PAUSED, DELETED, ARCHIVED (optional) - name: New ad set name (optional) - daily_budget: New daily budget in USD (optional, min $1). DO NOT use for CBO campaigns. - lifetime_budget: New lifetime budget in USD (optional). DO NOT use for CBO campaigns. - daily_min_spend_target: CBO only — minimum daily spend for this ad set (use INSTEAD of daily_budget) - daily_spend_cap: CBO only — maximum daily spend cap for this ad set (use INSTEAD of daily_budget) - lifetime_min_spend_target: CBO only — minimum lifetime spend (for lifetime budget CBO) - lifetime_spend_cap: CBO only — maximum lifetime spend cap (for lifetime budget CBO) - bid_amount: New bid amount in USD (optional) - targeting: New targeting spec as JSON (optional) — for placements, audiences, demographics - start_time: New start time ISO format (optional) - end_time: New end time ISO format (optional) - optimization_goal: REACH, LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, VALUE, etc. (optional) **CBO (Advantage Campaign Budget) campaigns:** For ad sets under CBO campaigns, do NOT set daily_budget or lifetime_budget. Use daily_min_spend_target / daily_spend_cap to control spend distribution. Setting daily_budget on a CBO ad set will cause Meta to reject with an error. At least one update field must be provided. Targeting Spec Examples: *Exclude Audience Network:* ```json { "publisher_platforms": ["facebook", "instagram"], "facebook_positions": ["feed", "stories", "reels"], "instagram_positions": ["stream", "story", "reels"] } ``` *Change age and gender:* ```json { "age_min": 25, "age_max": 45, "genders": [1] } ``` (genders: 1=male, 2=female, omit for all) *Add interest targeting:* ```json { "flexible_spec": [{"interests": [{"id": "6003139266461", "name": "Fitness"}]}] } ``` *Exclude custom audience:* ```json { "excluded_custom_audiences": [{"id": "AUDIENCE_ID"}] } ``` Execution time: 2-5 seconds Modifies: Real ad set in Meta Ads Workflow: 1. Use `list_meta_ad_sets` or `get_meta_campaign_details` to find the ad set ID 2. Use `update_meta_ad_set` with the changes you want to make 3. Verify changes in Ads Manager # Update Meta Campaign Source: https://www.adspirer.com/docs/api-reference/meta-ads/update-meta-campaign /api-reference/openapi.json post /api/v1/tools/update_meta_campaign/execute User wants to update an existing Meta campaign's status, budget, name, or schedule. IMPORTANT: This tool modifies REAL campaigns in Meta Ads Manager. Changes take effect immediately. Returns: - Confirmation of updates applied - Updated campaign details - Ads Manager URL When to use this tool: - "Update my Meta campaign budget" - "Change my Facebook campaign name" - "Pause my Instagram campaign" - "Resume my paused campaign" - "Set a new budget for campaign X" - "Change the end date for my campaign" Parameters: - campaign_id: The Meta Campaign ID to update (required) - status: New status - 'ACTIVE', 'PAUSED' (optional) - name: New campaign name (optional) - daily_budget: New daily budget in USD (optional) - lifetime_budget: New lifetime budget in USD (optional) - start_time: New start time in ISO format (optional) - stop_time: New stop time in ISO format (optional) At least one update field must be provided. Execution time: 2-5 seconds Modifies: Real campaign in Meta Ads # Validate And Prepare Meta Assets Source: https://www.adspirer.com/docs/api-reference/meta-ads/validate-and-prepare-meta-assets /api-reference/openapi.json post /api/v1/tools/validate_and_prepare_meta_assets/execute User wants to upload NEW images for Meta campaigns. This tool validates images and uploads them to Meta to get image hashes. This tool validates image URLs against Meta's specifications and uploads them to get image hashes needed for campaign creation. It stores validated assets in a temporary bundle (60-minute TTL). Returns: - Validation results (pass/fail per image) - Image hashes for successfully uploaded images - Asset bundle ID for use in campaign creation - Placement compatibility information When to use this tool: - "Upload this image for my Meta campaign" - "Validate my product images for Facebook ads" - "Prepare images for Instagram ads" - User provides image URLs and wants to create a campaign Parameters: - image_urls: List of public URLs to validate and upload (1-10 images) - placement: Target placement - 'feed' (default), 'stories_reels', or 'carousel' - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 5-15 seconds (depends on image count and size) Data source: Meta Ad Image Upload API Image Requirements: | Placement | Aspect Ratio | Min Dimensions | Max Size | |-----------|-------------|----------------|----------| | Feed | 1:1 or 4:5 | 600x600 | 30MB | | Stories/Reels | 9:16 | 500x888 | 30MB | | Carousel | 1:1 | 1080x1080 | 30MB | Workflow: 1. Use `validate_and_prepare_meta_assets` with image URLs 2. If successful, receive an `asset_bundle_id` 3. Use that bundle_id with `create_meta_image_campaign` # Create Monitor Source: https://www.adspirer.com/docs/api-reference/monitoring/create-monitor /api-reference/openapi.json post /api/v1/tools/create_monitor/execute Create a monitoring alert for your campaigns. Checked daily. **Supported metrics:** roas, ctr, cpc, cpa, cpm, cpv, spend, conversions, impressions, clicks, cost_per_lead, conversion_rate, budget_utilization, video_views, engagement_rate **Operators:** less_than, greater_than, less_than_or_equal, greater_than_or_equal, changes_by **Advanced features:** - **Multiple conditions with AND/OR:** Use `conditions` array with `conditions_logic: "AND"` or `"OR"` - **Consecutive days:** Add `consecutive_days: 3` to only trigger after 3 days in a row - **Relative thresholds:** Set `threshold_type: "relative"` with `threshold_multiplier: 1.5` to mean "50% above average" - **% change detection:** Use `operator: "changes_by"` with `direction: "decrease"` and `threshold: 30` for "dropped 30%" - **Campaign targeting:** Use `campaign_ids` to monitor specific campaigns only - **Auto-actions (coming soon):** `auto_action: "pause_campaign"` or `"increase_budget"` with `auto_action_value: 20` **Examples:** 1. Simple: "Alert me if ROAS drops below 2" → metric: "roas", operator: "less_than", threshold: 2.0 2. Consecutive days: "Alert if CPA exceeds $50 for 3 days straight" → metric: "cpa", operator: "greater_than", threshold: 50, consecutive_days: 3 3. Compound AND: "Alert if CTR `<` 0.8% AND spend > $200" → conditions: [ `{metric: "ctr", operator: "less_than", threshold: 0.8}`, `{metric: "spend", operator: "greater_than", threshold: 200}` ], conditions_logic: "AND" 4. Relative: "Alert if CPA goes 50% above my 30-day average" → metric: "cpa", operator: "greater_than", threshold_type: "relative", threshold_multiplier: 1.5, threshold_timeframe: "last_30d" 5. % drop: "Notify me if cost per lead drops 30% in a day" → metric: "cost_per_lead", operator: "changes_by", threshold: 30, direction: "decrease", timeframe: "vs_previous_day" **IMPORTANT:** - If user doesn't specify an email for alerts, ASK them. Do not guess. - If user doesn't specify platforms, default to all their connected platforms. - If user doesn't specify campaigns, default to all campaigns. - Do not assume timeframe — ask if unclear. - Do not assume threshold values — ask if the user doesn't specify a number. - ROAS monitors are skipped on traffic/awareness/engagement campaigns automatically. - CPA monitors are skipped on campaigns with zero conversions automatically. # Delete Monitor Source: https://www.adspirer.com/docs/api-reference/monitoring/delete-monitor /api-reference/openapi.json post /api/v1/tools/delete_monitor/execute Delete a monitoring alert by its task ID. **When to use:** - "Delete my ROAS monitor" - "Remove this alert" - "Stop monitoring my campaign" Get the task_id from `list_monitors` first. Accepts `task_id`, `alert_id`, or `monitor_id` — all treated the same. # Generate Report Now Source: https://www.adspirer.com/docs/api-reference/monitoring/generate-report-now /api-reference/openapi.json post /api/v1/tools/generate_report_now/execute Generate an immediate performance report and deliver it now. **What it does:** - Generates a comprehensive PDF performance report immediately - Fetches latest campaign data from all connected platforms - Includes AI-powered recommendations and insights - Delivers via email, Slack, or webhook **When to use:** - "Get me my campaign performance report" - "Send me a detailed analysis of all my accounts" - "Generate a report and email it to me" - "I need my performance data now" - "Prepare a report for all my campaigns" **Report Types:** - performance_brief: Quick overview of key metrics - detailed_analysis: Deep dive with breakdowns - executive_summary: High-level summary for stakeholders **Execution time:** 2-5 minutes (async - you'll be notified when ready) **Example:** User: "Get me my detailed campaign performance for all accounts and email it to me" → Call generate_report_now with: - report_type: "detailed_analysis" - platforms: null (all platforms) - delivery_method: "email" - delivery_destination: "user@example.com" # Get Monitor History Source: https://www.adspirer.com/docs/api-reference/monitoring/get-monitor-history /api-reference/openapi.json post /api/v1/tools/get_monitor_history/execute Show trigger history for a monitoring alert. **What it does:** - Shows when the monitor triggered, what condition was met, and what value caused it - Shows which campaigns triggered and whether notifications were sent - Useful for understanding monitor behavior and verifying it works correctly **When to use:** - "Show history for my CPA monitor" - "When did this alert last trigger?" - "What campaigns triggered my ROAS alert?" Requires the monitor's alert_id (get from list_monitors). # Get Research Status Source: https://www.adspirer.com/docs/api-reference/monitoring/get-research-status /api-reference/openapi.json post /api/v1/tools/get_research_status/execute Check the status of a research job. **What it does:** - Shows current progress percentage - Indicates if job is pending, in progress, completed, or failed - Provides summary when complete **When to use:** - "Check on my research" - "Is my analysis done?" - "What's the status of job [ID]?" # List Monitors Source: https://www.adspirer.com/docs/api-reference/monitoring/list-monitors /api-reference/openapi.json post /api/v1/tools/list_monitors/execute List all your monitoring alerts. **What it does:** - Shows all active and paused monitors - Displays conditions, trigger counts, and status - Provides alert IDs for management **When to use:** - "Show my monitoring alerts" - "What am I monitoring?" - "List all my alerts" # List Pending Actions Source: https://www.adspirer.com/docs/api-reference/monitoring/list-pending-actions /api-reference/openapi.json post /api/v1/tools/list_pending_actions/execute List auto-actions waiting for your approval. **What it does:** - Shows pending campaign actions (pause, budget changes) queued by your monitors - Displays before/after state for each action - Shows expiry time (actions expire after 48 hours) **When to use:** - "Show my pending actions" - "What actions need approval?" - "Any pending budget changes?" After reviewing, use `manage_action` to approve or reject each action. # List Scheduled Tasks Source: https://www.adspirer.com/docs/api-reference/monitoring/list-scheduled-tasks /api-reference/openapi.json post /api/v1/tools/list_scheduled_tasks/execute List all your scheduled automation tasks. **What it does:** - Shows all scheduled briefs, monitors, and research jobs - Displays status, schedule, and last execution - Provides task IDs for management **When to use:** - "Show my scheduled tasks" - "What automations do I have running?" - "List my scheduled reports" # Manage Action Source: https://www.adspirer.com/docs/api-reference/monitoring/manage-action /api-reference/openapi.json post /api/v1/tools/manage_action/execute Approve or reject a pending auto-action. **What it does:** - Approves a pending action → executes it immediately on the ad platform - Rejects a pending action → cancels it, no changes made **When to use:** - "Approve action [action_id]" - "Reject action [action_id]" - "Approve all pending actions" (call multiple times) **IMPORTANT:** - Approved actions are EXECUTED IMMEDIATELY (campaign paused, budget changed) - This is irreversible in the moment — verify before approving - Actions expire after 48 hours if not approved # Manage Scheduled Task Source: https://www.adspirer.com/docs/api-reference/monitoring/manage-scheduled-task /api-reference/openapi.json post /api/v1/tools/manage_scheduled_task/execute Manage a scheduled task — pause, resume, or delete. Works for briefs, monitors, and all task types. **What it does:** - Pause: Temporarily stop a scheduled task or monitoring alert - Resume: Restart a paused task or monitor - Delete: Permanently remove a task or monitor **When to use:** - "Pause my daily brief" - "Resume my performance reports" - "Delete the weekly summary task" - "Pause this monitoring alert" **Required parameters:** - `task_id`: The ID of the task (get from `list_scheduled_tasks` or `list_monitors`) - `action`: 'pause', 'resume', or 'delete' To delete a monitoring alert specifically, you can also use `delete_monitor`. # Schedule Brief Source: https://www.adspirer.com/docs/api-reference/monitoring/schedule-brief /api-reference/openapi.json post /api/v1/tools/schedule_brief/execute Schedule recurring performance briefs delivered to your inbox. **What it does:** - Creates automated daily or weekly performance reports - Summarizes key metrics across all your ad platforms - Highlights top performers and underperformers - Provides AI-generated recommendations **When to use:** - "Set up a daily performance report" - "Send me weekly campaign summaries" - "I want automated performance updates" - "Create a scheduled brief for my campaigns" **Execution time:** 2-3 seconds to schedule **Example:** User: "Send me daily performance updates at 9 AM" → Call schedule_brief with: - name: "Daily Performance Update" - schedule_type: "daily" - time: "09:00" - delivery_method: "email" - delivery_destination: "user@example.com" # Start Research Source: https://www.adspirer.com/docs/api-reference/monitoring/start-research /api-reference/openapi.json post /api/v1/tools/start_research/execute Start an AI-powered research job (runs in background). **What it does:** - Performs deep analysis that takes 5 minutes to 2 hours - Runs asynchronously - you'll be notified when complete - Provides comprehensive insights and recommendations **Research Types:** 1. **competitor_analysis** - Analyze competitor ad strategies Required context: competitors (list of competitor domains/names) 2. **keyword_research** - Discover high-value keywords Required context: seed_keywords (list of starting keywords) 3. **market_landscape** - Industry overview and trends Required context: industry (industry name) 4. **audience_insights** - Target audience analysis Required context: target_audience (description of audience) 5. **campaign_strategy** - Strategic recommendations Required context: campaign_goals (what you want to achieve) **Depth Levels:** - quick: 5-10 minutes - standard: 15-30 minutes - comprehensive: 1-2 hours **Example:** User: "Research my competitors" → Call start_research with: - research_type: "competitor_analysis" - depth: "standard" - context: `{"competitors": ["competitor1.com", "competitor2.com"]}` # Test Monitor Source: https://www.adspirer.com/docs/api-reference/monitoring/test-monitor /api-reference/openapi.json post /api/v1/tools/test_monitor/execute Dry-run a monitor against current data WITHOUT triggering alerts or sending notifications. **What it does:** - Evaluates the monitor's conditions against current campaign data - Shows which campaigns would match and which would be skipped - Does NOT create triggers, send emails, or queue auto-actions - Useful for verifying a monitor is configured correctly before enabling **When to use:** - "Test my CPA monitor" - "Would this alert trigger right now?" - "Check if my monitor is set up correctly" - "Dry run the budget overspend alert" Requires the monitor's alert_id (get from list_monitors). # Add TikTok Ad Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/add-tiktok-ad /api-reference/openapi.json post /api/v1/tools/add_tiktok_ad/execute Add a new ad to an existing TikTok ad group. Use this when you need to add additional ads (creatives) to an ad group that was already created. Supports all ad formats: - SINGLE_IMAGE: Provide image_urls (public HTTPS URLs — auto-uploaded) OR image_ids (pre-uploaded TikTok IDs) - SINGLE_VIDEO: Provide video_id (TikTok video ID from creative library) - Spark Ads: Boost organic TikTok posts (requires tiktok_item_id + identity_type=TT_USER) - Carousel: Multi-card ads (first call create_tiktok_carousel_card to get card_id, then provide card_id + card_type here) Identity (identity_id) is auto-resolved — you do NOT need to provide it unless using Spark Ads. Images are auto-uploaded from URLs — you do NOT need to call upload_tiktok_images first. This is useful for: - Testing different creatives in the same ad group - Adding new ad variations without creating a new campaign - A/B testing ad copy, images, or CTAs Required: adgroup_id, ad_text, landing_page_url. For image ads: provide image_urls (easiest) or image_ids. For video ads: provide video_id. For Spark Ads: provide tiktok_item_id and set identity_type to TT_USER. # Add TikTok Ad Group Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/add-tiktok-ad-group /api-reference/openapi.json post /api/v1/tools/add_tiktok_ad_group/execute Add a new ad group to an existing TikTok campaign. Use this when you need to add additional ad groups to a campaign that was already created. Each ad group can have different targeting, budget, and placement settings. This is useful for: - A/B testing different audiences under the same campaign - Splitting budget across different targeting strategies - Adding new targeting segments to an existing campaign Required: campaign_id, adgroup_name, budget. The objective parameter determines automatic billing/optimization defaults (TRAFFIC→CPC, CONVERSIONS→OCPM, etc.). After creating the ad group, use `add_tiktok_ad` to add ads to it. # Analyze TikTok Geo Performance Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/analyze-tiktok-geo-performance /api-reference/openapi.json post /api/v1/tools/analyze_tiktok_geo_performance/execute Analyze TikTok geographic/country-level performance. Returns: per-country spend, conversions, CPA, CTR, hook rate, engagement. Best/worst countries with recommendations. Note: TikTok uses country-level breakdowns (not placement-level like Meta's Feed/Stories/Reels). When to use: "TikTok performance by country", "Which countries perform best on TikTok?", "TikTok geo breakdown" Parameters: - lookback_days: default 30 # Analyze TikTok Wasted Spend Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/analyze-tiktok-wasted-spend /api-reference/openapi.json post /api/v1/tools/analyze_tiktok_wasted_spend/execute Analyze TikTok campaigns for wasted ad spend. Identifies campaigns losing money (ROAS `<` 1.0) and underperforming campaigns (ROAS `<` target). Returns: wasted spend by campaign, severity levels (CRITICAL/HIGH/MEDIUM), creative fatigue analysis, status-aware recommendations (distinguishes active vs disabled campaigns). When to use: "Where am I wasting money on TikTok?", "TikTok wasted spend", "Which TikTok campaigns are losing money?" ⚠️ NEVER say "pause" for campaigns with conversions. Say "review" or "reduce budget". ⚠️ Campaigns in LEARNING phase (`<` 14 days) should not be paused. # Create TikTok Campaign Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/create-tiktok-campaign /api-reference/openapi.json post /api/v1/tools/create_tiktok_campaign/execute User wants to create a TikTok ad campaign with IMAGES, Spark Ads, or Carousel ads (not video). LONG-RUNNING TOOL: Creates a TikTok In-Feed ad campaign with image creatives, Spark Ads (boost organic posts), or Carousel ads. Supported creative types: - Standard Image Ads: Provide asset_bundle_id or existing_image_ids - Spark Ads: Provide tiktok_item_id to boost an existing organic TikTok post as a paid ad - Carousel Ads: First call create_tiktok_carousel_card to get a card_id, then provide card_id + card_type here - App Promotion: Set objective=APP_PROMOTION + app_id for app install campaigns Emits MCP progress updates during campaign creation (typically 15-30 seconds). Progress stages: validate - commit. CRITICAL WARNING: - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying # Create TikTok Carousel Card Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/create-tiktok-carousel-card /api-reference/openapi.json post /api/v1/tools/create_tiktok_carousel_card/execute Create a carousel card from multiple images for TikTok carousel ads. IMPORTANT: Call this tool BEFORE creating a carousel campaign or carousel ad. Carousel ads show 2-10 swipeable image cards. Each card can have its own ad text and landing page. Workflow for carousel campaigns: 1. Get TikTok image IDs: - Option A: upload_tiktok_images with public image URLs (uploads to TikTok, returns image_ids) - Option B: discover_tiktok_assets to find existing images in your library 2. Call this tool with those image_ids to create a carousel card (get card_id back) 3. Use the card_id in create_tiktok_campaign or add_tiktok_ad with card_type='IMAGE' Required: image_ids (2-10 TikTok image IDs). Optional: ad_texts (one per card), landing_page_urls (one per card), call_to_action. # Create TikTok Video Campaign Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/create-tiktok-video-campaign /api-reference/openapi.json post /api/v1/tools/create_tiktok_video_campaign/execute User wants to create a TikTok ad campaign with a VIDEO (not images). Also supports Spark Ads and Carousel with video. LONG-RUNNING TOOL: Creates a TikTok In-Feed video ad campaign. Also supports Spark Ads (boost organic posts) and Carousel ads. Additional creative types supported: - Spark Ads: Provide tiktok_item_id to boost an existing organic TikTok post as a paid ad - Carousel Ads: First call create_tiktok_carousel_card to get a card_id, then provide card_id + card_type here - App Promotion: Set objective=APP_PROMOTION + app_id for app install campaigns Emits MCP progress updates during campaign creation (typically 30-60 seconds). Progress stages: validate - upload - commit. CRITICAL WARNING: - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying # Detect TikTok Creative Fatigue Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/detect-tiktok-creative-fatigue /api-reference/openapi.json post /api/v1/tools/detect_tiktok_creative_fatigue/execute Detect TikTok creative fatigue using video-specific metrics (hook rate decline, completion rate decline, engagement decline, frequency). Returns: fatigue score (0-100) per ad, severely fatigued / at-risk / healthy counts, refresh schedule, recommendations. TikTok-specific: Hook rate (first 2 seconds) is the primary fatigue signal (35% weight). When to use: "Are my TikTok ads fatigued?", "TikTok creative refresh", "Which TikTok videos need replacing?" Parameters: - lookback_days: default 30 - frequency_threshold: override (default 3.5) # Discover TikTok Assets Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/discover-tiktok-assets /api-reference/openapi.json post /api/v1/tools/discover_tiktok_assets/execute User wants to reuse existing TikTok images instead of uploading new ones. Browse existing images in TikTok Asset Library for reuse in campaigns. IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Returns: - List of all images in your TikTok Asset Library - Image IDs, dimensions, file sizes, upload dates - Usage instructions for reusing assets Parameters: - advertiser_id: Optional (uses connected account if omitted) Execution time: 2-5 seconds (direct backend API call) Use this tool to: - Find existing images you can reuse in new campaigns - Avoid re-uploading the same images - See what assets are available in your library After calling this tool, you can use the returned image IDs in `create_tiktok_campaign` via the `existing_image_ids` parameter. # Explain TikTok Anomaly Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/explain-tiktok-anomaly /api-reference/openapi.json post /api/v1/tools/explain_tiktok_anomaly/execute Explain why a TikTok metric changed during a specific period. Uses statistical analysis and factor detection. Supported metrics: roas, ctr, cpc, cpm, conversions, conversion_rate, hook_rate, video_completion_rate, engagement_rate Returns: current value vs historical averages, deviation %, contributing factors (CPM change, CTR change, hook rate change, engagement change, campaign structure changes), assessment, recommendations. When to use: "Why did my TikTok CTR drop?", "Explain TikTok performance change", "What happened to my TikTok ROAS?" Parameters: - metric: REQUIRED — which metric to analyze - period_start/period_end: REQUIRED — YYYY-MM-DD dates for the anomaly period (max 30 days) # Get TikTok Ad Performance Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/get-tiktok-ad-performance /api-reference/openapi.json post /api/v1/tools/get_tiktok_ad_performance/execute Get TikTok ad-level performance with creative details, video metrics, and engagement. Returns: per-ad metrics (spend, CTR, ROAS, hook rate, completion rate, engagement rate), creative metadata (ad name, format, video ID), and top/underperforming ads. When to use: "Show my TikTok ad performance", "Which TikTok ads are best?", "TikTok creative performance" Parameters: - lookback_days: default 30 - limit: max ads to return (1-50, default 20) - offset: pagination offset # Get TikTok Audience Insights Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/get-tiktok-audience-insights /api-reference/openapi.json post /api/v1/tools/get_tiktok_audience_insights/execute Analyze TikTok audience segment performance by age, gender, and combined demographics. Returns: age group breakdown (AGE_18_24 to AGE_55_100), gender breakdown, best/worst segments, saturation detection, targeting recommendations. Note: TikTok audience API doesn't return conversion values per demographic — segments ranked by CPA or CTR. When to use: "TikTok audience performance", "Which age group works best on TikTok?", "TikTok demographic breakdown" Parameters: - breakdown_type: 'age', 'gender', 'age_gender', or 'all' (default) - include_saturation: true/false (default true) # Get TikTok Campaign Details Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/get-tiktok-campaign-details /api-reference/openapi.json post /api/v1/tools/get_tiktok_campaign_details/execute Get detailed information about a specific TikTok campaign including status, budget, objective, and timestamps. # Get TikTok Campaign Performance Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/get-tiktok-campaign-performance /api-reference/openapi.json post /api/v1/tools/get_tiktok_campaign_performance/execute Get TikTok campaign performance metrics including TikTok-specific video and engagement data. Returns: account summary (spend, impressions, reach, conversions, ROAS), campaign breakdown with video metrics (hook rate, completion rate), engagement metrics (likes, shares, comments), and recommendations. When to use: "How are my TikTok campaigns performing?", "Show TikTok performance", "TikTok ROAS" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 - start_date/end_date: Optional YYYY-MM-DD (overrides lookback_days) # List TikTok Ad Groups Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/list-tiktok-ad-groups /api-reference/openapi.json post /api/v1/tools/list_tiktok_ad_groups/execute List TikTok ad groups. Optionally filter by campaign ID. # List TikTok Ads Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/list-tiktok-ads /api-reference/openapi.json post /api/v1/tools/list_tiktok_ads/execute List TikTok ads. Optionally filter by ad group ID or campaign ID. # List TikTok Campaigns Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/list-tiktok-campaigns /api-reference/openapi.json post /api/v1/tools/list_tiktok_campaigns/execute List all TikTok campaigns with their status, objective, and budget. # Optimize TikTok Budget Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/optimize-tiktok-budget /api-reference/openapi.json post /api/v1/tools/optimize_tiktok_budget/execute Optimize TikTok budget allocation using linear programming to maximize conversions. Returns: current vs optimized allocation, expected conversion lift, campaigns to scale/reduce/pause/maintain. When to use: "Optimize my TikTok budget", "How should I allocate TikTok spend?", "TikTok budget recommendations" Parameters: - total_budget: REQUIRED — total monthly budget to allocate - target_roas: optional override (default uses historical avg or 2.0x) - max_change_percentage: 0.3 (conservative) to 0.7 (aggressive), default 0.5 # Pause TikTok Ad Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/pause-tiktok-ad /api-reference/openapi.json post /api/v1/tools/pause_tiktok_ad/execute Pause a TikTok ad. Sets status to DISABLE. # Pause TikTok Ad Group Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/pause-tiktok-ad-group /api-reference/openapi.json post /api/v1/tools/pause_tiktok_ad_group/execute Pause a TikTok ad group. Sets status to DISABLE. # Pause TikTok Campaign Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/pause-tiktok-campaign /api-reference/openapi.json post /api/v1/tools/pause_tiktok_campaign/execute Pause a TikTok campaign. Sets status to DISABLE. Use resume_tiktok_campaign to re-enable. # Resume TikTok Ad Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/resume-tiktok-ad /api-reference/openapi.json post /api/v1/tools/resume_tiktok_ad/execute Resume a paused TikTok ad. Sets status to ENABLE. # Resume TikTok Ad Group Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/resume-tiktok-ad-group /api-reference/openapi.json post /api/v1/tools/resume_tiktok_ad_group/execute Resume a paused TikTok ad group. Sets status to ENABLE. # Resume TikTok Campaign Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/resume-tiktok-campaign /api-reference/openapi.json post /api/v1/tools/resume_tiktok_campaign/execute Resume a paused TikTok campaign. Sets status to ENABLE. # Search TikTok Targeting Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/search-tiktok-targeting /api-reference/openapi.json post /api/v1/tools/search_tiktok_targeting/execute Search TikTok targeting options for campaign creation and ad group management. IMPORTANT: Call this tool to find valid targeting IDs BEFORE creating campaigns or ad groups. Covers ALL targeting types: - interest_categories: Browse all interest categories (fashion, gaming, food, etc.) — returns IDs for interest_category_ids - interest_keywords: Search interest keywords by a seed keyword (e.g., "fitness") — returns keyword IDs for interest_keyword_ids - regions: Get available locations (countries, provinces, cities) — returns location IDs for location_ids/target_locations - languages: Get available language codes — returns codes for languages targeting - action_categories: Get app event categories — for conversion tracking - carriers: Get mobile carrier names — for carrier targeting - device_models: Get device models — for device targeting Common usage patterns: - Before create_tiktok_campaign: search regions + interest_categories to set targeting - Before add_tiktok_ad_group: search interest_keywords for new audience segments - Before update_tiktok_ad_group: search regions to expand/narrow location targeting Parameters: - targeting_type: REQUIRED — which type to search (see above) - keyword: REQUIRED for interest_keywords — seed keyword to search - level_range: For regions — TO_COUNTRY (default), TO_PROVINCE, TO_CITY, TO_DISTRICT - language: Display language for results (default: en) # Update TikTok Ad Group Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/update-tiktok-ad-group /api-reference/openapi.json post /api/v1/tools/update_tiktok_ad_group/execute Update TikTok ad group settings: name, budget, targeting (age, gender, locations), schedule. # Update TikTok Campaign Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/update-tiktok-campaign /api-reference/openapi.json post /api/v1/tools/update_tiktok_campaign/execute Update TikTok campaign settings like name, budget, or budget mode. # Upload TikTok Images Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/upload-tiktok-images /api-reference/openapi.json post /api/v1/tools/upload_tiktok_images/execute Upload images to TikTok Asset Library from public URLs. Returns TikTok image_ids that can be used for: - create_tiktok_carousel_card — build carousel cards from uploaded images - create_tiktok_campaign with existing_image_ids — standard image campaigns - add_tiktok_ad with image_ids — add image ads to existing ad groups TikTok downloads images directly from the provided URLs (no intermediate storage needed). Supported formats: JPG, PNG, WEBP. Max 10MB per image. Max 20 images per call. Use this tool when the user provides image URLs and you need TikTok image IDs. # Validate And Prepare TikTok Assets Source: https://www.adspirer.com/docs/api-reference/tiktok-ads/validate-and-prepare-tiktok-assets /api-reference/openapi.json post /api/v1/tools/validate_and_prepare_tiktok_assets/execute User provides image URLs to validate BEFORE creating TikTok image campaign. Validate and prepare new image assets for TikTok ad campaigns. IMPORTANT: Call this tool BEFORE create_tiktok_campaign if uploading NEW images. TikTok Image Requirements: - Aspect ratio: 9:16 (vertical, e.g., 1080x1920 or 540x960) - Maximum file size: 10MB - Formats: JPEG, PNG, WEBP - Minimum size: 540x960px - Recommended: 1080x1920px Parameters: - image_urls: List of public image URLs (e.g., from postimages.org, imgbb.com) Returns: - Validation results for each image - asset_bundle_id (valid for 60 minutes) - Use this bundle ID in create_tiktok_campaign Execution time: 5-15 seconds (downloads and validates images) Use this tool to: - Upload new images you haven't used before - Validate images meet TikTok's specifications - Get detailed error messages if images don't meet requirements After validation, use the returned `asset_bundle_id` in `create_tiktok_campaign`. # Adspirer Changelog: New Tools, Platforms & Features Source: https://www.adspirer.com/docs/changelog Adspirer changelog — new MCP tools, platform integrations, AI client support, and feature releases for the autonomous advertising agent. **October 21, 2026** Searching for one Google account in Manage Accounts no longer deactivates your others, and the TikTok campaign link opens the right campaign ## Activate One Account Without Switching Off The Rest **Manage Accounts no longer drops accounts you didn't touch.** The picker for Google accounts loads in pages and has a search box, so it only ever shows part of your list. Saving sent just the accounts you had ticked on screen, and anything else went inactive. Searching for one account and activating it could switch off every other account you already had active. Saving now starts from the accounts that are already active and applies only what you changed: accounts you tick are added, and an account leaves the active set only when you untick it yourself. The activate button and the counter reflect that full set, so you can't go over your plan's account limit without seeing it first. **TikTok: the "View in TikTok Ads Manager" link opens your campaign.** After `create_tiktok_video_campaign`, the link in the result used the campaign ID where TikTok expects your advertiser ID, so it didn't land on the campaign you'd just created. It now carries both, and opens that campaign in Ads Manager. → [Multi-account](/docs/knowledge-base/multi-account) · [TikTok Ads](/docs/ad-platforms/tiktok-ads) **October 21, 2026** ChatGPT users: add Adspirer as a custom MCP server. It works on every plan, including Free ## In ChatGPT, Connect Adspirer Directly The Adspirer plugin in ChatGPT's **Plugins** directory is having issues, and it was already missing Amazon Ads, ChatGPT Ads, Google Analytics, and Google Search Console. The ChatGPT setup guide now leads with the path that works: add Adspirer as a **custom MCP server**. ChatGPT moved and renamed the option, so the steps changed. Open **Plugins → Add → Add custom MCP server**, keep **Server URL** selected, paste `https://mcp.adspirer.com/mcp`, set **Authentication** to **OAuth**, and click **Create as a plugin**. Then **Try in chat → Connect**, and click **Authorize** on Adspirer. About two minutes, on any ChatGPT plan, including Free. You get every tool the day it ships, on the same Adspirer account you already use. If you installed the plugin, disconnect it under **Settings → Plugins** so ChatGPT doesn't pick it. → [ChatGPT setup, step by step](/docs/ai-clients/chatgpt) **October 19, 2026** Amazon reports stay inside the ad product you ask for, and Meta reports and campaign flows stop saying things that aren't true ## Reports That Say What The Data Says **Amazon: a Sponsored Brands report is now only Sponsored Brands.** Sponsored Products, Brands, and Display share one analytics store, and campaign, search-term, targeting, product, ad-group, and placement reads were filtering by account and date only. Ask for Sponsored Brands and you got Display and Products rows too, with account-wide totals. Each read now returns the product you asked for. `ad_product` takes `SP`, `SB`, `SD` or the full names; anything else is rejected with an error instead of defaulting to Sponsored Products. **Meta performance and audience reads no longer mislead.** * A date range entirely after your last delivery used to say your range was "before any recorded activity." It now says there was no delivery in the period and gives the date of the most recent activity. * The CPC and CPA lines in the written summary of `get_meta_campaign_performance` now match the table. The summary line could read \$0.00 while the table had the real figure. * `get_meta_audience_insights` no longer reports "performing steadily" when there is nothing to rank. It says either that there was no delivery, or that impressions delivered but Meta couldn't resolve them to an age or gender segment. * `validate_catalog_readiness` reports **limited** retargeting when the pixel fires only `InitiateCheckout` or `AddToWishlist`. Only `ViewContent` or `AddToCart` counts as ready. **Meta campaign flows.** `validate_and_prepare_meta_assets` on a single image used to print "Asset Bundle ID: None" and a next step that passed `"None"` to `create_meta_image_campaign`. It now returns the image hash and points you to `existing_image_hash`. Carousel cards take the same hash under `image_hash`. `resume_meta_campaign` no longer claims delivery has resumed: it sets the campaign to ACTIVE, and delivery needs an active ad set and ad too. → [Amazon Ads](/docs/ad-platforms/amazon-ads) · [Meta Ads](/docs/ad-platforms/meta-ads) **October 19, 2026** Remove Google radius targets by ID, see full radius addresses, and Meta ad-set targeting edits no longer wipe what you didn't send ## Take A Radius Back Out, And Edit Meta Targeting Without Wiping It **Google radius targeting now works in both directions.** `remove_campaign_proximity` is the opposite of `add_campaign_proximity`: ask your assistant to stop targeting within a set distance of an address and it removes that radius. It works from the **Criterion ID** that `get_campaign_targeting` now shows beside each radius and location. It only ever removes radius targets, so an ID that belongs to a location or keyword is skipped and reported instead of deleted. `get_campaign_targeting` also reads radius targets properly. A street address used to show as a bare country code with no units. It now shows the full address and miles or kilometers. Targeting reads refresh within a minute, and a change you make shows on the next read. **Meta partial targeting edits keep the rest.** Meta replaces the whole targeting spec on every edit, so changing only an age range on `update_meta_ad_set` or `update_meta_catalog_ad_set` used to drop locations, interests, and everything else you didn't resend. Edits now merge onto the ad set's current targeting. Send only the keys you want to change; to clear a key, send it empty. → [Google Ads tools](/docs/ad-platforms/google-ads) · [Meta targeting](/docs/ad-platforms/meta-ads) **October 2, 2026** Connecting an ad account mid-setup no longer loses the hand-off back to the Authorize screen your AI client is waiting on ## Connect An Ad Account Mid-Setup, Still Land On Authorize Setting up from ChatGPT, Claude, or any other client ends on Adspirer's **Authorize** screen, and most people connect their first ad account on the way there. That connect opens the ad platform's own sign-in in a pop-up — and on mobile Chrome and desktop Safari, that pop-up often comes back without a link to the tab that opened it. Adspirer was holding the pending authorization in that one tab, so the return had nowhere to go: setup finished, you landed on your account page, and the client that sent you there was never connected. The authorization now travels with you instead of sitting in one tab. It rides on the return address Adspirer hands the ad platform — Google, Meta, TikTok, LinkedIn alike — so an opener-less pop-up return still knows to finish the hand-off. The plan step in the middle of setup keeps it the same way. **And if you already finished setup in another tab,** returning to the tab that still carries the authorization forwards you straight to the **Authorize** screen instead of showing you your account page. Only an authorization on the address itself counts, so an ordinary visit to the setup page can never replay an old one. → [Setup troubleshooting](/docs/knowledge-base/faq#troubleshooting) · [Add Adspirer to your agent](/docs/add-to-your-agent) **September 30, 2026** The Adspirer Authorize screen now shows it's working, ignores a second click, and restarts a lapsed sign-in instead of showing an error page ## You Clicked Authorize. Now The Page Says So. Every client's setup ends on the same screen: Adspirer's **Authorize** page, where you grant your assistant access. You clicked **Authorize** and the page sat there, apparently unchanged, for a couple of seconds while your assistant's callback loaded — and the button was already outlined when the page opened, so it looked selected before you touched it. The natural response is to click again, which sent a second approval for a connection that had already been approved. The screen now answers the first click. The button turns into a spinner reading **Connecting…**, with a line underneath naming the app you're connecting and telling you that you'll be taken back automatically. Clicks after the first do nothing, and so does Enter — the first click is the one that counts, so a second one can't send a second approval. Nothing is focused when the page loads. If the hand-off takes longer than usual, the screen says so rather than leaving you to guess. Around eight seconds it tells you it's still connecting and to keep the window open; around twenty it tells you to press **Authorize** again if your client never opened. Desktop apps hand off differently — they open over this page instead of replacing it — so those end on **Sent ✓** and tell you that you can close the window once the app comes up. **A lapsed sign-in no longer dead-ends.** Leave the Authorize screen open long enough and your Adspirer sign-in expires behind it. Clicking **Authorize** then used to land you on a bare error page with no way forward. Now it sends you back through sign-in and returns you to the same Authorize screen with your request intact — finish signing in, click **Authorize**, and you're connected. No access is granted on that path, and the expired sign-in isn't carried through it. → [Setup troubleshooting](/docs/knowledge-base/faq#troubleshooting) · [Quickstart](/docs/quickstart) **September 29, 2026** Adspirer is an official, reviewed listing in Claude, ChatGPT, Cursor, and Grok Bot — search for it and add it, no custom connector ## Search For Adspirer, Click Add. That's The Whole Setup. Adspirer is now an official, reviewed listing in every major chat app's own directory, so setup is a search and one click: | App | Listing | Click | | - | - | - | | **Claude** | **Adspirer Ads & Performance Marketing Agent**, an **Anthropic-verified** connector (Anthropic reviewed it for quality and security). The **Adspirer** plugin in Anthropic's directory adds 15 skills, 5 slash commands, and an agent on top | **Connect to Claude** / **Add** | | **ChatGPT** | **Adspirer** in the **Plugins** directory, reviewed by OpenAI (OpenAI renamed Apps to Plugins) | **Install plugin** | | **Cursor** | **Adspirer** on the Cursor Marketplace, **Verified by Cursor** | **Add to Cursor** | | **Grok Bot** | **Adspirer for Grok Bot**, the same Verified by Cursor listing | **Add to Grok Bot** | **Drop the custom connector in Claude, Cursor, and Grok Bot.** The listing includes the connector, the skills, and the agent, and it's always current. If you added `mcp.adspirer.com` by hand before, remove it so your assistant doesn't see every tool twice. The Claude page no longer asks you to paste a `SKILL.md` either, because the plugin ships the skills. ChatGPT is the one exception for now. The plugin is still waiting on OpenAI to publish our latest update, so it has no Amazon Ads, ChatGPT Ads, Google Analytics, or Search Console tools yet. For those, **Plugins → Add → Create MCP App** connects straight to Adspirer's server in about two minutes. Codex and clients without a listing keep their existing install paths. → [Add Adspirer to your agent](/docs/add-to-your-agent) · [Claude](/docs/ai-clients/claude) · [ChatGPT](/docs/ai-clients/chatgpt) · [Cursor](/docs/ai-clients/cursor) · [Grok Bot](/docs/ai-clients/grok) **September 28, 2026** Sellers can read the brand entity ID Sponsored Brands requires, instead of hunting for it outside Adspirer ## Sponsored Brands Asks Sellers For A Brand ID. Now You Can Just Read It. Creating a Sponsored Brands campaign on a **seller** account means passing a `brand_entity_id`, and Adspirer had no way to tell you what yours was. Either you already had it written down, or the campaign didn't get created. Vendor accounts were never affected — they can usually leave the field empty. **`list_amazon_brands`** reads the Brand Registry entities on your Amazon profile and returns each one's `brandEntityId`, next to its `brandId` and its registered brand name. Read-only. Ask for your brands, take the ID, create the campaign. Two things worth knowing. Sponsored Brands wants the **`brandEntityId`** — the long one starting with `ENTITY` — not the shorter `brandId` sitting beside it. And each advertiser profile carries its own, so a brand you sell under in the UK and in the US has a different ID in each marketplace; ask against the profile you're about to advertise on. It covers creative assets too — `upload_amazon_asset` takes the same ID from sellers. And when Amazon rejects a Sponsored Brands campaign over a brand problem, the error now names this tool rather than leaving you to work out which field it meant. → [Finding your brand entity ID](/docs/ad-platforms/amazon-ads#finding-your-brand-entity-id) · [Tool catalog](/docs/agent-skills/tools) **September 27, 2026** Performance Max finally answers 'what did it spend on?', and negative keyword lists become reusable across campaigns ## Performance Max Will Tell You What It Spent On Ask for the search terms on a Performance Max campaign and the answer used to be **"No search term data"** — which read like Google was hiding them. It wasn't. Google keeps PMax queries in a different place than Search and Shopping queries, and Adspirer was only reading the latter. Two tools now read the PMax side. **`analyze_pmax_search_terms`** returns every query the campaign matched, one row each, with cost, clicks, impressions, conversions, conversion value, CTR, and CPC. It opens with a summary across the whole window — how many terms, total cost, total conversions, and how many terms recorded no conversions along with what they cost. Those are facts, not a verdict: a query with nothing attributed may be upper-funnel or tracked elsewhere, and that call is yours. **`analyze_pmax_search_categories`** reads Google's own grouping of those queries into search categories, so you can see the shape of demand — which themes convert — without reading ten thousand individual terms. Google's residual **(Other search terms)** bucket comes back labelled rather than silently folded into a total. Both take a lookback of 7, 30, 60, 90, or 120 days, sort on any metric they return, and take a free-text filter so "show me everything with *free* in it" is one call. Results are ranked by cost first, so the terms worth your attention are on the first screen — paging is capped on purpose rather than inviting a walk through the long tail. Money renders in your ad account's own currency. ## One Negative Keyword List, Every Campaign `add_negative_keywords` blocks a term on one campaign. Blocking the same twenty terms across fifteen campaigns meant fifteen calls, and adding a sixteenth term later meant fifteen more. Five new tools bring Google's shared negative keyword lists to the agent: **`create_negative_keyword_list`** to start one, **`add_negative_keywords_to_list`** to fill it (each term `EXACT`, `PHRASE`, or `BROAD`), **`attach_negative_keyword_list_to_campaign`** to put it to work, and **`list_negative_keyword_lists`** / **`get_negative_keyword_list`** to read back what you have — the first of those reports each list's keyword count and how many campaigns it's attached to. Add a term to the list and every campaign carrying it blocks the term at once. Detaching a list from one campaign leaves it intact everywhere else. → [PMax search terms](/docs/ad-platforms/google-ads#pmax-search-terms) · [Shared negative keyword lists](/docs/ad-platforms/google-ads#shared-negative-keyword-lists) · [Tool catalog](/docs/agent-skills/tools) **September 27, 2026** Meta engagement campaigns stop failing on a performance goal you never picked ## An Engagement Campaign That Actually Gets Created Asking for a Meta engagement campaign — the objective that buys reactions, comments, shares, and saves on a Page post — failed at creation every time, with a rejection that blamed a setting you never chose: > Performance goal isn't available: You can't use the selected performance goal with your campaign objective Meta wants an engagement ad set to declare **where** the engagement happens. Adspirer sent the performance goal and the Page, but left the destination blank, and Meta refuses that pairing at creation — so the campaign never existed. It now sets the destination to the post itself, which is the one Meta accepts for post engagement. Every create path that can build an engagement ad set is covered: **`create_meta_image_campaign`**, **`create_meta_video_campaign`**, **`create_meta_carousel_campaign`**, and **`add_meta_ad_set`**. Nothing else moved. Pass `destination_type` yourself and your value still wins. Campaigns that send people into WhatsApp, Messenger, or Instagram Direct keep their own destination. Traffic, leads, sales, and awareness campaigns were never affected and are unchanged. → [Engagement campaigns on Meta](/docs/ad-platforms/meta-ads#engagement-campaigns) **September 23, 2026** Google Analytics, Search Console and Tag Manager stop guessing which property, site or container you meant, and ask instead ## One Google Login, Many Properties — And No More Guessing Which Connecting Google Analytics hands Adspirer one Google login, and that login usually reaches more than one thing: a dozen GA4 properties, several verified Search Console sites, a Tag Manager account with containers under it. Ask for "last week's sessions" without saying which property and the agent had to pick one. A wrong read gave you another site's numbers with no hint they were the wrong site's. A wrong write — a tag created in the wrong container — quietly changed tracking on a live website. The agent now asks. Call an action that operates on a specific property, site, or container without naming one, and Adspirer pulls the real labelled list off your connection and hands it back for you to choose from: ``` You have 28 properties connected for Google Analytics on jane@agency.com. This is NOT a connection problem — do not reconnect. Tell me which one — a single property, a few, or all of them — then call again. ``` Picking is part of the conversation, not a lookup you go do somewhere else. You can answer with one, with a few, or with **all** — and "all" means every property on *that* connection, one call each, so the agent says what that will cost you in tool calls and waits for a yes before running them. The question itself doesn't cost you a tool call. **Reads with exactly one property, site, or container are untouched.** If your login reaches a single GA4 property, nothing changes — the agent uses it and answers, exactly as before. **Writes always confirm, even at one.** Search Console's `submit-url-for-indexing`, `submit-sitemap` and `delete-sitemap`, and Tag Manager's `create-tag`, `update-tag` and `update-variable` name their target back to you before they run. Tag Manager is a three-level hierarchy — account, then container, then workspace — and it asks one level at a time rather than presenting a list of everything at once. This is the same idea as [one integration holding more than one account](/docs/agent-skills/tools#marketing-stack-integrations-plus-and-above), one level deeper: first which account, then which property inside it. → [Google Analytics integration](/docs/integrations/google-analytics) · [Integration tool reference](/docs/agent-skills/tools) **September 20, 2026** Meta housing, employment, credit and politics campaigns no longer fail when you target outside your ad account's own country ## A Housing Campaign Can Run Somewhere Other Than Your Own Country Meta requires a campaign in a Special Ad Category — **housing, employment, credit, or social issues, elections and politics** — to declare the country it runs in, separately from its targeting. Adspirer sent the category but never the country, so Meta fell back to whatever country your ad account sits in and rejected the campaign the moment the targeting pointed anywhere else: > The locations are not in the countries selected for Special Ad Categories A US agency launching a housing campaign in Brazil hit that every time. Adspirer now reads the country out of the campaign's own targeting and sends it alongside the category — ask for a housing campaign targeting Brazil and nothing else is needed. It covers every create path that takes a special ad category — **`create_meta_image_campaign`**, **`create_meta_video_campaign`**, **`create_meta_carousel_campaign`**, and **`create_meta_catalog_campaign`** — plus **`update_meta_catalog_campaign`**. Two cases still want a word from you. If you target only cities, regions, or ZIP codes and none of them names a country, there is nothing to read a country from: pass `special_ad_category_country` with the ISO codes yourself, such as `['BR']` or `['US', 'CA']`. Pass it too when the country the campaign is declared in genuinely differs from where it's targeted. Adspirer never guesses one. Campaigns with no special ad category are untouched — the field isn't sent at all. → [Special Ad Categories on Meta](/docs/ad-platforms/meta-ads#special-ad-categories) **September 18, 2026** ChatGPT Ads gets custom audiences from your own customer list, server-side conversion sending with hashed matching, conversion reporting, and ad-group auto-bidding ## Your Customer List Is Now A ChatGPT Ads Audience Upload the people you already know and target them inside ChatGPT — or keep them out of a prospecting campaign. Twelve new tools cover the whole life of an audience: **`create_chatgpt_custom_audience`** to build one (empty, or seeded from a file you've uploaded to OpenAI), **`add_chatgpt_custom_audience_members`** and **`remove_chatgpt_custom_audience_members`** to change it, **`replace_chatgpt_custom_audience_members`** to swap the membership wholesale, and **`merge_chatgpt_custom_audiences`** to combine up to 64 of them into one. Give the agent emails, phone numbers, identifiers you've already hashed, or Google Advertising IDs. Building an audience is asynchronous, so the tools hand back an operation you can watch with **`get_chatgpt_custom_audience_operation`** — and the agent polls until the audience is `ready` instead of reporting a size it can't see yet. Then target it. A campaign can include audiences and exclude audiences, and an ad group can bid **0.1× to 10×** for one, so your highest-value list pays up without a separate campaign. Including an audience or bidding on it needs roughly 25,000 matched users; excluding one has no minimum. Size comes back as OpenAI's matched-user range — that is the only number OpenAI publishes, and Adspirer won't invent a precise one. ## Conversions You Send Yourself, And View-Throughs Kept Apart **`send_chatgpt_conversion_event`** posts a real conversion through the Conversions API — the path that survives ad blockers and the cross-device journeys a pixel misses. Send the event type, its value and currency, an order id so OpenAI can de-duplicate against the pixel, and the customer fields that raise match rates: email, phone, name, external id, country, city, region, postal code, IP, user agent, Google Advertising ID. Raw emails, phone numbers, and names are **SHA-256 hashed at the point of the call**. The plain values never reach Adspirer's backend and are never written to your tool-call history; the response reports which match keys were used, never what they were. Values are whole minor units — 2599 for \$25.99 — and a decimal is rejected rather than quietly truncated. Ask for a dry run and nothing is sent. **`get_chatgpt_conversion_insights`** reads the results back by campaign, ad group, or ad, split by country or device on request. View-through conversions get their own line and are never folded into the total, so a view is never counted as a click. ## Auto-Bidding, Surfaces, And URLs That Tag Themselves Ad groups now carry a bid strategy. Keep `fixed_bid` and set the number yourself, or hand it over with `maximize_clicks` or `maximize_conversions` — each of which needs a matching campaign bidding type, checked before the request is sent rather than after OpenAI rejects it. Three smaller things that were missing: * **Surface targeting.** Restrict a campaign to `ios_app`, `android_app`, `desktop_web`, or any mix, instead of running everywhere. * **One query string for every landing page.** Set `utm_source=chatgpt&utm_campaign={campaign_id}` on the campaign; `{campaign_id}`, `{ad_group_id}`, `{ad_id}`, and `{ad_account_id}` are filled in when the ad serves. * **Lists you can actually search.** Campaigns, ad groups, ads, pixels, and event settings all take a free-text search, a status filter, a sort, a date range, and paging — and report *3 of 41* rather than handing back an empty result that reads like an empty account. On ads the search covers the copy itself. Targeting a campaign now has five sides — locations in and out, audiences in and out, and surfaces. Change one and the other four stay exactly as they were; if the agent can't read your current targeting to merge a change into it, it refuses rather than guessing. → [ChatGPT Ads](/docs/ad-platforms/chatgpt-ads) · [Tool catalog](/docs/agent-skills/tools) **September 18, 2026** Adspirer is on the Cursor Marketplace — one install for the subagent, 14 skills, 2 rules, and the MCP server, and the same listing runs in Grok Bot ## Installing Adspirer In Cursor Is One Click Now Adspirer is listed on the [Cursor Marketplace](https://cursor.com/marketplace/adspirer). Open **Customize** in Cursor's sidebar, search **adspirer**, and select **Install** — or type `/add-plugin adspirer` in any chat. Choose **user** scope for every project or **project** scope for one client folder. One install brings four things: the `adspirer` MCP server with 400+ tools, the `performance-marketing-agent` subagent, **14 skills**, and **2 rules**. Nothing is copied into `~/.cursor/` by hand, the plugin updates itself, and Cursor reviews every release before it ships. The 14 skills replace the old 5. There is now one per platform — `adspirer-google-ads`, `adspirer-meta-ads`, `adspirer-amazon-ads`, `adspirer-linkedin-ads`, `adspirer-tiktok-ads`, `adspirer-chatgpt-ads` — each carrying the traps that cause most failures there, plus workflow skills for setup, launch, optimize, performance review, and creative, and `adspirer-docs` for questions about Adspirer itself. Cursor matches them from what you ask; `/adspirer-optimize` and friends force one. **The `install.sh` script is retired.** If you ran it, delete the `adspirer-*` folders it left in `~/.cursor/skills/`, `~/.cursor/agents/`, and `~/.cursor/rules/` so they don't shadow the plugin's copies. ## The Same Plugin Runs In Grok Bot [Grok Bot](/docs/ai-clients/grok) installs from the same marketplace. Open **Marketplace** at the bottom of the sidebar, add **adspirer**, and complete **Authorize** — your bot now reads and acts on your live ad accounts. All 14 skills come across. What Grok Bot adds is scheduling that doesn't depend on your laptop being open. A routine runs in the cloud on an hourly, daily, weekday, weekly, or monthly schedule, so a Monday scorecard across every connected platform arrives before you sit down. Every run spends tool calls, so start weekly. Installing in one product doesn't install in the other — they share a marketplace, not an install. → [Cursor setup](/docs/ai-clients/cursor) · [Grok Bot setup](/docs/ai-clients/grok) · [What's in the plugin](/docs/agent-skills/cursor-agent) **September 17, 2026** Microsoft Advertising is no longer read-only — create and edit campaigns, ad groups, ads, keywords, budgets, bid strategies, extensions, Performance Max asset groups and targeting from your assistant ## Your Bing Account Is Something You Can Change Now The launch note two days ago said creating and editing Microsoft campaigns weren't live. They are now. Every control you can create on Microsoft Advertising, you can also edit — campaign down to a single device bid adjustment — without opening the Microsoft interface. Ten edit tools, one per layer: * **`update_microsoft_campaign`** — name, budget, bidding scheme, languages, time zone, URL tracking, dates, and status. * **`update_microsoft_ad_groups`** — name, status, CPC/CPM/CPV/mCPA bids, bidding scheme. * **`update_microsoft_ads`** — status, and the creative on responsive ads: headlines, descriptions, long headlines, images, videos with pinning, paths, and URLs. * **`update_microsoft_keywords`** — match type, status, and per-keyword bid. * **`update_microsoft_budgets`** and **`update_microsoft_bid_strategies`** — the shared budget library and portfolio bid strategies. * **`update_microsoft_asset_groups`** — Performance Max asset groups: business name, call to action, headlines, descriptions, images, videos, final URLs, paths, search themes, and dates. * **`update_microsoft_ad_extensions`** — sitelink text and URLs, callout text, price rows, promotion details. * **`update_microsoft_ad_group_criterions`** and **`update_microsoft_campaign_criterions`** — the bid adjustment and status on targeting you've already added, at ad-group or campaign level. The create tools from the launch — campaigns of every type, ad groups, ads, keywords, extensions, Performance Max asset groups, audiences, and deep targeting — are live too. ## Edits Are Partial, With Two Places They Aren't Pass the fields you want changed and everything else is left alone. Clearing a value is explicit: an empty string `""` clears a URL field, `0` detaches a shared budget or a portfolio bid strategy, and an end date on or after 2050-01-01 removes the end date. Two exceptions worth knowing before you ask for an edit: * **Creative lists replace.** Send headlines, descriptions, or images on an ad or an asset group and that whole list is replaced — omit it to keep what's there. * **Ad extensions are all-or-nothing.** Microsoft deletes any field you don't send, so an extension edit has to carry the complete object. Ask your assistant to read the extension back with `list_microsoft_ad_extensions` first and it will. A campaign's type can't change, and neither can the detail of a targeting criterion — the age range, device, or geo itself. Change a bid or pause it in place; to change what's targeted, delete it and add it again. ## Two Things That Can't Go Wrong Quietly A Performance Max asset group edit refuses to replace a live asset list when an image or video fails to resolve, rather than emptying it. And extension and targeting edits never report an item as applied when Microsoft rejected it. `list_microsoft_ad_extensions` also returns your account's extension library now — it came back empty for every account before, whatever was in there. Performance reporting on Microsoft — spend, clicks, conversions — isn't live yet. Edit a live Bing campaign. On my Microsoft Advertising account, raise the budget on my top Search campaign to 75 a day, pause every keyword in its ad groups that has no conversions, and set a -20% bid adjustment on tablets. → [Microsoft Advertising tools](/docs/agent-skills/tools) · [What Adspirer can and can't do](/docs/knowledge-base/capabilities) **September 16, 2026** Connect a Microsoft Advertising account and ask your assistant what's running on it — Search, Shopping, Audience, Performance Max, Hotel and App campaigns, with status, budget and bidding scheme ## Your Bing Account Is Now Something You Can Ask About Microsoft Advertising (Bing Ads) connects in the Connections tab, through Microsoft's own sign-in, the same way Google or Meta does. Once it's connected your assistant can read the account without you opening the Microsoft interface. Two tools are live: * **`list_microsoft_accounts`** — every Microsoft Advertising account you've connected, each with the `account_id` to pass, its customer id, and its currency. * **`list_microsoft_campaigns`** — campaigns of every type on the account — **Search**, **Shopping**, **Audience**, **Performance Max**, **Hotel**, and **App** — each with its status, budget, and bidding scheme. Several Microsoft Advertising accounts, and several Microsoft logins, can be connected at once. Pass the `account_id` from `list_microsoft_accounts` to say which one you mean; with a single account connected you can leave it out. Ask without naming one while several are connected and you get the account list back rather than a guess — that reply is not a connection problem, and disconnecting won't change it. Budgets and bids read back as plain decimals in the account's own currency: `50` means 50.00 in that account's currency, never cents and never micros. ## Reading Is The Whole Surface Today Creating and editing Microsoft campaigns is not live yet. Everything above is read-only — nothing Adspirer does on a Microsoft account can change it or spend on it. The write tools land in a later release and will be announced here. See what's running on your Bing account. List my Microsoft Advertising accounts, then show me every campaign on the main one with its type, status, budget and bidding scheme. → [Microsoft Advertising tools](/docs/agent-skills/tools) · [What Adspirer can and can't do](/docs/knowledge-base/capabilities) **September 16, 2026** Pause or re-enable any number of Google ads, ad groups, or campaigns in one call each, with every change verified against Google before it reports success ## Swapping Ads Across An Account No Longer Means Hundreds Of Calls Refreshing creative across 150 ad groups used to mean pausing each old ad and resuming each new one, one at a time. Three new tools do the whole sweep in a call apiece: * **`bulk_update_ad_status`** — pause or enable any number of ads in one ad group. Pass `ad_group_id`, the `ad_ids`, and `PAUSED` or `ENABLED`. One call per ad group; get the IDs from `get_campaign_structure` or `get_ad_performance`. * **`bulk_update_ad_group_status`** — pause or enable any number of ad groups, on any campaign type: Search, Performance Max, Display, Demand Gen. Pass `campaign_id` too and each ad group is checked to belong to that campaign, so an ID from somewhere else is reported instead of quietly changed. * **`bulk_update_campaign_status`** — pause or enable any number of campaigns from a list of IDs. There is no cap on how many IDs you can pass. All three set status and never remove anything, so re-running with the opposite status undoes the sweep. ## A Bulk Change That Didn't Land Can't Report Success Each of these reads the live status back from Google after writing. Anything that didn't actually change is moved out of the success list and into the failures, with the reason — so a swallowed mutation shows up as a failure rather than a green tick. Before writing, the current status is checked as well. Anything already in the target status is skipped rather than rewritten, an ID that isn't in the ad group or campaign you named comes back as not found, and a removed entity can't be re-enabled — Google has no route back from removed, and the tool says so instead of failing obscurely. Nothing changes for one-off work: `pause_campaign`, `resume_campaign`, `pause_ad_group`, and `resume_ad_group` are unchanged, and `bulk_update_keyword_status` still covers keywords. Pause every old ad in an ad group before swapping in new creative. List the ads in my Search ad group, then pause all of the ones launched before this month in a single bulk call and confirm each one actually changed. Pause a set of campaigns at once. Pause every Google Ads campaign that spent money last month with zero conversions — use the bulk campaign status tool so it's one call, and show me anything that didn't pause. → [Google Ads campaign management](/docs/ad-platforms/google-ads#campaign-management) · [Tool reference](/docs/agent-skills/tools) **September 15, 2026** A max CPC ceiling on Maximize Clicks is applied instead of discarded, and a brief you asked for weekly no longer arrives every morning ## Maximize Clicks Took Your Max CPC And Threw It Away Put a campaign on Maximize Clicks with a cap — *"maximize clicks, but never pay more than CA\$8 a click"* — and `update_bid_strategy` accepted the number, reported **Bidding Strategy Updated**, and saved no ceiling at all. The campaign went on bidding uncapped. A ceiling was only ever written for Target Impression Share; on Maximize Clicks it was dropped on the way to Google. Over the last 120 days, 191 successful calls passed a cap that never landed. `cpc_bid_ceiling` now applies on **Maximize Clicks**, where it caps what the strategy may pay for a click. Give it in your account's own currency as a decimal — `8` for a CA\$8.00 cap, not cents and not USD. Leave it out and an existing ceiling stays as it is, so you can change something else about the campaign without clearing the cap by accident. The response no longer takes your word for what was saved. Adspirer reads the ceiling **back from Google** after the write and shows what is actually stored, before and after — so **"Max CPC ceiling: not set"** means the cap really is absent, rather than repeating the number you sent. On the strategies that have no max-CPC field at all, a ceiling is now refused up front, naming the two strategies that accept one, instead of being taken and discarded. Reading a cap back no longer means opening the Google Ads interface either: `list_campaigns` and `get_campaign_structure` both report the ceiling and which strategy it sits on. Cap what Maximize Clicks pays for a click. Put my Search campaign on Maximize Clicks but never pay more than \$8 a click, then read the ceiling back from Google and confirm it saved. ## A Brief You Asked For Weekly Arrived Every Morning Ask for a weekly performance brief and you were told you would get one — *"Schedule: weekly at 09:00"* — and then it arrived daily. Every brief scheduled through an assistant fell back to a daily cadence no matter what you requested. The confirmation echoed your request rather than what was stored, so nothing in the reply gave you a reason to check. `schedule_brief` now keeps the cadence you actually asked for — **daily**, **weekly**, or **every N days**. Weekly runs on Mondays at the time and timezone you chose; every-N-days runs on its own interval. If you set up a brief before this and it has been landing every morning, it is still stored as daily — fixing it means scheduling it again. Ask for your scheduled tasks, delete the ones whose cadence is wrong, and create them fresh at the cadence you want. Audit the cadence on your existing briefs. List my scheduled tasks and tell me the cadence of each performance brief. For any that should be weekly rather than daily, delete it and schedule it again as weekly. → [Google Ads campaign management](/docs/ad-platforms/google-ads#campaign-management) · [Scheduled briefs & reports](/docs/agent-skills/tools) **September 12, 2026** Performance Max campaigns with Brand Guidelines can be built end to end — the square logo and business name now attach where Google requires them ## A Brand Guidelines PMax Campaign Could Never Finish Its Asset Group Turn on Brand Guidelines for a Performance Max campaign and Google stops accepting the square logo and business name as asset-group assets — it requires them on the **campaign**. Adspirer only ever linked them to the asset group, so the campaign could never be completed: the attempt came back with *"require at least one square logo to be linked as a CampaignAsset"*, and no asset-group tool could clear it, because none of them link at the campaign level. **`create_pmax_campaign` now takes `brand_guidelines_enabled`.** Set it at creation and the logo and business name are routed to the campaign level in the same call. Google does not allow this flag to change after the fact, so it is create-time only — a campaign built without it cannot be converted later. **`add_pmax_campaign_logo` links the square logo to a campaign that already exists.** Point it at an `asset_id` already approved in your account, or give it an image URL to upload a new one, and pass `business_name` to attach both at once. A logo that is already linked is skipped rather than duplicated. `add_pmax_asset_group` is aware of Brand Guidelines too — it builds the group from text and marketing images while the brand assets go to the campaign. **`get_pmax_conversion_goals` reads what a campaign actually bids toward** — each goal's category, its origin, and whether it is biddable. The check it exists for is confirming that purchase is the only biddable goal before a retail campaign spends anything. Performance Max campaigns without Brand Guidelines are unchanged; none of this applies unless the setting is on. ## Removing The Logo From A Brand Guidelines Campaign Now Stops You A campaign with Brand Guidelines enabled cannot serve without its logo and business name, and nothing warned you before the campaign went dark. Removing or pausing a logo, landscape logo, or business name on one of these campaigns is refused now, with the reason and the safe way to swap it — add the replacement first, then remove the old one. Re-enabling an asset is never blocked. Reads caught up as well. `list_campaign_extensions` and the Extensions block of `get_campaign_structure` show campaign-level logos and the business name, which previously read as absent however much was attached. Build a Performance Max campaign with Google's brand-controlled layout. Create a Performance Max campaign with Brand Guidelines enabled, link our square logo and business name at the campaign level, then confirm purchase is the only biddable conversion goal. → [PMax Brand Guidelines](/docs/ad-platforms/google-ads#pmax-brand-guidelines) **September 11, 2026** A campaign you launched today stops reporting no delivery, your stop times land in your own timezone, and sitelinks attached at ad-group level are finally visible ## "No Delivery" On A Campaign That Launched An Hour Ago Launch a Meta campaign, ask whether it's running, and Adspirer could tell you nothing was being delivered while the campaign was already spending. Asking again tomorrow would show it. `get_meta_campaign_details` has two paths — with the full ad set and ad hierarchy, and without — and only the second one was passing your requested date window through. The hierarchy path fell back to a silent `last_7d`, and Meta's `last_7d` **excludes today**, so a campaign created today had a reporting window containing none of its life. It fired on 5,262 calls across 829 accounts. Both paths carry the window now. And when you don't name one, a campaign created in the last seven days defaults to its own run so far — creation date through today — instead of to a week that ended before it existed. An established campaign still defaults to the last 7 days, so nothing changes on the accounts where that was already the right answer. Check a campaign you just launched. I launched a Meta campaign today. Is it actually delivering, and what has it spent? ## Your 11:59 PM Stop Time Was 11:59 PM In London Give Meta a date and time with no timezone on it — `2026-09-30T23:59:59` — and Meta reads it as UTC. A campaign an advertiser in Los Angeles meant to stop at midnight stopped at 5 PM, and a dated start ran and spent hours before it was supposed to be live. 763 calls across 193 accounts sent a stop time this way; 67 sent a start time. Adspirer now attaches your **ad account's own timezone** to a time you give without one, daylight saving included, on every create and update path — campaigns, ad sets, and all five ad types, catalog ads included. A time that already carries an offset, a `Z`, or a bare date is passed through untouched. Update responses show the time that was **applied**, offset and all, so you can read back what Meta actually stored rather than the string you typed. `update_meta_campaign` also says plainly that it changed the **campaign's** stop time, and that ad sets keep their own end times — the ambiguity that had people setting a campaign stop date and wondering why an ad set kept spending. ## A New Ad Says PAUSED Three Times, And Means It Create a Meta campaign and Meta may email you that your ad is under review, which reads like it is about to start spending. Create responses now show the status at every level — **Campaign: PAUSED · Ad set: PAUSED · Ad: PAUSED (in Meta review)** — with a note that Meta reviews and notifies about a new ad even while everything is paused, and that nothing delivers or spends until you set the campaign Active. Wired into the image, video, and carousel create paths. **Carousel asset prep stopped pointing you at the wrong tool.** `validate_and_prepare_meta_assets` on a carousel printed `Asset Bundle ID: None` — a field carousels don't have — and told you to call `create_meta_image_campaign` next, which is not the tool that builds a carousel. It now lists the image hash per card and names `create_meta_carousel_campaign` with the fields it wants. **`search_meta_targeting` stopped returning all 285 behaviors.** Meta's behavior browse endpoint accepts a search term and a limit and then ignores both, so asking for "engaged shoppers" came back with every behavior Meta has, *Facebook access (OS): Windows 7* among them. Adspirer pulls the category once and filters it itself, on name, description, and category path, and honours the limit you asked for. No match now returns an honest empty result instead of a haystack. Interest search was never affected. ## Sitelinks At Ad-Group Level Existed. Adspirer Said Zero. Extension assets can be attached at three levels in Google Ads — account, campaign, and ad group — and every read tool only ever looked at one of them. `list_campaign_extensions` and the Extensions block of `get_campaign_structure` read campaign level only, so an account with 16 live sitelinks on its ad groups was told **Sitelinks (0)**. Nothing read account level at all. 609 campaign checks across 345 accounts hit that flat zero. All three levels are read now, and each asset says where it's attached — *"16 at ad-group level — these serve"* rather than a count that hides which ones are actually running. **"None configured at any level"** appears only when all three really are empty, which is the difference between an extension you should add and one you already have somewhere you weren't looking. **Locations read as place names.** `get_campaign_targeting` used to hand back Google's raw criterion IDs — `geoTargetConstants/2036` — leaving your assistant to spend a call resolving each one, or to guess. Positive and negative locations now come back resolved: **Australia | Country | 2036**. ## Keyword Research Stopped Coming Back Empty For A City Ask `research_keywords` to research a city — *"McKinney, TX"* — and it could return nothing at all, then blame Google for an empty result. Google had returned around a thousand ideas. Keyword Planner scopes volume to the area you target, so city-level volumes are small, and a fixed 100-monthly-searches floor removed every single one. A quarter of all calls returned zero, and 35% of calls naming a city. The floor can no longer empty a list that had something in it: if it would remove everything, the top 20 by volume are kept and labelled as low volume. And the empty-result message is honest about who emptied it — it says Google returned nothing **only when Google returned nothing**, and otherwise tells you what Adspirer filtered out and why. → [Google Ads extensions](/docs/ad-platforms/google-ads#ad-extensions-assets) · [Meta campaign scheduling](/docs/ad-platforms/meta-ads#start-and-stop-times-use-your-account-timezone) **September 8, 2026** Lead-gen campaigns stop being reported as losing money at 0.00x ROAS, and Meta's 'authenticate your account' block finally comes with the steps that clear it ## Your Lead Campaign Was Never Losing Money At 0.00x ROAS Ask about wasted spend on an account that runs lead generation and Adspirer could hand back something that reads like a disaster: the campaign listed as losing money, most of its spend marked wasted, **ROAS 0.00x**. Lead campaigns earn no revenue, so that zero was arithmetic, not a finding — and acting on it meant pausing campaigns that were doing their job. The test behind it was on the wrong thing. Waste analysis chose its yardstick — revenue or cost per lead — by checking whether the campaign had recorded any conversion *value*. One stray purchase value drifting into a lead campaign on a mixed account was enough to make it look like a revenue campaign and get it graded on ROAS. `analyze_meta_wasted_spend`, `analyze_tiktok_wasted_spend`, and `analyze_linkedin_wasted_spend` now decide from the **campaign's objective**, so lead, messaging, and talent-lead campaigns are measured on cost per lead whatever values landed against them. A lead campaign with genuinely zero leads is still a real loss — that spend bought nothing — but it now reads as what it is: *spend with no leads recorded, ROAS does not apply to this objective*, and the suggested next step is to confirm your lead tracking rather than to pause. **LinkedIn gained a Lead Gen Campaign Performance table** it never had, sorted best cost-per-lead first. **TikTok stopped printing its internal `insufficient_signal` marker in the Severity column** and says `unrated (not enough data)` instead. **Budget optimization stopped saying "Only 0 days of data" about every campaign.** `optimize_meta_budget`, Google's `optimize_budget_allocation`, and `optimize_linkedin_budget` are meant to leave out campaigns with less than a week of data — there is nothing to optimize against yet. But none of them was counting the days, so every campaign carried that note *and* was optimized anyway: the answer said it had excluded the campaigns it had just reallocated. The count is real now, so the exclusion is real. When every campaign in the account is that young you get one plainly provisional note instead of a confident reallocation built on three days. On Meta the excluded campaigns are also listed by name with the reason, under **Constraints Applied** — a section that previously read two keys the backend had stopped sending, so it showed nothing at all. **Money in the written dashboard summaries reads as money.** Sentences that quoted a total used the currency code where the symbol belonged — `GBP17,808` — and fell back to `$` when the account currency couldn't be determined. They use the account's own symbol now. A metric that doesn't apply to your objectives shows as **n/a** with a note instead of a coloured delta, and click-through rate is never coloured as though up were always good. → [Which conversions Adspirer counts](/docs/ad-platforms/meta-ads#performance-analysis) ## Meta's "Please Authenticate Your Account" Is Not A Reconnect Meta error code **31**, subcode **3858385**, blocks the API from publishing or editing ads while the account itself keeps working normally in Ads Manager. Adspirer's message said the account needed re-verifying and to retry — which reads as *reconnect Adspirer*. Reconnecting never clears it, so customers reconnected, hit the same wall, and reconnected again. The error now carries the steps that actually clear it: open Ads Manager with no VPN, go to **Billing and payments** and click **Start Authentication** to get Meta's code; if that button isn't there, rename an existing ad in a private window and hit Publish to make the prompt appear. Turn on two-factor authentication, check [Account Quality](https://www.facebook.com/accountquality), and retry once — then wait 24 to 48 hours before trying again rather than hammering it. → [Meta troubleshooting](/docs/ad-platforms/meta-ads#meta-is-holding-a-security-check-on-the-account) **September 6, 2026** ChatGPT's App Store app no longer stalls when a tool it needs to read a schema isn't on its list ## The Assistant That Stopped Because A Tool It Needed Wasn't On Its List Before it calls anything, Adspirer has your assistant fetch that tool's exact parameters with `get_tool_schema`. That step is what stops it inventing an argument name and failing on a real campaign. But some clients hold a tool list that was frozen when you installed them — the ChatGPT App Store app is the common one, and some older uploaded skill kits do it too. On those, `get_tool_schema` isn't in the list at all, so the assistant announced that a required tool wasn't available and stopped, mid-task, with nothing done. The way around it already worked. Nothing said so. Any platform router will fetch a schema for you — `google_ads`, `meta_ads`, `linkedin_ads`, `tiktok_ads`, whichever you have — and what comes back is identical to calling `get_tool_schema` directly. That sentence is now in the text the assistant reads, so it takes the detour itself instead of giving up. Nothing changes if your client does list `get_tool_schema`: calling it directly by name is still the normal path, and still the one to use. → [Tool discovery](/docs/agent-skills/tools) **August 30, 2026** Google Ads accounts that aren't activated now appear with the reason instead of vanishing, and active accounts stop being marked inactive ## The Account That Wasn't There, And The One That Shouldn't Have Been Greyed Connecting Google Ads could hand you an empty account picker. If an account you genuinely have access to hadn't been activated on Google's side — billing never set up, or the account deactivated — discovery dropped it without a word and you got *"no accounts found"*. The account existed, you could see it in Google Ads, and Adspirer behaved as though it didn't. It shows up now. An account that can't be activated appears in the picker as a greyed-out row you can't select, carrying the reason it's unavailable. That's the difference between *"Adspirer can't see my account"* and *"this account needs billing set up in Google Ads"* — two problems with very different fixes, which used to look identical. The row carries the account number and the reason and nothing else: currency and time zone are left off, because the lookup that would have supplied them is the one that failed, and an invented currency is worse than a missing one. **Accounts that are fine are no longer greyed out by mistake.** The same check could go the other way. A transient hiccup on Google's side sometimes came back with a message that read like a deactivation notice, and an account that was perfectly active got shown as inactive and blocked from selection. Eligibility is now decided on the account's actual status rather than the wording of an error, and a check that fails temporarily leaves the account selectable instead of locking you out of it. → [Connecting Google Ads](/docs/ad-platforms/google-ads#connecting-google-ads) **August 25, 2026** Meta campaigns stop guessing which Facebook Page to run from when your account has more than one ## Two Facebook Pages, And Adspirer Was Quietly Picking One If your Meta ad account can run ads from more than one Facebook Page and you didn't name one, Adspirer used whichever Page Meta listed first. Meta has no "default Page" and the order it returns them in is arbitrary, so an ad could go out under the wrong brand — and it looked like a choice Adspirer had made on purpose. It doesn't choose any more. When the ad account has **exactly one** promotable Page, that Page is used and nothing changes for you. When it has **two or more** and you haven't named one, the campaign stops before anything is created and comes back with every Page it could run from, each with its name and ID, so you pick. Adspirer won't guess the linked Instagram account in that case either. **`list_meta_pages`** is the new tool behind it: every Facebook Page that can run ads on the account, with any Instagram account attached to it. Ask *"which Facebook Pages can I run ads from?"* and you get the list without starting a campaign to find out. See your promotable Pages before you launch. Which Facebook Pages can I run Meta ads from on my ad account? This covers image, video, carousel, and Advantage+ Catalog creation, plus `add_meta_ad_set` and `add_meta_ad`. Pausing, resuming, updating, and duplicating are untouched — those work on an ad that already has its Page. → [Choosing a Facebook Page](/docs/ad-platforms/meta-ads#choosing-a-facebook-page) **August 25, 2026** Adspirer installs into Codex inside the ChatGPT desktop app with three chat messages ## Codex Desktop: Three Messages, No Terminal The ChatGPT desktop app now has Codex built in, and Adspirer's Codex plugin installs from a chat window. Switch to **Codex** in the top-left dropdown, then send `codex plugin marketplace add amekala/ads-mcp`, `install plugin`, and `help me oauth it`. Codex runs each one, opens the Adspirer sign-in, and confirms when the connection is live. It's the same `adspirer-ads-agent` plugin as the terminal install — 400+ tools, five skills, brand workspace — so nothing changes if you later move to the CLI for scheduled runs. In the sidebar, the terminal guide is now **Codex Terminal** and the new one is **Codex Desktop**. Two optional extras follow the setup. Turn on the desktop app's **Computer use** and **Computer history** and Codex can work in Chrome and Excel and remember what you were doing. And if you have an **Expert Kit**, hand Codex the downloaded folder — it installs the skill and the account's agent itself, no file copying. → [Codex Desktop setup](/docs/ai-clients/codex-desktop) **August 24, 2026** Amazon ad review status, and long product-ad and asset lists you can actually page through ## Find Out Why The Ad Isn't Running An Amazon ad that never serves usually isn't broken — it's rejected, and Amazon doesn't volunteer that. **`get_amazon_moderation`** reads the review status straight off the ad: APPROVED, IN\_PROGRESS, REJECTED, or FAILED, broken out per component, so you can see that the text passed and the video didn't. On a rejection it comes back with the policy violation. Sponsored Products, Sponsored Display, and Sponsored Brands. Check an Amazon ad's review status. Check the moderation status of my Amazon ad and tell me if anything was rejected and why. **Long lists no longer stop partway.** On a large account, `list_amazon_product_ads` and `search_amazon_assets` used to truncate — whatever came after the first batch was unreachable. Both page properly now, and product ads can be narrowed by state or ad group up front so you don't have to page at all. `get_amazon_product_performance` returns the page you asked for instead of the top 20 every time, so the 40th ASIN is finally visible. **Sponsored Products ad extensions get an honest answer.** Amazon's API supports creating extensions for Sponsored Brands, Sponsored Display, and DSP — not for Sponsored Products, which are console-only. Asking for one used to return a bare `ACTION_NOT_SUPPORTED`; now you're told what's actually going on. An extension update that carries fields Amazon ignores is rejected out loud rather than reported as a success that didn't happen. → [Amazon Ads tools](/docs/ad-platforms/amazon-ads#creative-assets) **August 24, 2026** Several multi-text Meta ads can now run in one ad set, and a pixel on a traffic campaign finally records events ## The Second Multi-Text Ad Used To Be Rejected. Now It Just Runs. Give a Meta image or video ad several primary texts and headlines and Meta tests the combinations. Try to put a *second* one of those ads in the same ad set and it failed — *"You can only have one ad in a dynamic creative ad set"*, error `1885553`. That was Dynamic Creative doing what Dynamic Creative does: it caps an ad set at one ad. Multi-text ads are now built as Meta's **Flexible** format, which is an ordinary ad. So an image ad with three headlines, a video ad with two, and a plain single-text ad all coexist in one ad set and compete properly. Explicit Dynamic Creative is untouched — `create_meta_dco_ad` and `is_dynamic_creative` on `add_meta_ad_set` still give you a real DCO ad set, one ad and all. On-platform lead-form ads keep their previous shape too. **`add_meta_ad` with multiple texts works at all now.** It had been failing every single time with *"object\_story\_spec is malformed"* (error `1443048`) while the same creative through the create path was fine. A multi-text ad aimed at a lead form now carries the form through as well. **A pixel on a traffic, awareness, or engagement campaign records events again.** Those objectives don't optimize toward a pixel, so the `pixel_id` you passed was accepted and then dropped, and Website Events never switched on. It's now attached as ad-level tracking, so the events land in Meta reporting. Conversion objectives never had this problem and are unchanged. One more: a **Click-to-WhatsApp video** ad no longer dies on *"The field link is not supported in the field video\_data."* Meta's video creatives can't hold a top-level link, so the WhatsApp destination now rides the call-to-action instead. Image and carousel WhatsApp ads are byte-for-byte what they were. → [Several ads with multiple text variations in one ad set](/docs/ad-platforms/meta-ads#several-ads-with-multiple-text-variations-in-one-ad-set) **August 24, 2026** Four helper tools withdrawn after they reported working accounts as disconnected ## Four Helper Tools Pulled For Calling A Connected Account Disconnected `diagnose_my_setup`, `preflight_campaign`, `whats_changed_since_last_visit`, and `weekly_opportunities` are no longer part of the tool surface. Your assistant doesn't see them any more, so they won't come up on their own — treat them as gone. They were misreading which ad platform you meant. Say "meta" and the check looked for the account's canonical `meta_ads` name, failed to match it, and answered that no account was connected — on an account that was connected and working fine. That is worse than no answer: it sends you off to reconnect something that was never broken. The other **nine** Diagnostic & Helper tools are unaffected and still quota-free on every plan, Free included: `start_here`, `suggest_next_action`, `list_what_i_can_do`, `get_campaign_spec`, `validate_campaign_draft`, `explain_platform_error`, `why_did_this_fail`, `verify_campaign_is_live`, and `usage_value_summary`. If you were reaching for `diagnose_my_setup` to work out where a problem is, ask *"why did my recent calls fail?"* instead. `why_did_this_fail` names the platform's real error on each recent failure, which is usually enough to tell an expired AI-client connection apart from an ad-platform sign-in — the two connections customers most often confuse. → [Diagnostic & Helper tools](/docs/agent-skills/diagnostic-helper-tools) **August 24, 2026** A direct-connection path for ChatGPT with every current tool, while the App Store app waits on OpenAI review ## ChatGPT: Connect Directly For Amazon Ads, ChatGPT Ads, Analytics, and Search Console The Adspirer app in the ChatGPT App Store is behind. Every update to a ChatGPT app has to be approved by OpenAI, and our latest one hasn't been published — so App Store users have no **Amazon Ads**, **ChatGPT Ads**, **Google Analytics**, or **Google Search Console** tools, and won't see anything new until the next review lands. You don't have to wait. ChatGPT's **Developer mode** lets you add Adspirer as a custom connector that talks to `mcp.adspirer.com` directly: same account, same sign-in, every tool the day it ships. It takes about two minutes. The [ChatGPT setup guide](/docs/ai-clients/chatgpt) now documents both paths side by side, with a plain comparison so you can pick the one you need. The App Store app still works for Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads, and you can keep both installed. → [ChatGPT setup — App Store vs. custom connector](/docs/ai-clients/chatgpt) **August 22, 2026** Meta video ads upload regardless of file size, and a brand-new funded Meta account can create its first campaign ## Video Size Stopped Mattering An 80 MB video ad sometimes came back as **"Backend returned a non-JSON response (HTTP 503)"**. A 1.3 GB one came back as **"timed out after 250s"**, three times in a row. Same cause both times: Adspirer downloaded your entire video before handing it to Meta, so the bigger the file, the more likely the upload fell over. It doesn't download it any more. Adspirer hands Meta the URL and Meta fetches the file itself, so nothing about the upload depends on how big the video is. `create_meta_video_campaign`, `add_meta_ad`, and `add_meta_ad_set` all take the same path. One thing this asks of you: **the video URL has to be reachable from the public internet**, because Meta is the one fetching it now. A Google Drive or Dropbox link shared with "anyone with the link" works; a private or sign-in-required link does not. If Meta genuinely can't fetch it, Adspirer falls back to fetching and pushing the file itself. → [Creative assets](/docs/ad-platforms/meta-ads#creative-assets-what-you-need-to-know) ## "No Payment Method Is Set" — On An Account That Has A Card Before creating a campaign, Adspirer checks the Meta ad account for the things Meta will reject it for. The payment check read the wrong signal: Meta leaves that field empty on an account that has a valid card attached but has **never spent** — which is exactly the state of every brand-new account at the moment its owner launches their first campaign. So a first campaign got blocked with **"No payment method is set on this Meta ad account"** on accounts that were funded and ready. Worse, the phantom blocker was listed ahead of any real one, so when something genuine was also missing — usually a promotable Facebook Page — you went and fixed the wrong thing. It now reads Meta's own `HAS_VALID_PAYMENT_METHODS` capability, and it fails open: if Meta's answer comes back partial or empty, Adspirer doesn't block a campaign Meta would have accepted. This covers image, video, carousel, and catalog campaign creation. → [Campaign creation failed](/docs/ad-platforms/meta-ads#troubleshooting) **August 22, 2026** Adding the same call asset twice no longer creates a duplicate phone number, and call assets get list, pause, and remove tools ## The Duplicate Phone Number Problem, Both Halves A customer added a call asset, couldn't tell whether it had worked, and added it again. Google stores a call asset's phone number verbatim and never deduplicates, so the campaign ended up serving two identical phone extensions — and there was no way to list what was on the campaign, no way to pause one, and no way to take one off. Both halves are fixed. **Adding is idempotent now.** `add_call_asset`, `add_business_name_asset`, and `add_search_campaign_image` check the campaign before they write, and skip when the same asset is already there — telling you it was already present rather than reporting a second success. Pass `force=true` when a genuine duplicate is what you want. **Call assets get a full lifecycle.** Three new tools: * **`list_call_assets`** — every phone number on a campaign, with its country code, status, and the asset ID the other two need. * **`set_call_asset_status`** — pause a number so it stops showing, or re-enable it, without unlinking anything. Name specific asset IDs, or omit them to change all of them. * **`remove_call_assets`** — unlink numbers from the campaign. The asset stays in your Asset Library and can be re-linked elsewhere. `list_campaign_extensions` grew to match. It used to report sitelinks, callouts, and structured snippets; it now covers call assets, business names, and images too, each with its status — so "what's actually on this campaign?" is one call rather than four. Find and clear a duplicate phone number on a Google Ads campaign. Show me every phone number on my Brand Search campaign, and remove the duplicate if there is one. → [Ad extensions and assets](/docs/ad-platforms/google-ads#ad-extensions-assets) **August 18, 2026** Competitor research stopped demanding a connected Google Ads account — Meta-only, TikTok-only and LinkedIn-only advertisers can now run it ## Competitor Research No Longer Needs A Google Ads Account `competitor_ads_research` reads public ad libraries. It never needed a connected Google Ads account to do that — but it insisted on one anyway, and stopped with **"No google\_ads account connected"** for anyone who hadn't connected Google. If you advertise on Meta only, the tool was unreachable, even when you explicitly asked for `sources=["meta"]`. It now resolves who you are instead of demanding an account you don't have. The research runs on whatever sources you name. The *Your ads* half of the comparison — your own creatives and brand terms placed beside theirs — still needs a connected account on the platform being compared. With nothing connected there you get the competitor findings and no comparison tab, instead of an error and nothing at all. Naming an account explicitly still behaves exactly as before: a wrong or ambiguous `account_id` errors and tells you which accounts to pick between. Only the requirement to have one at all is gone. Run competitor research on Meta with no Google Ads account connected. Show me the Facebook and Instagram ads figma.com is running right now. → [Competitor research](/docs/agent-skills/tools#competitor-research-1) **August 18, 2026** Meta budgets on yen, won, rupiah and eight other whole-unit currencies were being sent to Meta 100x too high — fixed on both the write and the read side ## Meta Budgets On Whole-Unit Currencies Were 100× Too High If your Meta ad account bills in Japanese yen, Korean won, Indonesian rupiah, or one of eight other currencies that have no decimal subdivision, **a budget you set through Adspirer reached Meta a hundred times larger than you asked for**. A ¥20,000 daily budget was sent as ¥2,000,000. Meta wants budgets in each currency's smallest unit, and how many of those make one unit depends on the currency: 100 for dollars, euros and most others, but **1** for the eleven currencies that have no minor unit at all. Adspirer multiplied by 100 in every case. The read side hid it. Adspirer divided by 100 to display a budget, so the number it showed you back was the one you'd asked for — correct on our screen, wrong at Meta. That is why this ran undetected. Both sides are fixed. The multiplier is now the one Meta actually specifies for your account's currency, applied once, at the last step before the request leaves — and budgets, bids, and remaining spend read back with the real conversion and the real currency symbol. A ¥20,000 budget now displays as `¥20,000`, not `$200`. > [!WARNING] > > **If your Meta ad account bills in one of these currencies, check your live budgets now** — in Adspirer or in Meta Ads Manager — and correct anything that reads 100× high. Any budget or bid set through Adspirer before August 18, 2026 is affected. This does not apply to USD, EUR, GBP, or any other currency with cents; those were always sent correctly. > > The eleven affected currencies: **CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD, VND**. Two smaller things came with it. Budget validation no longer rejects legitimate budgets on these accounts — the old fixed ceiling was effectively 100× lower for them, which turned real Japanese and Korean advertisers away. And whole-unit currencies stop rendering a meaningless `.00`: a Hungarian account reads `Ft 5,000`, not `Ft 5,000.00`. → [Meta budget guidelines](/docs/ad-platforms/meta-ads#budget-guidelines) **August 17, 2026** ChatGPT Ads campaigns can bid for conversions, budgets read in your account's own currency, location exclusions arrive, and archiving asks before it acts ## ChatGPT Ads Campaigns Can Bid For Conversions A ChatGPT Ads campaign used to optimize for clicks or impressions and nothing else. If you had conversion tracking set up, the campaign couldn't use it. `create_chatgpt_campaign` and `update_chatgpt_campaign` now take a **`bidding_type`** — `conversions` (oCPC), `clicks` (CPC), or `impressions` (CPM). On `conversions`, OpenAI optimizes toward the clicks most likely to convert and still bills you per valid click. Conversions bidding needs exactly one conversion event to aim at, named with **`conversion_event_setting_ids`**. Get one from `list_chatgpt_event_settings`, or create it with `create_chatgpt_event_setting`. Ask for conversions bidding without an event setting — or with more than one — and the agent tells you so before the request leaves, instead of relaying an opaque rejection from OpenAI. Switch a running ChatGPT Ads campaign to conversions bidding. List my ChatGPT Ads conversion event settings, then switch my Spring Launch campaign to conversions bidding against the order\_created one. → [Budgets, bidding, and targeting](/docs/ad-platforms/chatgpt-ads#budgets-bidding-and-targeting) ## Budgets In Your Own Currency, And Budget Edits That Stick Two money problems, both fixed. **Budget changes silently did nothing.** Asking to raise a ChatGPT campaign's daily budget reported success and changed no budget — the number went to OpenAI in the wrong shape and was discarded. It applies now, on daily and lifetime budgets alike, and a lifetime campaign is no longer quietly converted to a daily one. If you tried to change a ChatGPT Ads budget from chat and the campaign kept spending at the old rate, that is why. Check the campaign and set it again. **ChatGPT Ads is not a dollars-only platform.** Roughly a third of connected accounts bill in AUD, BRL, CAD, GBP, MXN, or NZD, and every budget and bid was labelled in dollars regardless. Budgets and bids are the account's own currency now — say `25` for 25 a day in whatever currency the account bills in — and create and update responses read back the budget and bidding that actually applied, rendered in that currency, so you confirm the number rather than trust it. One consequence worth knowing: OpenAI's real minimum for a daily budget is **25 a day** in the account's currency, not 1. Adspirer had been enforcing 1, so a smaller budget passed validation and then failed at OpenAI with nothing useful attached. It's caught up front now, with the account's currency in the message. → [Budgets, bidding, and targeting](/docs/ad-platforms/chatgpt-ads#budgets-bidding-and-targeting) ## Exclude A Location — And Keep The Targeting You Already Had `create_chatgpt_campaign` and `update_chatgpt_campaign` gain **`exclude_location_query`** and **`exclude_location_ids`**, so you can run nationally and skip a state, or target a metro and cut a suburb out of it. The more important half is what happens on an edit. OpenAI replaces a campaign's targeting wholesale rather than merging it, so changing one side used to erase the other — add an exclusion and the campaign quietly lost its include list and started serving everywhere. Adspirer now reads the current targeting and preserves whichever side you didn't mention. Two related guards came with it: * **A location it can't resolve is an error, not a wipe.** A misspelled place name leaves your targeting exactly as it was and says so, rather than clearing it. * **Serving everywhere is now something you ask for explicitly**, with `clear_targeting`. Empty location lists no longer mean it by accident. `update_chatgpt_campaign` also checks OpenAI's response against what you asked for and names any field OpenAI kept at its old value — so a change that didn't take never comes back reported as done. Add a location exclusion without disturbing the existing targeting. My ChatGPT Ads campaign targets California. Keep that, but exclude Los Angeles, and show me the targeting that ended up applied. → [Budgets, bidding, and targeting](/docs/ad-platforms/chatgpt-ads#budgets-bidding-and-targeting) ## Archiving A ChatGPT Campaign Asks First OpenAI has no un-archive endpoint. Archive a ChatGPT campaign, ad group, or ad and it is gone for good — but the confirmation gate that guards permanent actions only recognised tools named `delete` or `remove`, so the three `archive_chatgpt_*` tools went straight through. They now require an explicit confirmation, and the agent points you at pausing instead when pausing is what you meant. Archive tools on Google, Meta, TikTok, and LinkedIn are unaffected — archiving there is reversible, and nothing about how they behave has changed. → [Safety guardrails](/docs/ad-platforms/chatgpt-ads#safety-guardrails) **August 17, 2026** ChatGPT Ads holds more than one account, and the agent can now create your pixel, Conversions API key, and conversion events without opening Ads Manager ## More Than One ChatGPT Ads Account ChatGPT Ads authenticates with a pasted Advertiser API key rather than an OAuth login, and one key reaches exactly one advertiser account. That made it the only Adspirer platform locked to a single account — awkward for an agency, and worse for anyone running two brands. Connect a key per account and they all sit side by side. **"Connect another account"** in the [Connections](https://adspirer.ai/connections) tab adds one; each disconnects on its own, so removing a client doesn't disturb the rest. How many you keep active at once follows your plan. Nothing changes if you have a single account connected — tools still use it automatically and you never pass an ID. With two or more, name the account you mean. `list_chatgpt_accounts` shows each one with its `account_id`, name, and currency, and a request that doesn't say which account comes back with your list rather than a guess at one. See every connected ChatGPT Ads account, then scope a question to one. List my ChatGPT Ads accounts with their account IDs and currencies, then show me last week's spend for the Northwind Retail one. → [Managing several ChatGPT Ads accounts](/docs/ad-platforms/chatgpt-ads) ## Conversion Tracking You Can Set Up By Asking Measuring a ChatGPT ad used to mean leaving the conversation: open OpenAI Ads Manager, create a pixel, copy the ID back, create a Conversions API key, define your events. Five tools now do it from chat. * **`create_chatgpt_pixel`** creates the web pixel and hands back the **site snippet ready to paste** into your ``, along with the Pixel ID and the Source ID you need next. Automatic Advanced Matching — which hashes what your site forms collect so more conversions match — is on unless you ask for it off. * **`create_chatgpt_conversions_api_key`** creates a server-side key. The secret is shown once and never again, and by default it's stored encrypted so Adspirer starts sending server-side conversions straight away. * **`create_chatgpt_event_setting`** ties an event — `order_created`, `lead_created`, one of the other supported types, or a custom one — to a pixel or Conversions API source, with an attribution window. * **`list_chatgpt_pixels`** and **`list_chatgpt_event_settings`** show what already exists. One thing to know before you ask: OpenAI has no way to delete a pixel, a Conversions API key, or an event setting. They are permanent. So each create asks you to confirm first, and none of them will overwrite a pixel or key you already have unless you explicitly say to replace it. Set up ChatGPT Ads conversion tracking end to end from chat. Create a ChatGPT Ads pixel called "Main Site" and give me the snippet to paste. Then set up an order\_created conversion event against it with a 30-day window. → [ChatGPT Ads conversion tracking](/docs/ad-platforms/chatgpt-ads) **August 17, 2026** One unchangeable field no longer sinks an entire conversion action update, and Search language targeting degrades honestly ahead of Google removing it in September ## One Field Google Won't Change No Longer Sinks The Whole Update A customer asked to make a conversion action secondary and, in the same breath, to leave it out of the Conversions column — where it already was. Nothing happened. Google returned an immutable-field error, and because the update is a single atomic write, the field that *was* changeable went down with it. Only a retry that dropped the second request worked. The cause: **"counts in the Conversions column" cannot be set through the Google Ads API on an existing conversion action.** Not for GA4-imported actions, not for native ones. Google derives it from the action's category and goal setup — and for imported conversions, from Google Analytics. Adspirer had been sending it anyway. It now never goes to Google. Ask for it and: * **If the action is already set that way**, it's skipped in silence and the rest of your update applies — which is exactly the customer's case, now working. * **If it's a real change**, the rest of your update still applies and you're told to make that one change in the Google Ads UI (Goals → Conversions → the action → Edit settings) or in GA4. * **If it was the only thing you asked for**, you get that explanation rather than Google's opaque refusal. The confirmation also stopped over-reporting. It lists the fields that actually landed, not the fields you asked for. → [Conversion tracking on Google Ads](/docs/ad-platforms/google-ads) ## Search Language Targeting Ends In September, And Says So Google is removing campaign-level language targeting for Search campaigns in late September 2026. Search ads will match on the language of the ad itself. Performance Max is exempt, and reading a campaign's existing language criteria keeps working. `update_campaign` would have started failing on Search the day Google flipped it, with a context error that names nothing you could act on. It now recognises that specific rejection and explains it: Google no longer accepts language targeting on Search campaigns. A language-only update tells you it didn't apply instead of reporting success, and a mixed update applies everything else and says which part Google refused. Nothing changes before the cutover — Adspirer keys off Google's own rejection rather than a date on a calendar, so today the setting still writes exactly as it did yesterday. You don't need to do anything now; when the change lands you'll get a sentence instead of a stack trace. → [Campaign management on Google Ads](/docs/ad-platforms/google-ads) **August 16, 2026** Integration tools are listed before you connect them instead of hiding until you do, and a reused logo no longer breaks Demand Gen and YouTube campaign creation ## Integration Tools Stop Hiding Until You Connect Them Google Analytics, Search Console, Tag Manager, and Klaviyo were hidden from your AI client's tool list until you had connected them. The reasoning was to save you a dead-end call. The effect was a trap: you couldn't discover an integration existed, so you never learned there was something to connect. It cost a real customer more than a wasted call. They connected Search Console and Tag Manager, their Claude client was still holding a tool list from before those tools existed, and because the server had also been hiding them pre-connection, the agent never tried them once. From the outside it looked like the integrations were broken. Integration tools are now always listed, exactly like every ad platform. Ask for one you haven't connected and it answers with a prompt to authorize it in [Connections](https://adspirer.ai/connections) — which is the nudge that gets it connected, and a good deal more use than a tool that isn't there. → [Integration tool reference](/docs/agent-skills/tools) ## A Reused Logo No Longer Breaks Demand Gen And YouTube Campaigns `discover_existing_assets` hands back the logos already in your Google Ads account and tells the agent to reuse them as-is. `create_demandgen_campaign` and `create_youtube_campaign` then wrapped that value a second time, sending Google a malformed asset reference and getting back an `INVALID_ARGUMENT` that named nothing useful. Five accounts hit it across both tools over the last 90 days. Both tools now recognize an asset reference that's already complete and pass it through untouched. Reusing a logo the agent just discovered works, and so does supplying a bare asset ID — the path that happened to work before is unchanged. If a Demand Gen or YouTube campaign refused to create for you with an invalid-argument error after picking up an existing logo, try it again. → [YouTube campaigns](/docs/ad-platforms/youtube-ads) **August 16, 2026** Competitor research reaches Meta, TikTok and LinkedIn, a stricter advertiser match so you never get a stranger's ads, Google Tag Manager becomes connectable, and integrations hold more than one account ## Competitor Research Now Covers Meta, TikTok, And LinkedIn `competitor_ads_research` read Google's ad library — Search, Display, and YouTube. For a competitor whose real budget sits on Instagram or TikTok, that was a report about the smallest part of what they run. Three more ad libraries are now behind the same tool. Ask for a competitor's **Facebook and Instagram** ads, their **TikTok** ads, their **LinkedIn** ads, or any combination, and they come back in the same gallery — creatives, headlines, offers, formats, and how long each has been running, every one read with vision analysis. Google is still the default. You add the rest by naming them, and each one is another set of lookups, so ask for the platforms your competitor actually advertises on rather than all four out of habit. Two details worth knowing: * **Meta carousel ads arrive whole.** A multi-card ad used to show its first image and drop the rest. It now renders as a swipeable strip with all its cards, labelled for what it is. * **`region` doesn't apply everywhere.** Google and Meta ad libraries filter by market. TikTok's and LinkedIn's are worldwide and can't be narrowed — so those results are labelled worldwide rather than passed off as your market. Compare a competitor's social ads against their search ads. Show me what notion.so is running on Meta, TikTok, and LinkedIn right now, alongside their Google ads, and tell me which platform gets their best creative. → [Tool catalog](/docs/agent-skills/tools) ## The Right Advertiser, Or Nothing At All A live account asked about `get-ryze.ai` and got back ads from a haircare brand and a GP-booking service. Two strangers, presented as their competitors. The domain had been matched loosely by name, and nothing checked whether the advertiser it landed on was actually the company you asked about. Matching is now strict everywhere. A domain resolves to one advertiser and is confirmed against the links inside that advertiser's own ads where the platform exposes them — a check that rejects lookalike domains rather than accepting anything that merely contains your competitor's name. When a match can't be confirmed, you get an honest empty result instead of somebody else's creatives. Where a platform gives no website to verify against — TikTok and LinkedIn identify advertisers by name only — the result says so, so you can judge the match yourself. Two smaller honesty fixes shipped with it. An empty TikTok or LinkedIn result now reads "no ads found on TikTok (worldwide)" rather than "none in this market", which was a claim about where a competitor advertises that Adspirer had no basis for. And one bad domain in a list no longer kills the whole report — the rest run, and the ones that couldn't be read are named. → [Tool catalog](/docs/agent-skills/tools) ## Competitor Video Opens Where It Actually Plays Yesterday's release played competitor video inside the card. In Claude that turned out to render a blank white frame that never played — the sandbox around the card blocks an embedded player, and no setting on our side changes that. So the video no longer pretends to play in place. You get the poster frame with a **Watch on YouTube / Meta / TikTok / LinkedIn ↗** link, and clicking it opens the ad on the platform it runs on, in a new tab. The frame is still read with vision analysis exactly as before, so the written analysis of the video is unchanged. The Summary tab also stopped growing without limit — a long analysis scrolls inside the card now instead of stretching it down the page. And the **Your ads** tab no longer appears when there is nothing to put in it; it used to tell customers who were already connected to "connect an ad account". → [Tool catalog](/docs/agent-skills/tools) ## Google Tag Manager Joins Your Connections "Is my Meta pixel actually installed?" and "why isn't this conversion firing?" were questions your agent could see the symptoms of and not the cause. **Google Tag Manager** is now a connectable integration, alongside Google Analytics, Search Console, and Klaviyo. Connect it at [adspirer.ai/connections](https://adspirer.ai/connections) and the agent can read the tags and variables in your containers — which conversion pixels, analytics, and remarketing tags are on your site, and how each is configured. It can also create or update a tag or a variable. That writes to a live container firing tracking on your real website, where a wrong edit breaks conversion tracking everywhere at once, so the agent confirms the exact change with you first and leans on the read actions for diagnosis. Check whether your conversion tracking is really installed. List the tags in my Google Tag Manager container and tell me whether my Meta pixel and Google Ads conversion tag are both there and firing on the right pages. → [Integration tool reference](/docs/agent-skills/tools) ## One Integration, More Than One Account An integration held exactly one account. One GA4 login, one Search Console user, one Klaviyo. Agencies with a client's analytics and their own, or anyone whose properties sit under two logins, had to disconnect and reconnect to switch. Every integration now holds several accounts at once, the same way ad accounts already work — all equal, no primary. Add one with **Connect another account** on that integration's card in [Connections](https://adspirer.ai/connections), and each account gets its own row you can disconnect on its own. How many you can connect follows your plan's account limit. When an integration has more than one account, tell the agent which one you mean and it uses that; ask and it lists what it can see. With a single account nothing changes — you say nothing and it resolves as it always did. → [Integration tool reference](/docs/agent-skills/tools) **August 15, 2026** Competitor video ads are read instead of skipped, and the competitor card becomes three tabs instead of one long scroll ## Competitor Video Ads Are Read, Not Skipped A large share of what advertisers run is video, and `competitor_ads_research` was stepping straight past all of it. A competitor's video ad came back as nothing at all. Now each video ad's poster frame is pulled from the ad-transparency listing and read with the same vision analysis an image ad gets. The video shows up in the gallery with its headline, offer, format, and run duration alongside everything else. Click the frame and the ad plays inline in the card; close it and you're back in the gallery exactly where you left off. One frame is described as one frame. Adspirer reads what that frame shows and doesn't narrate the rest of a video it hasn't watched. ## The Competitor Card Splits Into Three Tabs The card stacked the written analysis, the competitor gallery, and your own ads into one continuous scroll — and the analysis arrived with its formatting showing as raw characters, literal `##` and `**` sitting in the middle of sentences. Both are fixed. The analysis renders as formatted text with real headings and emphasis, and the card is now three tabs — **Summary**, **Ads**, and **Your ads** — so you can read the takeaway first and then go look at the creatives behind it. → [Tool catalog](/docs/agent-skills/tools) **August 14, 2026** See a competitor's live ads next to your own — real creatives, offers, and how long each one has been running ## `competitor_ads_research` — Their Live Ads, Next To Yours Ask what a competitor is advertising and you now get their actual ads back: creatives, headlines, offers, calls to action, formats, and how long each one has been running. They come from public ad-transparency sources, and every creative is read with a vision model so the copy and the offer are extracted rather than left as an image you squint at. The second half is the part an ad-spy tool can't reach. Your own connected accounts land in the same answer — the ads you're running, and any competitor brand terms you're already paying for. **You supply the domains.** `competitor_domains` takes websites, not brand names — `semrush.com`, not "Semrush". A bare brand name returns nothing, so if you name a company without a website the agent asks for one instead of guessing. It never invents a competitor list for you either. `region` takes an ISO country code and defaults to your own account's market. Running more than one ad account? Pass `account_id` (or `customer_id` — same field) to scope the your-ads half of the comparison to one of them. Leave it off and the comparison covers every connected account and tells you so. > [!WARNING] > > It does not return competitor spend, ROAS, conversions, CPC, or impressions. No source publishes those, so Adspirer never estimates them. A creative that has been running for 1,200 days has been running for 1,200 days — that's a duration, not proof it works. In ChatGPT and Claude the result renders as an interactive card with a scrollable creative gallery; every other client gets the same findings as text. Available on Pro and Max. Put two competitors' live ads next to your own account. Show me what semrush.com and ahrefs.com are running as ads right now, and put it next to what my own account is running. → [Tool catalog](/docs/agent-skills/tools) **August 13, 2026** Connect Google Search Console and put your organic search performance next to what you pay for it ## Google Search Console Joins Your Connections Your agent could see what you pay for in Google Ads and what happens on the site afterwards in GA4. The half in between — what you rank for without paying — wasn't there. **Google Search Console** is now a connectable integration, alongside Google Analytics and Klaviyo. Connect it at [adspirer.ai/connections](https://adspirer.ai/connections) and the agent can read organic-search performance for any site you've verified: clicks, impressions, CTR, and average position, broken down by query, page, country, device, or date. The useful part is the comparison. Paid and organic search results for the same query now sit in one conversation, so "which of my top Google Ads keywords do I already rank for organically" is a question your agent can actually answer. It can also ask Google to re-crawl a page after you publish or update one. That one's a write, so the agent confirms the exact URL with you first. Find paid keywords you're already winning organically. Pull my top 25 Search Console queries by clicks for the last 28 days, then check which of them I'm also bidding on in Google Ads and what those cost me. → [Integration tool reference](/docs/agent-skills/tools) **August 13, 2026** Target Impression Share bidding arrives, a strategy switch that used to report success without changing anything is fixed, and conversion actions become editable ## Bid For The Top Of The Page: Target Impression Share Impression-share bidding meant a trip to the Google Ads interface. `update_bid_strategy` now accepts **`TARGET_IMPRESSION_SHARE`** alongside Target CPA, Target ROAS, Maximize Clicks, and Maximize Conversions. You set two things: where you want to appear — **absolute top of page**, **top of page**, or **anywhere on the page** — and the share of auctions you want to win there, 1 to 100. Send a **max CPC ceiling** too. Without one, a target of 90% at the absolute top will chase that number as far as your budget allows. The ceiling is a plain amount in the ad account's own currency, so a €4 ceiling is `4` — not 400, and not converted to dollars. Switch a brand campaign to impression-share bidding with a bid ceiling. On my brand Search campaign, switch bidding to target impression share — 80% at the absolute top of the page, with a max CPC ceiling of \$4. → [Google Ads integration](/docs/ad-platforms/google-ads) ## A Bidding Switch That Said "Done" And Changed Nothing This one affected **every** bid strategy change, not only the new one. Moving a campaign from one strategy to another — Maximize Clicks to Maximize Conversions, say — could come back reporting success while Google quietly kept the old strategy. The response said the change landed. The campaign carried on bidding exactly as before, and nothing in the reply gave you a reason to check. That's fixed. And because a false success is the hardest kind of failure to notice, `update_bid_strategy` now **reads the strategy back from Google after writing it** and returns an honest error when the campaign isn't on the strategy you asked for. A change Google declines can no longer be reported as a change that worked. > [!NOTE] > > If you switched a Google Ads bid strategy through Adspirer before August 13 and the performance never moved the way a strategy change should, check what the campaign is actually bidding on now. It may never have switched. → [Google Ads integration](/docs/ad-platforms/google-ads) ## Edit A Conversion Action Instead Of Rebuilding It Changing anything about a live conversion action — its name, its default value, how long its click window runs — meant doing it in the Google Ads interface, because Adspirer could only read conversion actions or create new ones. **`update_conversion_action`** edits one in place. Pass the conversion action ID plus whatever you want changed: name, category, status, value and currency, counting type, click-through and view-through lookback windows, whether it counts in the Conversions column, whether it's primary for its goal, or its attribution model. Only the fields you pass change. Everything else stays as it is, and the tool never removes a conversion action — to stop one counting, set `status` to `PAUSED`, which you can undo. Value changes are handled carefully on purpose: a conversion's value, currency, and always-use-default setting move as a set, and if Adspirer can't read the action's current settings first, the update fails rather than guessing. Smart Bidding reads those numbers, so a value silently rewritten to zero is worse than an update that didn't happen. Widen a conversion action's click window without touching anything else. List my Google Ads conversion actions, then change the click-through lookback window on the Purchase one to 60 days. Leave everything else as it is. → [Google Ads integration](/docs/ad-platforms/google-ads) **August 12, 2026** Pause hundreds of keywords in one call, Meta updates that show you the value they applied, an audit that stops passing agency accounts it never read, and an Expert Kit that installs an agent instead of overwriting yours ## `bulk_update_keyword_status` — Pause 300 Keywords In One Call Pausing a list of keywords meant one `update_keyword` call per keyword. The only bulk option was `remove_keywords`, which **permanently deletes** — so the fast path and the safe path were different paths. **`bulk_update_keyword_status`** sets status on up to **300 keywords in one ad group** in a single call, in both directions: `PAUSED` or `ENABLED`. It's fully reversible, and re-running it on a keyword already in the target status does nothing, so a retry is safe. You pass explicit keyword IDs. There is deliberately no "pause everything" mode — that's how a whole ad group gets switched off by accident. The delete-confirmation gate now points bulk-pause requests here instead of at `remove_keywords`. Pause a batch of underperforming keywords without deleting them. Find keywords in my Search campaign that spent more than \$50 last month with zero conversions, then pause all of them in one go. Don't delete anything. → [Google Ads integration](/docs/ad-platforms/google-ads) ## Meta Updates Now Show You The Value They Applied A successful Meta update replied with field *names* only — "Updated Fields: `daily_budget`". Not the value. So a budget that landed wrong was invisible in the response, and neither you nor your assistant had anything to catch it against. Every Meta update tool now echoes each field **with the value that was applied**, money rendered in the ad account's own currency — an Australian account reads `A$2,000.00`, not a dollar sign bolted onto the number. That covers campaign, ad set, ad, and the three catalog update tools. Each response ends by asking you to check the values before moving on, because they are live at that point. Catalog updates used to be the worst case: editing only a product set, pixel, or retargeting audience could report an **empty** change list on a successful write. Those fields now come back under readable names. → [Meta Ads integration](/docs/ad-platforms/meta-ads) ## The Conversion Audit Was Passing Accounts It Had Never Read If you manage Google Ads through a manager (MCC) account, `audit_conversion_tracking` was sending the wrong manager account on every request. Google refused it, the Google checks abstained, and the audit still printed a **Grade A** — a clean bill of health on an account it had not actually examined. Around **547 manager-managed accounts** were affected. Shared agency accounts had a second version of the same problem. Performance rows are stored under whichever teammate's login collected them, and the audit only counted rows belonging to *you* — so a colleague auditing a shared account saw zero conversion volume and got a "0/0 stable" **pass**. LinkedIn audits returned that same false pass for every account, from a platform-name mismatch. Both are fixed, and the report is honest about the difference between *checked and healthy* and *couldn't check*: when a critical check can't run, the header now reads **Incomplete** rather than showing a grade. `diagnose_funnel` no longer reports that "tracking checks out" on the back of an incomplete audit. > [!WARNING] > > If you run Google Ads under a manager account or share an account with teammates, re-run your conversion tracking audit. A previous Grade A may have been an audit that never reached your account. → [Multi-client agency setup](/docs/knowledge-base/multi-client) ## The Expert Kit Ships An Agent Instead Of Overwriting Yours The Prompt Engineering Playbook used to tell you to copy its `AGENTS.md` to your project root. That is a single well-known filename — so the step **replaced whatever was already there** with "work only on Google Ads account NNN", and a coding agent that had been useful for your own work stopped being useful for anything else. That step is gone, and it was never necessary. Every one of these clients has a first-class slot for exactly what an Expert Kit is, so the kit now generates **the agent definition itself** — `.claude/agents/`, `.cursor/agents/`, `.agents/agents/` as markdown, Codex as TOML. Your account instructions become that agent's system prompt, the file points at the skill, and on Claude Code, Codex and Antigravity it declares `mcp.adspirer.com` too, so there's no connector left to wire up. A uniquely-named new file can't clobber anything, and uninstalling is deleting it. Skills now install at **project scope**, never the `~/` home paths — those loaded one account's ads agent into every unrelated repo on your machine. Setup is now per client, and every claim was re-checked against that vendor's own documentation: * **Claude** — five steps: create the project, upload the skill, paste the agent instructions into the project instructions, add the prompt book to project knowledge, connect. Skills are on **every plan, including Free** (we had said paid-only), the upload control is **Add** rather than "+ Create skill", and Team and Enterprise do this under **Organization settings**. Teams can upload once for the whole org instead of once per seat. * **ChatGPT** — instructions and files, in a project. ChatGPT chat can't install a standalone skill; OpenAI scopes those to Codex, including Codex running inside the desktop app. * **OpenClaw** — its own steps. It's a workspace-scoped gateway, not a project-based IDE. * **Windsurf** — removed from the kit. Cognition renamed it Devin Desktop, it isn't on the Agent Skills client list, and nothing documents the desktop app loading a local skill. This does not affect using Windsurf as an MCP client — [that setup](/docs/ai-clients/windsurf) is unchanged. The prompt book changed shape too: each entry was a one-line prompt, and is now a short operating brief — the goal, what to look at, the guardrails, and how to report. → [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) **August 11, 2026** TikTok Instant Form lead generation, Meta errors that name the failure, and a budget unit that told you to send 100x ## TikTok Lead Generation Campaigns Can Be Built At All Now Lead generation with a TikTok Instant Form was structurally impossible here — not because of one bug, but because the `page_id` that attaches a form to an ad was dropped at six independent points between your request and TikTok. Each one was fatal on its own. All six are fixed. **`list_tiktok_lead_pages`** lists the Instant Forms on your advertiser with the `page_id` each one needs, and says whether the form is `PUBLISHED` — TikTok won't let a draft be attached to an ad. **Start here, though: an Instant Form is the minority path.** Most live lead-gen campaigns capture leads on your own site instead, with a pixel on the ad group and `optimization_event=FORM`. Run `list_tiktok_pixels` for that route. Use an Instant Form when you specifically want the form hosted inside TikTok. Three ad group settings that TikTok requires for lead gen — and which it reported only as the useless *"There was an error with the Lead Generation advertising objective"* — are now set for you: * The ad group is promoted as lead generation, not as a website visit * A custom bid is set, because TikTok refuses its own no-bid strategy on this objective * Placements are named explicitly, because automatic placement is rejected A form ad also can't carry a landing page URL — the TikTok-hosted form *is* the destination, and TikTok rejects an ad holding both. `add_tiktok_ad` had been sending both; it now carries exactly one destination, matching campaign creation. Launch a TikTok lead generation campaign on an Instant Form. What TikTok Instant Forms do I have, and which are published? Then build a lead generation campaign on the published one, \$40/day, targeting the US. → [TikTok Ads integration](/docs/ad-platforms/tiktok-ads) ## Meta Failures Now Hand You The Identifiers Meta Sent A customer spent three days isolating a Meta ad set publish failure — twelve controlled tests, then rebuilding the campaign by hand in Ads Manager to compare — and finally asked us for the error code, subcode and `fbtrace_id`. Adspirer had all three on every one of his failures and printed none of them. Across the previous 30 days, **2% of Meta errors reached a customer carrying an `fbtrace_id`**. Without those, there is nothing to act on and nothing to quote to Meta support. They now trail the error as their own reference line, so a failure that Meta sends without identifiers reads exactly as it did before. Two routes — including `add_ad_set`, the customer's failing call — had hand-rolled their own error handling and were the last Meta write paths still discarding the identifiers. All 32 Meta write paths behave identically now. When Meta sends a title and an explanatory sentence but no user-facing message, you get the sentence too, rather than a bare title. → [Meta Ads troubleshooting](/docs/ad-platforms/meta-ads#troubleshooting) ## Meta Budget Fields Said "Cents". They Were Never Cents. Every caller-facing description on a Meta money field — budgets, bids, spend caps, spend targets — told your assistant to send cents, or to convert to USD. The tools have always taken the value in **the ad account's own currency**, and converted internally. An assistant that followed the description literally sent `2000` for a 20/day budget, and Adspirer converted it again. That is a **100x budget**, on `update_meta_campaign` and `update_meta_ad_set` above all. Every Meta money-field description is now uniform: the ad account's own currency, as a decimal. For 20/day, send `20`. No conversion arithmetic changed — the tools behaved correctly the whole time, and only the instructions were wrong. The project-setup skill, which had been stamping "Meta = CENTS" into generated brand context, is corrected too. > [!WARNING] > > If you set a Meta budget or bid through Adspirer before August 11, 2026, check the value that actually landed on the campaign. An assistant that followed the old wording would have set it 100x too high. → [Meta budget guidelines](/docs/ad-platforms/meta-ads#budget-guidelines) **August 9, 2026** TikTok campaign creation actually works — pixel and video discovery, and two tools that never once succeeded are gone ## Two TikTok Tools That Had Never Worked Are Gone `create_tiktok_campaign` succeeded **zero times in 176 attempts** across 33 customers over the past year. `create_tiktok_carousel_card` never worked either. Neither was fixable: TikTok's in-feed placement requires a video creative, so a single-image in-feed campaign is rejected on principle, and the carousel tool was built against an endpoint that doesn't accept the value it was sending. Both are removed. Asking for them now returns a clean "unknown tool" with a pointer to what to use instead, rather than a campaign that half-builds and then fails. **`create_tiktok_video_campaign` is the creation tool**, and it now honours all three creative sources its schema has advertised since April: * **`video_url`** — a public MP4/MOV that Adspirer uploads for you * **`video_id`** — a video already in your TikTok library, reused without re-uploading * **`tiktok_item_id`** — an organic post boosted as a Spark Ad The two ID-based paths were dropped at four separate layers and always failed with *"Video asset (URL or data) is required"* — after creating a partial campaign. They work end to end now. `add_tiktok_ad` with an existing `video_id` used to fail with *"You must upload an image"*, because TikTok wants a cover alongside the video; Adspirer derives the cover itself. ## Find Your Pixel Instead Of Guessing At It Conversion campaigns were TikTok's largest failure cluster — **124 attempts, 27 customers, one success**. You had no way to discover a pixel or the events it accepts, so both got guessed at. **`list_tiktok_pixels`** returns each pixel on the advertiser with the **numeric `pixel_id`** TikTok requires — not the alphanumeric Pixel Code, which TikTok rejects — and the exact `optimization_event` values that pixel supports. Pixels with no events configured are flagged as unusable for conversion optimization rather than handed back as if they'd work. Adspirer no longer defaults `optimization_event` to `COMPLETE_PAYMENT`. The valid set is per-pixel, so a fixed guess is simply wrong for anyone whose pixel doesn't carry that event. Ask for a conversion campaign without one and you're told to run `list_tiktok_pixels` for the real list. ## A Conversion Campaign That Was Quietly Built As Something Else `WEB_CONVERSIONS` was missing from all three creation paths, so it fell through to each one's default. A campaign you asked to optimize for conversions was built as **video views** or **traffic** — and it still spent, with your purchase pixel attached to an ad group optimizing for something else entirely. If your TikTok conversion campaigns have been underperforming without an obvious reason, this is worth a look at what actually got built. `WEB_CONVERSIONS` maps correctly now in all three. ## `list_tiktok_ad_videos` — Reuse A Video You Already Uploaded Lists your advertiser's video library with the `video_id` for each, so a second ad from the same video doesn't mean a second upload. `discover_tiktok_assets` used to claim TikTok's API "does not support listing or searching existing assets," which was never true; it covers your image library and now points at the video tool for videos. Pixel and video lookups also raise a real error when TikTok's API fails. A timeout or a permission denial used to render as a confident "no pixels on this advertiser," with instructions to create one you may already have had. ## What TikTok Genuinely Doesn't Allow, Said Plainly * **Image-only in-feed ads are rejected by TikTok**, not by Adspirer. Images are supporting assets alongside a video creative — `upload_tiktok_images` and `discover_tiktok_assets` feed `image_ids` into a video ad. * **Carousel ads can't be built through the API.** Build the carousel in TikTok Ads Manager, then boost that post here as a Spark Ad with its `tiktok_item_id`. Set up a TikTok conversion campaign with the right pixel and event. Which TikTok pixels do I have, and what conversion events does each one support? Then set up a conversions campaign on the one that tracks purchases, \$50/day, using a video I've already uploaded. → [TikTok Ads integration](/docs/ad-platforms/tiktok-ads) **August 8, 2026** Google App campaigns become readable — promoted app, bidding goal, real target CPA, and install counts that aren't zero ## Your App Campaign Read Back As A Blank "MULTI\_CHANNEL" Google files App campaigns under the channel type `MULTI_CHANNEL`, and that was all `list_campaigns` and `get_campaign_structure` told you. No app, no store, no bidding goal — nothing identifying *which* app the campaign promotes or what Google optimizes toward. If you run a portfolio of apps, that's the first thing you need before touching a budget or a bid. Campaign reads now name it: * **The sub-type** — an App campaign says it's an App campaign instead of hiding behind `MULTI_CHANNEL`. * **The promoted app and its store** — the Play package name or App Store ID Google holds, and which store it points at. * **The App bidding goal** — install volume, installs at a target cost, in-app conversions, return on ad spend, or pre-registration volume. What Google is actually optimizing toward. These appear in the normal readback, not behind `raw_data`. Search, Shopping, PMax and every other campaign type read back exactly as before. ## A Live Target CPA That Reported As No Target At All Google stores a target CPA or ROAS in one of two shapes: as a standalone **Target CPA** / **Target ROAS** strategy, or as a target sitting on top of **Maximize Conversions** / **Maximize Conversion Value**. Adspirer only read the second shape. A campaign running a standalone \$2.00 Target CPA came back with no target at all — so asking "what is this campaign bidding to?" got you silence about a campaign that was very much bidding to a number. Both shapes are read now, and the readback says which one you have. A bare **Target CPA** is a standalone strategy; **Target CPA (target on Maximize Conversions)** is a ceiling on a maximize strategy. They behave differently, and the difference is worth knowing before you move one. ## `update_bid_strategy` Stops Handing You Google's Opaque Rejection On an App campaign the bidding strategy is paired with the App bidding goal, and Google refuses a mismatched pair with *"bidding strategy is incompatible with the goal type"* — which tells you nothing about which half to change. Campaign creation already enforced the pairing. Updates didn't know App campaigns existed, so the two disagreed. The check now runs before the call reaches Google. If the strategy you asked for doesn't fit the campaign's goal, you get the goal, the strategy that goal requires, and both ways forward: change the goal in Google Ads (which resets the campaign's learning — your decision, not something Adspirer does behind a bid change), or use the strategy that matches the goal you have. Non-App campaigns are untouched, and a goal Adspirer can't identify goes to Google rather than being blocked on a guess. ## Installs And Cost Per Install Were Zero On Every Google App Campaign Adspirer wasn't collecting Google's app-install metric at all, so `installs` read `0` on every Google app campaign while Google reported six figures of installs over the same window for a single account. Installs, cost per install, and post-install conversions are collected now. Two things worth knowing. **Cost per install is reported only when there are installs** — no installs means no CPI, rather than a number with nothing behind it. And **periods already collected stay at zero until they're re-collected**, so a June app campaign still looks flat when you look back at it. Read an App campaign back before you touch its bids. Show me the structure of my Google App campaign — which app it promotes, what it's optimizing for, and what it's bidding to. → [Google Ads integration](/docs/ad-platforms/google-ads) **August 8, 2026** A Google budget change that fails now says so, instead of reporting success ## "Campaign Updated Successfully" Now Means The Budget Actually Changed When you asked Adspirer to change a campaign's daily budget and Google rejected the change, `update_campaign` came back with **"Campaign updated successfully"** anyway. The failure was logged somewhere you couldn't see it. If you were moving budget through an agent — lifting the cap on a winner, cutting one on a loser — you got a confirmation for a spend cap that had not moved. Budget updates now report what actually happened: * **The budget was the only thing you asked to change, and it failed.** You get a failure that says plainly that nothing on the campaign changed, with Google's own reason attached. * **Other changes landed but the budget didn't.** You get a failure that names exactly which changes *did* apply and don't need re-running, so your retry is the budget alone rather than the whole call. * **Adspirer couldn't find the campaign's budget at all.** This used to be indistinguishable from success. It now says so, and names the likely causes — the campaign doesn't exist, it was removed, or the account doesn't grant access to its budget. * **A budget change that works names the new amount** in the list of applied changes, instead of asserting success in general terms. This applies to every Google campaign type, not just one. Pausing, resuming and deleting a campaign never touch the budget, so they behave exactly as before. The same honesty now holds one layer up: when your AI client reports a campaign update, it reads the result's own success flag rather than assuming the request went through. An update that didn't happen can't be passed back to you as one that did. → [Google Ads integration](/docs/ad-platforms/google-ads) **August 7, 2026** Meta app campaigns stop failing, video completion metrics stop reading zero, and Google errors name the actual problem ## Meta App Campaigns Stop Bouncing Off "Mobile Targeting Mismatch" App-promotion ad sets were the single largest cluster of Meta campaign-creation failures. Meta rejected them with *"The app you're trying to create an ad for is on a different operating system than targeting settings for this ad set"* — because the campaign named an app without constraining the targeting to that app's OS. Adspirer now reads the OS off your app's store URL and sets it for you. An App Store link targets iOS, a Google Play link targets Android, and either way the ad set is constrained to mobile — an app install can't be fulfilled on a desktop. This applies wherever an app ad set gets built: image, video, and carousel campaigns, `add_meta_ad_set`, and `update_meta_ad_set` when you repoint an existing ad set at an app on the other platform. You can override it with `user_os` if you need to. If that override contradicts the store URL, Adspirer stops and says so instead of forwarding Meta the exact pair it rejects. **`list_meta_promotable_apps` finds your app instead of you guessing at it.** App campaigns need the numeric *Facebook* App ID — not an iOS bundle ID, not an Android package name — and customers were guessing (a literal `YOUR_FACEBOOK_APP_ID` reached Meta in production). The new tool lists the apps your ad account can promote, each with its App ID and the store URLs Meta already holds, so both fields get filled without leaving the conversation. Apps with no mobile store listing come back separately with the reason, rather than quietly missing. Launch a Meta app-install campaign without hunting for IDs. Which mobile apps can I promote on Meta? Then set up an app install campaign for the iOS one at \$30/day. ## Your Meta Video Completion Rates Were Zero. They Were Never Zero. Video view-through and completion metrics — 25%, 50%, 75%, and 100% watched — were being recorded as `0` for every account. Adspirer was looking for the completion percentage in the wrong part of Meta's response, so real numbers were read as nothing: one delivering account had **103,316 quarter-views and 13,823 completions** all stored as zero. Anything built on them — Meta video analysis, creative comparisons — inherited the zeros. Newly collected data is correct. **Periods already collected before this fix stay at zero until they are re-collected**, so a video campaign you ran in July will still look flat when you look back at it. ## Advantage+ State And Bid Strategy, Readable And Editable From Chat **Campaign reads now include `advantage_state_info` and `bid_strategy`** — so you can ask whether Advantage+ is actually on for a campaign and what it's bidding toward, instead of opening Ads Manager to check. Meta retired the old Advantage+ App Campaign API object in May; this is the readback surface for the model that replaced it. **Campaign-level bid strategy is editable.** `update_meta_campaign` used to refuse and tell you to go adjust it in Meta Ads Manager. It now accepts `LOWEST_COST_WITHOUT_CAP`, `LOWEST_COST_WITH_BID_CAP`, `COST_CAP`, and `LOWEST_COST_WITH_MIN_ROAS`. The capped strategies need a bid cap on the ad sets first (`bid_amount` via `update_meta_ad_set`) or Meta rejects the change. ## Google Errors That Name The Actual Problem **Broad-match-only Search campaigns.** If a campaign runs broad match only (AI Max), Google rejects exact and phrase keywords with an error code newer than the client library can name — so the only thing that surfaced was the placeholder *"The error code is not in this version."* Neither you nor your AI client could tell what to fix. Adspirer now reads the campaign's real match-type setting before saying anything, then explains that this campaign takes broad match only. Exact and phrase keywords on normal campaigns are unaffected. **Retail PMax asset groups build in the right order.** Google validates an asset group at the end of each batch of asset links, so interleaving asset creation with asset linking could start validation before the required assets existed — and the campaign failed on assets you had actually supplied. Every asset is now created before anything is linked. → [Meta Ads integration](/docs/ad-platforms/meta-ads) · [Google Ads integration](/docs/ad-platforms/google-ads) **August 6, 2026** Meta summary numbers now say when they don't apply, and the conversion audit scopes to one account ## A 0.00x ROAS On A Traffic Account Is Not A Failing Account If your Meta campaigns run traffic, awareness, engagement or link-click objectives, Meta reports no revenue against them — ROAS is `0` by design. `get_meta_campaign_performance` handed your AI client that bare `0.00x` with nothing attached, and clients read it as an account in trouble. Every summary number now carries whether it applies to *your* account's objectives: * **The ROAS row reads "Not applicable"** instead of `0.00x`, with a sentence underneath naming the objectives behind it — "traffic and engagement campaigns, measured by CPC. ROAS is not a meaningful measure here." * **Your account's actual primary KPI is named** — cost per conversion, cost per install, CPC, CPM, cost per video view, whichever your objectives call for — so the agent leads with the number that matters instead of the first one in the table. * **Lead-gen, messaging and app accounts are described correctly.** They expect conversions that carry no revenue, so they're measured on cost per conversion or cost per install — not reported as broken tracking. * Accounts whose objectives Meta never recorded are told exactly that, rather than assumed to be traffic accounts. No number changed. The same flags reach the in-chat dashboard tile, so the widget and the text can't contradict each other, and they survive raw-data responses — whether a metric applies is a fact about the number, not advice. ## No More "Scale This Segment" On A Segment You Can't Target `analyze_meta_audiences` used to close with "Best performing segment: X with Nx ROAS. Consider increasing budget allocation" every time. Three fixes: * **It names the metric the ranking actually used.** On an account with no conversion value the segments are ranked by CTR, so the message now says CTR ranks engagement rather than quoting a ROAS figure that means nothing there. * **Meta's `Unknown` demographic bucket no longer wins.** That bucket holds people Meta couldn't resolve, so its spend and its attributed value describe different populations and the ratio is fiction — one account showed 623x while every resolvable segment sat at 1.3–2.2x. It is out of the ranking and stays in the age and gender breakdowns as a measured fact. You couldn't target it anyway. * **"Scale" has to be earned.** A top-ranked segment without the volume to back the claim now gets a plain statement of what was measured, instead of an instruction to move budget onto the segment we know least about. ## Audit One Account, Not All Of Them `audit_conversion_tracking` takes an optional `account_id` (`customer_id` works too, for Google Ads). Without it the audit sweeps every active account on the platform — a lot of live API calls if you run several — and agents used to narrow it by switching your active accounts, changing state you never asked to change. Scope the conversion audit to a single account. Audit conversion tracking for just my main Google Ads account, not all of them → [Meta Ads integration](/docs/ad-platforms/meta-ads) · [Tool catalog](/docs/agent-skills/tools) **August 6, 2026** One flat Expert Kit that installs cleanly in every AI client ## One Zip, One Folder — The Expert Kit Installs Where You Point It We audited the [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) kit against the Agent Skills spec and against every client's own documentation. The skill itself was conformant. The packaging and the setup steps were not. **One download, one folder, flat inside.** The kit is now a single root folder — `SKILL.md`, `AGENTS.md`, `PROMPTBOOK.md`, `README.md`, and `references/` — which is exactly the shape Claude's uploader documents *and* exactly what the filesystem clients want copied into a skills directory. One download now serves every client. Only `references/` still nests, because that is the spec's progressive-disclosure mechanism: the dossier loads on demand instead of burning context on every activation. **One instructions file.** `AGENT_INSTRUCTIONS.md` is gone — it was a third copy of text already in `AGENTS.md` and already behind the kit page's **Copy instructions** button. Kits you downloaded before this change keep working exactly as they did. **A README that says where each piece goes**, per client, so the folder explains itself even if you unzip before reading anything. **Setup steps that name the actual path.** The wizard now gives Claude's real route — Customize → Skills → **+ Create skill**, with code execution turned on first — and the literal install directory for coding agents: `~/.claude/skills/` for **Claude Code**, `.agents/skills/` for **Codex**, **Cursor**, **OpenClaw**, and **Antigravity**, instead of "check its docs". It also tells you to copy `AGENTS.md` up to your project root, which is the only place agents actually read it. **ChatGPT** and **Windsurf** now route down the paste path, which is the one that works on those clients today. **The prompt book is now visible to your agent — as a menu, not a script.** It can open `PROMPTBOOK.md` to suggest a sensible next step, or to find the right approach for something you asked for, and then run just that one. It is explicitly told never to work through the book in bulk or in order, because every prompt in it spends real tool calls. You can also download the prompt book on its own as a `.md`. Also: an account with nothing to show yet — brand new, or simply quiet — now builds its honest no-recent-activity kit instead of failing. → [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) **August 5, 2026** Prompt Engineering Playbook — an agent trained on your own ad account ## A Playbook Generated From Your Own Ad Account The **[Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook)** reads one of your ad accounts — its campaigns, spend history, and current state — and generates a set of agent files you download and install in your AI client: * **`SKILL.md`** — an operating doctrine scoped to that one account, in the open [Agent Skills](https://agentskills.io) format * **`references/account-profile.md`** — a written dossier: what state the account is in, what to prioritize, what cadence to work on * **`PROMPTBOOK.md`** — starting prompts written against your real campaigns and currency * **`AGENT_INSTRUCTIONS.md`** / **`AGENTS.md`** — paste-ready instructions for Claude and ChatGPT Projects, and the [agents.md](https://agents.md/) file that folder-based clients read automatically This sits on top of the [13 free Agent Skills](/docs/agent-skills/skills), which every plan already gets. Those teach advertising in general; the playbook is your specific account, written down. **\$39 one time, per ad account — not a subscription.** Nothing recurs, and the files are yours to keep. Annual plans include one free. Rebuilding against fresh account data is free and unlimited. → [Pricing](/docs/knowledge-base/pricing#add-ons-one-time-purchases) **July 7, 2026** Delete-confirmation safety gate ## A Hard Gate So "Pause" Never Means "Delete" Adspirer now hard-gates every destructive tool. `remove_*` and `delete_*` tools carry a `destructiveHint` and **won't run unless the call explicitly passes `confirm_delete: true`**, and a "pause" request is never routed to a delete tool. This closes a class of error where an ambiguous instruction like "pause these keywords" could be interpreted as a permanent deletion. Read tools still auto-run; only irreversible actions are gated. → [Tool safety model](/docs/mcp#tool-safety-model) **July 6, 2026** Google App campaigns + LinkedIn campaign groups & forecasting ## Google App Campaigns + a Much Deeper LinkedIn **Google App (Universal App) campaigns.** `create_app_campaign` launches campaigns that drive app **installs, engagement, or pre-registration** across Search, Google Play, YouTube, Display, and Discover — with app-ad creative management. Created PAUSED for review. → [Google App campaigns](/docs/ad-platforms/google-ads) **LinkedIn, deepened (now 55 tools).** New this week: * **Campaign groups** — create, update, delete, list, search, and batch-create groups with shared budgets and schedules. * **Pre-launch forecasting** — `estimate_linkedin_audience_size` and `forecast_linkedin_campaign_supply` project reachable audience and expected impressions/clicks/spend at a given budget, so you size campaigns with data. * **Full lifecycle** — archive, reactivate, delete, clone, and batch-update campaigns. → [LinkedIn Ads integration](/docs/ad-platforms/linkedin-ads) **July 4, 2026** Google Shopping + Merchant Center + smarter tool discovery ## Google Shopping Campaigns Arrive Run **Standard Shopping** campaigns straight from your Google Merchant Center feed — no per-product ad building. * `link_merchant_center` / `get_merchant_center_links` connect your product feed. * `create_shopping_campaign` → `add_shopping_ad_group` → `add_shopping_product_ad` builds the campaign. * **Product partition trees** (`add_product_group` and friends) let you subdivide the feed by brand, category, product type, or item ID and bid on each partition independently. → [Google Shopping campaigns](/docs/ad-platforms/google-ads) **Smarter tool discovery.** As the surface grows past 400 tools, new `search_tools` (find the right tool from a natural-language description) and `get_tool_schema` (fetch a tool's exact parameters) keep the AI accurate. → [How discovery works](/docs/mcp) **July 3, 2026** Google Ads Manager-parity deep management ## Manager-Parity Deep Management for Google Ads Google Ads is now Adspirer's deepest integration at **147 tools**, with control down to the ad-group, asset-group, and product-partition level: * **Search** — ad-group lifecycle and settings, demographics, audiences, proximity / ad-schedule / device-bid targeting. * **Demand Gen** — create campaigns and ads, manage audiences and channel controls across YouTube, Shorts, Discover, and Gmail. * **Performance Max** — full asset-group lifecycle, per-asset edits, asset-performance ratings (Best / Good / Low), and listing filters for retail PMax. * **Campaign-level depth** — tracking, dates, frequency caps, network settings, and labels. Every write is live-verified against a sandbox. → [Google Ads integration](/docs/ad-platforms/google-ads) **July 2, 2026** Cross-platform Ad Ops agents, teach-your-agent + Meta lead forms ## Ad Ops Agents Get Smarter — and Cross-Platform * **Cross-platform agents.** One agent can now reason and act across **Google, Meta, TikTok, LinkedIn, and Amazon** from a single goal — e.g. "cap total monthly spend at 10,000 CAD across Meta, Google, and LinkedIn." * **Teach your agent.** Upload your own brand rules, target CPAs, seasonal calendars, and SOPs; every run grounds its decisions in your documents. * **Evidence-gated impact.** Impact verdicts only make a causal claim when your own data supports it — no more misleading "+54% worse" calls off a tiny sample. * **Rejection-reason chips.** One tap tells the agent *why* you rejected a proposal, so the next run is better. Also: **Meta native lead-form campaigns** (on-platform Instant Forms, no pixel required) now pass pre-flight. → [Autonomous Ad Ops agents](/docs/agent-skills/ad-ops-agents) **June 30, 2026** Meta Advantage+ Catalog (dynamic product ads) ## Meta Advantage+ Catalog — Dynamic Product Ads Adspirer now runs **Meta Advantage+ Catalog campaigns (dynamic product ads / DPA)** — the way e-commerce advertisers show the exact products from their feed to the right shopper without hand-building an ad per SKU. **16 new Meta tools** (Meta Ads is now 54 tools): * **Discover & prepare** — `list_meta_catalogs`, `list_meta_products`, `list_meta_product_sets`, `create_meta_product_set`, and `validate_catalog_readiness` (a pre-flight that tells you whether your catalog + pixel data supports **retargeting** or **prospecting only**, before you spend). * **Launch & manage** — `create_meta_catalog_campaign` (prospecting or retargeting, created PAUSED) plus catalog ad-set and ad management. * **Optimize** — `analyze_meta_catalog_performance`, `get_meta_product_performance` (per-SKU ROAS), `detect_meta_catalog_waste`, and `diagnose_meta_catalog_funnel`. Connect a catalog you already manage in Meta Commerce Manager (or synced from Shopify/WooCommerce) and manage the ads conversationally. → [Meta Catalog ads](/docs/ad-platforms/meta-ads) **June 24, 2026** Ad Ops agent builder, approvals & community playbooks ## Build, Approve, and Share Ad Ops Agents The autonomous Ad Ops agent got a full build-and-run experience: * **Gallery + 5-step builder** with active-agent cards, background goal-compile so the builder opens instantly, and per-agent detail panels. * **Approvals from the card** — review, approve, or reject each proposal in place, with server-side approval counts and a per-agent inbox. * **Impact & Recommendations tabs** — see whether approved changes actually added value (fed back into the next run) and a running list of prioritized, ad-focused suggestions. * **Community playbooks** — share an agent's decision logic (goal, rules, and guardrails only — never accounts or budgets) and fork others' proven playbooks onto your own account. → [Autonomous Ad Ops agents](/docs/agent-skills/ad-ops-agents) **June 23, 2026** Shareable Dashboards V2 — white-label & adaptive ## Shareable Dashboards V2 — White-Label & Adaptive Shareable dashboards were rebuilt into a data- and platform-adaptive report you can hand to clients: * **White-label** — upload your own logo, set a custom title and footer, and hide Adspirer branding. * **Adaptive depth** — \~20 analysis blocks (Pareto, anomaly z-scores, efficiency frontier, funnel, treemap, waterfall) that appear only when your data supports them, plus per-platform "signatures" for Google, Meta, TikTok, and LinkedIn. * **Prompt-mode** — compose a dashboard's layout from a natural-language prompt. Links stay live (fresh data on open), expire per plan tier, and are revocable. → [Shareable dashboards](/docs/knowledge-base/capabilities#shareable-dashboards) **June 22, 2026** Community Plugins — open-source, read-only extensions ## Community Plugins (v1) Adspirer can now be extended with **open-source, community-contributed analysis tools** that appear alongside the built-in ones via the `community_plugins` router. They're **read-only** to your ad accounts, run in a **credential-free, sandboxed** sub-server, and are loaded from a **pinned, reviewed commit** of the public [`Adspirer/adspirer-mcp-community`](https://github.com/Adspirer/adspirer-mcp-community) repo. First example: a keyword clusterer that groups your search terms into themes. → [Community Plugins](/docs/agent-skills/community-plugins) **June 20, 2026** Now in 116 languages + Start Here onboarding ## Adspirer Now Speaks 116 Languages The Adspirer dashboard, onboarding, and AI-client setup guides are now localized into **116 languages**, with: * **Automatic browser-language detection** and a one-click language switcher. * Full **right-to-left (RTL)** support for Arabic, Hebrew, Persian, Urdu, and more. * A language preference that's **remembered across devices**. And because you manage ads by chatting with an AI, you can give instructions in your own language. → [Localization](/docs/knowledge-base/localization) Also new: a redesigned **Start Here** onboarding experience with an interactive, illustrated card carousel and try-it prompts that track real completion from your own account history. **June 18, 2026** Autonomous Ad Ops agents are live ## Autonomous Ad Ops Agents Go Live Adspirer's **autonomous Ad Ops agents** are out of beta. Give an agent a plain-English goal and a cadence, and it monitors your accounts on a schedule and **proposes every change to an approval queue** — find winners to scale, wasted spend to cut, budgets to rebalance, CPA/ROAS drift to correct, or broken conversion tracking to flag. Nothing spends or changes without your approval, enforced server-side. Available on Plus, Pro, and Max. → [Autonomous Ad Ops agents](/docs/agent-skills/ad-ops-agents) **June 17, 2026** ChatGPT Ads — new platform ## Run Ads Inside ChatGPT — New: ChatGPT Ads (OpenAI Ads) Adspirer now supports **ChatGPT Ads (OpenAI Ads)** — pay-per-click "chat card" ads that render inside ChatGPT responses, with **31 tools** to launch, manage, and measure them conversationally from ChatGPT, Claude, or any connected AI client. (This also brings Adspirer's total tool surface to 340+.) * **Connect once with an API key.** ChatGPT Ads is Adspirer's first non-OAuth platform: paste your OpenAI Advertiser API key in the Connections tab (one key = one ad account). It's stored encrypted, and the chat agent never sees it. * **Launch in one shot, or manage granularly.** `launch_chatgpt_ad` builds the whole ad from a description (URL, headline, body, image, budget, geo), or use full campaign/ad-group/ad controls (list, get, create, update, pause, resume, archive). * **Paused by default.** Nothing serves or spends until you resume the campaign, and the agent always speaks in dollars, not micros. * **Honest review status.** Adspirer reports OpenAI's ad-review state (in review → approved/rejected) and flags policies up front — notably that third-party AI services are disallowed. * **Conversions** via the OpenAI pixel and Conversions API, with a built-in test event to verify tracking. → [ChatGPT Ads integration guide](/docs/ad-platforms/chatgpt-ads) **June 16, 2026** Meta conversions reconcile with Ads Manager ## Meta Performance: Conversions That Reconcile With Ads Manager The Meta performance dashboard now shows a **full conversion-action breakdown** and highlights the **purchase-class event** that matches the "Results" column in Meta Ads Manager. Meta's `total_conversions` sums every pixel action (add-to-cart, initiate-checkout, purchase, and more), which could make the dashboard headline look far higher than Ads Manager's purchase count. Now you can see exactly which figure reconciles — no more chasing a phantom discrepancy. CPA, ROAS, and deltas are unchanged. **June 12, 2026** Google ad-level performance & creative export ## Google Ads: Per-Ad Performance, Creative Export & Complete Asset Discovery * **`get_ad_performance`** — a per-ad breakdown (one row per ad) with impressions, clicks, CTR, cost, conversions, conversion value, CPC, CPA, ROAS, video views, ad strength, and a live flag — plus a head-to-head comparison when an ad group has multiple ads. Covers Search, Display, Demand Gen, and YouTube. * **`get_ad_creative`** — export the creative composition of existing ads: YouTube video IDs and thumbnails, downloadable image URLs with roles and dimensions, every headline/description/CTA, and carousel cards. * **`discover_existing_assets`** is now **paginated** across all asset types, returning your complete asset inventory instead of silently capping — with downloadable image URLs and a clear path forward when a square logo is missing (previously a dead end for Performance Max). The OpenClaw plugin (v2026.6.12) bundles these too. **June 11, 2026** Claude Cowork OAuth self-serve fix ## Claude Cowork: Self-Serve Fix for "No OAuth Flow Is in Progress" If Claude's desktop/Cowork app shows *"No OAuth flow is in progress"* when connecting Adspirer, that's a known client-side bug in the Claude app — not an Adspirer problem. The fix takes about 30 seconds: in Claude, go to **Settings → Connectors → Add custom connector**, enter `https://mcp.adspirer.com/mcp`, and connect from there. → [Claude Cowork setup](/docs/ai-clients/claude-cowork) **June 10, 2026** Amazon Ads — new platform ## Amazon Ads Joins Adspirer — 61 Tools for Sponsored Products, Brands & Display Amazon Ads is now a fully supported ad platform, with **61 tools** spanning **Sponsored Products, Sponsored Brands, and Sponsored Display**. * Connect via **Login with Amazon**; Adspirer discovers your advertiser profiles across **North America, Europe, and the Far East** and imports each as an ad account. * Full Sponsored Products lifecycle (campaigns → ad groups → product ads → keywords / targets / negatives), all 7 Sponsored Brands ad types (Brand Registry required), and Sponsored Display. * Amazon-native analytics: **ACOS / ROAS**, per-ASIN performance, wasted-spend detection, budget optimization, and a purchased-products cross-sell view. Reporting runs asynchronously via `get_amazon_report`. → [Amazon Ads integration guide](/docs/ad-platforms/amazon-ads) ### Meta: EU DSA support + an extra Google extension tool * Meta ad sets that target the **EU/EEA** now accept the required **DSA disclosure** fields (`dsa_beneficiary` / `dsa_payor`), so EU-targeted campaigns no longer dead-end. The fields are sent only when an ad set actually targets the EU/EEA. * Google Ads adds **`remove_structured_snippets`** to clear stale snippet values before adding fresh ones. The OpenClaw plugin (v2026.6.10) adds the Amazon Ads router. **June 9, 2026** In-chat dashboards overhaul ## In-Chat Dashboards: Tabs, Date Ranges, Working Buttons & Mobile The interactive widgets in ChatGPT and Claude got a major upgrade: * **Tabbed performance dashboard** — Overview / Campaigns / Insights, with KPI tiles, period-over-period deltas, charts, "needs attention" highlights, and **7 / 14 / 30 / 60 / 90-day plus custom date-range** switching that re-runs the query live. * **Redesigned conversion-audit and connections widgets** — a graded scorecard with an action plan, and an account switcher with a quota meter. * **Action buttons now work** — "pause this campaign" or "draft a message for my developer" post straight back into the chat. * **Mobile rendering** — widgets now render in the Claude mobile app, with a clean text fallback on clients that don't support them. **June 8, 2026** Google agency-level Standard Access ## Approved at the Agency Level for the Google Ads API Google reviewed and classified Adspirer as an **agency, full-service ad platform** for the Google Ads API and granted **Standard Access** — which lifts the daily operations cap. Bulk builds, large account restructures, and account-wide optimization now run at full speed, with no daily ceiling on Google Ads work. **June 6, 2026** Connection Health on Usage & Billing ## See Your Connection Health on Usage & Billing The Usage & Billing page now shows a **Connection Health** card: whether your AI assistant is connected via MCP, and — per ad account — whether the OAuth link is healthy or needs reconnecting. A **Test now** button re-checks live, so you can confirm everything's wired up before you start a session. **June 5, 2026** TikTok targeting fix + redesigned setup guide ## TikTok Targeting Search Fixed + Redesigned Setup Guide * **TikTok targeting search works again.** `search_tiktok_targeting` had been failing for every caller; it's fixed. Interest keywords are targeted by **numeric ID** (from that search), not by plain keyword strings — the tool docs now make this explicit. * **Redesigned setup guide.** The per-client setup experience now has a screenshot carousel synced to the step list and a walkthrough video for Claude Cowork and ChatGPT, plus a standalone Setup Guide you can revisit any time from the web app. **June 2, 2026** Local targeting & support chat ## Meta Local Targeting Lands Correctly + Screenshots in Support Chat ### City + radius targeting now reaches Meta Targeting a city with a radius — "everyone within 20 miles of Austin" — now reaches Meta as a real city-and-radius instead of being mis-sent as an invalid country code and silently dropped. Local campaigns on image, video, and carousel ads were effectively running nationwide (or failing) before this fix. * **Multiple cities, each with its own radius**, now work in a single ad set. * **Location reach modes** — choose who in a location you reach: people who **live** there, were **recently** there, or are **traveling to / interested in** it. * **Safer location edits** — updating an ad set's locations now merges onto its existing targeting instead of replacing everything, so a location-only change no longer wipes the rest of your targeting. ### Attach screenshots to the support chat The in-app support chat widget now accepts **PNG/JPEG screenshots** — click the paperclip, paste, or drag-and-drop. Support reads the image and runs its diagnostics on it, which is far faster for visual issues. Up to 5 images per message (5 MB each); screenshots are processed in-memory and never stored. Conversations also now **resume where you left off for up to 7 days** (previously 48 hours). **June 1, 2026** Onboarding & billing ## Onboarding & Billing Refresh A polish pass across sign-up and plan management: * **App Store connect tabs** on the onboarding connection screen, matching how you actually install Adspirer in ChatGPT and Claude. * **Redesigned pricing step** — an animated tool-call hero, clearer active-account messaging, and a full-width tier ladder so the plan differences are easy to scan. * **Congrats screen** confetti and copy polish once you finish setup. * **"Manage Subscription"** now reliably opens the Stripe billing portal from the account menu. **May 31, 2026** Account switching ## Switch Your Active Ad Account From Chat You can now change which ad account Adspirer acts on **by just asking** inside ChatGPT or Claude — including switching between child accounts under the same Google Ads manager (MCC) — without opening the web app. ``` Use my Sahaayak Google Ads account instead ``` * `list_connected_accounts` now surfaces connected-but-not-yet-activated accounts (including live MCC child accounts), so the agent can resolve a business name to the right account and switch to it. * Switching respects your plan's [active-account cap](/docs/knowledge-base/multi-account): on single-account tiers the new account **replaces** the active one; on multi-account tiers (annual plans and Max) it's **added** to the active set. * Account switching is a session operation — it never costs a tool call. Previously this switch silently failed over MCP. It now works end-to-end from any connected AI client. **May 30, 2026** Diagnostic & Helper tools ## Diagnostic & Helper Tools — and Interactive Widgets in ChatGPT & Claude A new group of **13 read-only "get unstuck" tools** is now live across every AI client, on Free and up. They're **quota-free** — calling them never counts against your monthly tool calls. ### Get started, pre-flight, diagnose, and see your value | When | Tools | What they do | | - | - | - | | **Getting started** | `start_here`, `suggest_next_action`, `list_what_i_can_do` | Personalized "what should I do next" based on your real connected accounts and data | | **Before launching** | `get_campaign_spec`, `preflight_campaign`, `validate_campaign_draft` | Check an account is launch-ready and dry-run a campaign against the platform's rules before anything is created | | **When something fails** | `explain_platform_error`, `why_did_this_fail`, `diagnose_my_setup`, `verify_campaign_is_live` | Turn a cryptic platform error into a plain-language fix, run a full connection health check, and confirm a campaign is actually serving — a **real live check against all four platforms** | | **See your value** | `whats_changed_since_last_visit`, `weekly_opportunities`, `usage_value_summary` | What moved since you were last here, 1–3 concrete optimization opportunities, and what your plan delivered | `diagnose_my_setup` is especially useful when you're not sure whether a problem is your AI-client connection or your ad-platform sign-in — it tells them apart. → [Full Diagnostic & Helper reference](/docs/agent-skills/diagnostic-helper-tools) ### Answers render as interactive cards In **ChatGPT and Claude**, these tools now render as branded, interactive cards — setup checklists, usage meters, opportunity lists, an account switcher — instead of a wall of text. The cards adapt to light/dark themes and fall back gracefully to plain text on any client that doesn't render widgets. ### OpenClaw plugin v2026.5.30 The OpenClaw plugin now bundles the diagnostic & helper tools too (tool count 139 → 140). Reinstall with `openclaw plugins install openclaw-adspirer` to pick them up. **May 30, 2026** Google Ads reliability ## Google Ads: Clearer Bidding Errors, Reliable Keyword Metrics, Full Ad Extensions ### Bid-strategy changes explain themselves Changing a campaign's bid strategy when it's attached to a **shared (portfolio) bid strategy** used to fail with Google's opaque "operation not allowed for the given context." Adspirer now detects the portfolio strategy up front and tells you exactly what to do — detach it from the campaign, or edit the shared strategy itself. Smart Bidding errors (Target CPA / Target ROAS) now include the conversion-tracking prerequisites you're missing. ### Keyword research metrics reach your AI reliably `research_keywords` now surfaces **per-keyword search volume, competition, average CPC, and top-of-page bid range** in the structured data your assistant reads — so it stops claiming "per-keyword data isn't available" when Google Keyword Planner returned it all. ### Ad copy edits stop failing on duplicates Editing a Responsive Search or Display ad no longer fails with "Assets are duplicated across operations" — Adspirer automatically de-duplicates identical headlines/descriptions before submitting, and if that leaves you short of Google's minimum, it tells you exactly how many more unique lines to add. ### Full ad-extension control Sitelinks, callouts, and structured snippets now have complete add / remove / list coverage, including the new `remove_structured_snippets` tool for clearing out stale snippet values. Sitelinks also accept natural field names (`text`/`headline`, `url`/`link`) and are now suggested whenever you ask about "extensions" or "making my ads better" — you don't have to know the word "sitelinks." **May 29, 2026** Meta conversions & creatives ## Meta Ads: Conversion Reporting You Can Trust, Plus Creative & Agency Fixes ### Conversions Meta actually reports now count If your campaigns showed real conversions in Meta Ads Manager but **zero in Adspirer**, this fixes it. Adspirer now counts: * **Pixel custom-event conversions** (e.g. a Calendly booking) — the most common "0 conversions" cause * **Lead-form submissions** and **Messenger conversations** * **Offline conversions**, with a **per-event-name breakdown** ("5 *invitee\_select\_time* events", not "5 custom conversions") Lead-gen and sales campaigns are now correctly treated as conversion campaigns in wasted-spend, anomaly, and budget analysis — no more "Meta is optimizing blind" when it isn't. > [!NOTE] > > This applies to newly collected performance. Historical numbers for affected accounts backfill separately as data is re-collected. ### Creating ads with fewer dead ends * **Carousel ads** accept your existing assets (the same `existing_image_hash` Adspirer's discovery returns) and validate each card up front — needs an image, headline, and landing URL — with a clear message instead of an opaque Meta rejection. * **Dynamic creative (DCO)** ads now accept multiple headlines and body texts directly, and Adspirer auto-enables dynamic creative on the target ad set for video as well as image. * **Conversion ad sets** now warn you about a **missing pixel** before Meta rejects the campaign with "promoted object fields missing." ### Agency-grade cross-account safety If you manage multiple ad accounts and ask the agent to add an ad to an ad set that belongs to a *different* account, Adspirer now catches the mismatch, names both accounts, and points to the right tool — instead of a misleading "missing image" loop. Deselected (inactive) accounts can no longer be written to until you re-activate them. **May 29, 2026** ChatGPT App Store ## Adspirer Is Now in the ChatGPT App Store Adspirer is now an **official ChatGPT app** — no more Developer mode, custom connectors, or pasted server URLs. Open **Apps** in ChatGPT, search **"Adspirer,"** click **Connect**, and sign in. Setup takes under a minute, and you invoke it in any chat by mentioning **@adspirer**. * **One-click install** — find Adspirer in the ChatGPT App Store and connect with OAuth; ChatGPT manages the connection for you. * **No elevated-risk warning** — the old Developer-mode + "I understand and want to continue" flow is gone for ChatGPT users. * **Same account, same tools** — all 190+ tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok work exactly as before. If you previously added Adspirer as a custom connector, remove it and reconnect through the App Store; your account and ad platform connections carry over. [ChatGPT App Store setup guide →](/docs/ai-clients/chatgpt) **May 26, 2026** v2.23.1 ## Platform Hardening & Resilience Fixes * **MCP base image hardening** — all six MCP sub-servers (hub + Google + Meta + TikTok + LinkedIn + Monitoring) pinned to `python:3.11-slim-trixie` with audit-pass cryptography and authlib dependencies. * **Container scanning by digest** — vulnerability scans resolve images to their content digest instead of the floating `:latest` tag, so the report can't drift between scan time and image promotion. * **Tool routing resilience** — tighter input handling on Google Ads tool routing and a longer hub timeout for slow Meta calls. * **Watch Agent stability** — finding classifier no longer cascades a stuck SQL transaction into a noisy false-positive. **May 25, 2026** v2.23.0 ## Multi-Google-OAuth, Meta Account Improvements & Per-Platform Cap Messaging ### Connect Multiple Google Logins to One Adspirer Account A single Adspirer account can now hold **multiple Google OAuth grants**, each with its own non-overlapping set of Google Ads customer IDs. Agencies and consultants who manage Google Ads across separate Google identities no longer need a second Adspirer account. * Adds a second (or third) Google login from the **Connections → Google Ads → Add another Google login** flow. * Each grant tracks its own customer IDs; the agent routes tool calls to the right OAuth based on the customer you reference. * Available on **Max annual** today; rolling to the rest of the paid tiers behind a feature flag. ### Meta Ads — Account Discovery & Asset Handling Overhaul A set of improvements to how Adspirer works with Meta Business Manager and ad-account-scoped assets. * **Business Manager-wide import** — when you connect Meta, Adspirer discovers **every ad account inside the Business Manager** you grant access to, not just the one you happened to click during OAuth. The Manage Accounts modal lists them all so you can pick which ones to activate. * **Per-account asset scoping** — image, video, and creative discovery is now scoped to the specific ad account you're targeting. Eliminates the "this asset was discovered but Meta says it's not in this ad account" error class. * **Opt-in auto-copy of creatives** — when you reuse a creative from a sibling ad account, Adspirer offers to copy it into the target account before launching the campaign (opt-in per call) so the launch doesn't stall on asset placement. * **Clearer "no account" error** — when a tool call can't find a Meta account, the response distinguishes a stale token from a missing-row state so you (or your AI client) know whether to reconnect or just re-select. ### Per-Platform Active-Account Messaging The active-account cap is **per platform** — every plan card across pricing and the Manage Accounts modal now states up front how many active accounts you get per platform (Google + Meta + LinkedIn + TikTok each counted independently). When you're at the cap, the modal shows an inline upsell that links directly into the Adspirer plan picker. ### Smaller Improvements * **Sidebar rename** — "Account Setup" is now **Home**. Same page, more accurate label for users past initial setup. * **Brief coverage** — scheduled performance briefs are scoped to your selected accounts (not just the primary), with full multi-OAuth coverage so a second Google identity's accounts no longer show up empty. * **Live-tail merge** for Google Ads in the brief data fetchers so spend that hit the API after the nightly sweep still lands in your brief. **May 24, 2026** v2.22.0 ## Plan Limits, Cap Rework & Connections Panel Refresh ### Active-Account Caps — New Per-Tier Limits The big change: **annual plans now activate up to 5 accounts per platform**, not 1. Monthly plans (except Max) still cap at 1 per platform. Full table: | Plan | Monthly | Annual | | - | -: | -: | | Free | 1 | 1 | | Plus | 1 | **5** | | Pro | 1 | **5** | | Max | **5** | 5 | * "Account" means an ad account on a single platform — Plus annual customers can activate up to 5 Google Ads accounts **and** 5 Meta accounts **and** 5 LinkedIn accounts **and** 5 TikTok accounts. * Every Stripe webhook now reconciles down-tier moves automatically: if you downgrade from Max monthly to Plus monthly, excess actives demote to inactive (deterministically — primary-set-first, then most-recently-synced). * Caps live in a new `subscription_plan_limits` table so we can adjust without redeploys, and every change is written to a `tier_limit_changes` audit log. * **Defense in depth:** the MCP hub also truncates account lists at the tier cap before returning them, so any reconciliation gap can't accidentally let a downgraded user keep agent access to more accounts than their plan allows. ### Onboarding & Connections — Smoothed Out * **Onboarding Step 5 stays put** — fixed an issue where the Congrats screen would bounce users back to Step 1 if their AppUser stub hadn't finished writing after Stripe checkout. You always land on Step 5 post-payment now. * **Connections panel — unified stacked rows** — Available Platforms restyled to compact rows that match the Pipedream integration cards below. The Google Analytics + Klaviyo cards no longer hide below the fold. * **OAuth modal always opens** — after a successful OAuth, the account-selection modal opens regardless of how many accounts are under your OAuth identity. No more silent auto-pick when you have multiple accounts and didn't realize. * **Tier-aware Manage Accounts modal** with an inline Edit button and a Connections-panel mirror so the active-account picker shows the same state in both surfaces. * **Admin: Plan Limits page** with a dry-run preview that counts affected users before you commit a cap change. ### Bug Fixes * "Add another Google login (coming soon)" placeholder is replaced with a Max-annual upsell that explains how to unlock it today. * `get_ad_accounts` now filters out deselected (inactive) accounts so they stop rendering as green Active in the Connected Platforms UI. **May 22, 2026** v2.21.0 ## Google Analytics & Klaviyo Integrations Adspirer's first non-ad-platform integrations are live. Plus, Pro, and Max users can now connect **Google Analytics 4** and **Klaviyo** alongside their ad accounts, and the agent can read and act on those properties through chat. ### What You Can Do | Integration | Tool | What it does | | - | - | - | | Google Analytics (GA4) | `google_analytics` | Read property data — sessions, conversions, traffic sources, landing-page performance — so the agent can correlate paid ad spend with site behavior. | | Klaviyo | `klaviyo` | Read campaigns, flows, segments, profiles, and metrics so the agent can pull email/SMS performance alongside paid media. | Each is a **router tool** — `action="list_tools"` first to discover what's available, then `action="execute"` with the specific Pipedream tool name to call it. The agent handles this two-step automatically. ### How It Works * Connect from the **Connections** tab at [adspirer.ai](https://adspirer.ai/connections) — each integration has its own OAuth popup powered by Pipedream Connect. * Gated to **Plus and above**. Free users see the integration card with a "Upgrade" prompt that links into the Adspirer plan picker. * Disconnect anytime from the same panel; idle connections (>90 days) get pruned automatically to keep the integration list tidy. ### Self-Serve Account Deletion in the Chat Widget Free-tier users can now ask the in-app chat widget to delete their account end-to-end — no email round-trip required. The widget confirms before executing and runs the full GDPR delete (hard-delete + pseudonymize + retain per Article 17(3)(b)). ### OpenClaw Plugin v2026.5.12 Bumped to expose the new integration tools plus 9 additional Google Ads tools (PMax search themes, audience signals, ad group management) and 3 monitoring tools. **May 21, 2026** v2.20.1 ## Watch Agent Polish & Support Widget UX ### Watch Agent Briefs * **Conversion-tracking caveat** — briefs now include a "conversion data is reported through your platforms" caveat so anomalies in conversion volume aren't read as Adspirer numbers. * **Paused vs active classification** — briefs no longer call a paused campaign "underperforming" — paused campaigns are explicitly flagged as paused. * **Account names cleaned** — fixed a template placeholder that was occasionally showing up in account labels. * **Dead dashboard link replaced** — the in-brief "open dashboard" link is now a copy-paste AI prompt you can run in your AI client to drill into the finding. * **Recommendations de-alarmed** — toned down "URGENT" language on routine recommendations so high-severity callouts read as actually high severity. ### Monitors & Alerts * **`create_monitor` returns 409** when you try to create a duplicate alert instead of silently writing two. * **Digest email values corrected** — the daily digest now reports the same value the alert evaluated against, not a stale snapshot. ### Support Chat Widget * **Address by name** — the in-app support widget greets you by name from turn 1. * **Panel state persists** — the widget stays open across page navigations and refreshes, with a time-aware "welcome back" greeting when you return. **May 20, 2026** v2.20.0 ## Watch Agent, Monitors & Alerts Web UI, and 8 New MCP Tools ### Watch Agent — Proactive Signal The **Watch Agent** is a server-side AI agent that scans your connected ad accounts every 15 minutes, identifies issues, and emails you a copy-paste re-entry prompt so you can act immediately inside your AI client. No more waiting for weekly reviews to catch a broken campaign. **What the Watch Agent does:** * Analyzes ROAS, CPA, CTR, spend, and conversion rate across all connected platforms * Distinguishes true anomalies from normal variance (noise suppression built in) * Stages pre-validated fix actions (pause campaign, adjust bid, add negatives) alongside each finding * Sends a finding email with a ready-to-paste prompt when severity ≥ medium is detected **MCP tools for the Watch Agent:** | Tool | Type | Description | | - | - | - | | `run_watch_now` | Read | Trigger an on-demand Watch Agent scan immediately — don't wait for the next scheduled run | | `get_signal_briefing` | Read | Pull the advisory briefing and pre-staged fixes for a specific Watch Agent finding | | `apply_signal_actions` | Write | Apply the pre-staged fixes from a finding — approve with one call | | `list_pending_actions` | Read | See all actions staged by the Watch Agent waiting for your approval | | `manage_action` | Write | Approve or reject an individual staged action | **Example:** ``` "Run the watch agent on my accounts now" → run_watch_now "Show me the briefing for signal abc123" → get_signal_briefing(signal_id="abc123") "Apply the staged fixes" → apply_signal_actions(signal_id="abc123") ``` The Watch Agent runs automatically for all connected accounts — no setup required. ### Monitors & Alerts — Web UI A new **Monitors** page at [adspirer.ai/monitors](https://adspirer.ai/monitors) lets you create and manage performance alerts without opening your AI client. Every alert you create on the web goes to the same backend as the MCP `create_monitor` tool — the Watch Agent reads from one unified table regardless of which surface created the alert. **What you can do on the Monitors page:** * Create alerts for CPA, ROAS, CTR, CPC, spend, conversions, impressions, clicks, cost per lead, conversion rate, or budget utilization * Set thresholds with "goes above" or "drops below" operators * Optional: trigger only after N consecutive days (1–14) — filter out one-off noise * Scope to specific platforms (Google Ads, Meta, LinkedIn, TikTok) or all connected * Edit, pause, resume, test (dry-run), and delete alerts in the dashboard **Supported alert metrics:** | Metric | Example threshold | | - | - | | CPA | Alert when CPA goes above \$50 | | ROAS | Alert when ROAS drops below 2x | | CTR | Alert when CTR drops below 1% | | Spend | Alert when daily spend goes above \$500 | | Budget utilization | Alert when pacing exceeds 110% | | Conversions | Alert when conversions drop below 1 | | Clicks, Impressions | Volume monitoring | ### 3 More New Monitoring Tools | Tool | Type | Description | | - | - | - | | `get_monitor_history` | Read | See all past trigger events for a specific alert — when it fired, what values triggered it | | `test_monitor` | Read | Dry-run a monitor against today's data — see whether it would fire without waiting | | `manage_scheduled_task` | Write | Unified pause, resume, or delete for any brief, monitor, or scheduled task | ### PDF Reports for Scheduled Briefs Scheduled performance briefs now **attach a PDF** to the email. The PDF contains the same tables and charts as the email body — useful for sharing with stakeholders who don't have Adspirer access. **Monitoring tool count: 8 → 16** **May 16, 2026** v2.19.0 ## Annual Plans & Max Quota ### Annual Quota Pooling Annual subscribers now get a **single pooled allowance for the full year** instead of per-month caps. No monthly resets — use your calls whenever you need them. | Plan | Annual Price | Annual Pool | Monthly Equivalent | | - | - | - | - | | Plus | \$485/year | 1,800 calls | \~150/month | | Pro | \$999/year | 7,200 calls | \~600/month | | Max | \$2,000/year | 50,000 calls | \~4,167/month | * Pool renews on your subscription anniversary date. Unused calls do **not** roll over. * Annual subscribers are **never charged overage** — the yearly pool is your total budget for the year. * Max annual (50,000) is intentionally higher than 12× monthly (36,000) as the upgrade incentive for high-volume months. ### Max Plan: 3,000 calls/month The Max plan monthly limit is now formalized at **3,000 calls/month** (previously displayed as "unlimited"). This aligns with the Stripe product metadata and all enforcement layers. Max annual subscribers retain the 50,000/year pool with no monthly cap. See the updated [Pricing & Tool Calls](/docs/knowledge-base/pricing) page. **May 15, 2026** v2.18.2 ## GDPR Article 17 — Right to Erasure Account deletion requests (submitted via **[support@adspirer.com](mailto:support@adspirer.com)**) now correctly pseudonymize all associated audit log rows, satisfying GDPR Article 17 right-to-erasure requirements. A bug in the deletion pipeline previously left historical audit rows intact. A one-time backfill also pseudonymized rows from prior deletion requests that had been processed without full erasure. > [!NOTE] > > Account deletion is handled by the Adspirer support team. To request account deletion, email **[support@adspirer.com](mailto:support@adspirer.com)**. **May 14, 2026** v2.18.1 ## TikTok: 3 Customer-Blocking Fixes Three bugs from live tool call logs that were causing TikTok campaign creation failures. ### Local Currency for Budget Floors TikTok campaign budget pre-flight checks were using USD as the hardcoded currency regardless of the advertiser's local currency. This caused incorrect minimum budget enforcement for non-USD accounts. The fix fetches the correct currency and timezone from TikTok's API at OAuth connect time, and backfills existing accounts. A one-time database backfill corrected 167 of 170 affected accounts (3 had expired tokens). ### Disclaimer Text Format Ad disclaimer text must be passed as a structured object (`{"text": "..."}`) rather than a plain string per TikTok's API requirements. Campaigns with a `disclaimer_text` were silently failing at TikTok's server even though the tool accepted the input. The fix wraps string input into the correct object format automatically. Disclaimer text is also now enforced at a max of 90 characters (TikTok's hard limit). ### CTA Autocorrect & Full Whitelist The `call_to_action` field on TikTok ads previously accepted stale values that TikTok's API would reject at campaign creation time. The field is now backed by: * **30-value authoritative whitelist** extracted from TikTok's rejection response * **14-alias autocorrect map** for commonly used old values: | Old (accepted, now autocorrected) | New (correct) | | - | - | | `DOWNLOAD` | `DOWNLOAD_NOW` | | `BUY_NOW` | `SHOP_NOW` | | `INSTALL` | `INSTALL_NOW` | | `WATCH` | `WATCH_NOW` | | `GET_OFFER` | `GET_QUOTE` | | `BOOK` | `BOOK_NOW` | Autocorrect applies to all 4 CTA schema fields (campaign creation, video ads, `add_tiktok_ad`, carousel). Invalid values that don't map to an alias return a clear error with the full allowed list. **May 12, 2026** v2.18.0 ## Google Ads: Campaign Control Expansion 18 new capabilities across campaign management, search campaign creation, and asset tools, resolving the top customer-reported gaps from production. ### Ad Group Pause / Resume Two new tools give you ad group-level control without touching the parent campaign: * **`pause_ad_group`** — Pause an individual ad group while leaving the campaign running * **`resume_ad_group`** — Resume a paused ad group ### `update_campaign` — Expanded Controls `update_campaign` now accepts 6 new parameters: | Parameter | What it does | | - | - | | `search_partners` | Enable or disable the Google Search Partners network | | `display_expansion` | Enable or disable Display Expansion for Search campaigns | | `language_codes` | **Replace** the campaign's language targeting (ISO-639-1 codes like `"en"`, `"es"`, `"fr"` or `languageConstants/` resource names from `list_google_languages`) | | `locations_to_add` | Append geo targets (free-text or `geoTargetConstants/` resource names) | | `locations_to_remove` | Remove geo targets by criterion resource name | | `audience_targeting_mode` | Set `OBSERVATION` (bid adjustments only) or `TARGETING` (targeting restriction) | | `ai_max_enabled` | Enable or disable AI Max for eligible Search campaigns | ### `create_search_campaign` — Per-Keyword Match Types Initial keywords in `create_search_campaign` now accept a mixed format: * Plain strings default to BROAD (backward compatible) * Objects like `{"text": "running shoes", "match_type": "PHRASE"}` set EXACT or PHRASE on individual keywords Previously, all initial keywords were forced to BROAD match — requiring a separate `add_keywords` call to set correct match types. ### New Asset Tools Three new tools for attaching assets to Search campaigns: * **`add_business_name_asset`** — Attach a business name text asset (max 25 characters) at the campaign level * **`add_call_asset`** — Attach a phone number call asset with country code. Accepts an optional `call_conversion_action` resource name to enable call conversion tracking. * **`add_search_campaign_image`** — Attach image assets to Search campaigns (logo, landscape, square, portrait). Accepts HTTP URLs or base64-encoded data URIs. ### `get_campaign_structure` — Expanded Fields `get_campaign_structure` now surfaces `network_settings` (Search Partners, Display Expansion), EU political content eligibility, and geo target type for each campaign. `get_campaign_targeting` responses now include `resource_name` on each criterion row so you can pass exact IDs to `locations_to_remove`. ### Callout Extension Policy CTA words in callout extensions (e.g., "Learn More", "Sign Up") were previously silently dropped. They now generate a **warning** in the tool response instead of being removed — giving you visibility into which callouts were affected without blocking campaign creation. **Google Ads tool count: 89 → 92** **May 9, 2026** v2.17.3 ## TikTok Deep Overhaul, Google Ads Conversion Tools, and Meta Adset Performance ### TikTok Ads — Full SDK Overhaul + Layer 2 The TikTok integration received its largest overhaul since launch — every customer-blocking bug from production logs was closed and the platform's full API depth is now accessible. **Phase 0 — bug fixes (all customer-blocking):** Ad group spec re-architected to 86 fields; creative spec to 59 fields. Image direct-path skips base64 conversion. Slideshow (unsupported by TikTok) removed from code paths. ffmpeg added to Cloud Run for video frame extraction. 5 prod-harness-discovered bugs (pause schema, ValueError hints, image path, envelope, deletes) fixed. **Phase 1 — full SDK depth:** All 86 ad-group fields and 59 creative fields from TikTok's marketing API are now surfaced through `add_tiktok_ad_group` and `add_tiktok_ad`. Previously only a subset was accessible. **Layer-1 — validity matrix:** 6 common error classes are now caught *before* the API call — saving tool call quota and eliminating confusing API rejection messages. **Layer-2 — new tool and rich targeting:** | Tool | Type | Description | | - | - | - | | `explain_tiktok_objective` | Read | Given your goal (leads, sales, traffic, app installs), returns the correct TikTok campaign objective, recommended ad format, and validity constraints — eliminating trial-and-error | **Rich targeting** for `add_tiktok_ad_group` now supports interest filters, behavioral keywords, action categories, carrier/device targeting, and language filters — all available through `search_tiktok_targeting`. **Atomic rollback:** If campaign creation fails at any sub-step (ad group or ad level), previously-created resources are automatically rolled back. No more partial campaigns left in your account. ### Google Ads — Conversion Tracking Tools Two new tools for conversion analysis — separate from the existing `audit_conversion_tracking` health check: | Tool | Type | Description | | - | - | - | | `list_conversion_actions` | Read | List all conversion actions in your Google Ads account (purchases, form fills, phone calls, etc.) with status and tracking method | | `get_conversion_action_performance` | Read | Pull conversion metrics (volume, value, CPA) broken down by conversion action — see which actions are actually driving results | `get_campaign_targeting` is also expanded: it now returns all criterion types (location, language, audience, device, ad schedule, topic, content label) instead of just locations and languages. ### Google Ads — Ad-Group Extensions `add_sitelinks`, `add_callout_extensions`, and `add_structured_snippets` now accept an optional `ad_group_id` parameter. Extensions attached at the ad-group level override campaign-level extensions for that specific ad group — useful for ad groups targeting different products or audiences. ### Meta Ads — Ad Set Performance A new middle-layer analytics tool between campaign and ad level: | Tool | Type | Description | | - | - | - | | `get_meta_adset_performance` | Read | Pull spend, clicks, CTR, CPA, ROAS, and conversions broken down by ad set within a campaign — see which audience segments and placements are driving results before going to individual ad level | Previously, Meta performance tools showed either campaign-level (too broad) or ad-level (too granular) data. Ad set performance fills the gap for budget allocation decisions. ### Billing — Plan Management UI The **Billing** page now supports plan changes without contacting support: * **Downgrades** — Switch from Pro → Plus or Plus → Free directly from the billing page * **Interval switching** — Toggle between monthly and annual billing mid-cycle * **Max plan visibility** — Max plan capabilities and tool call limits are now shown inline on the billing page All plan changes go through Stripe Checkout (same flow as upgrades) for consistent billing history. **April 30, 2026** v2.17.2 ## Reconnect now resumes metric collection Fixed an issue where reconnecting an ad account after an authentication error wouldn't actually resume background metric collection. Previously, if Adspirer auto-paused an account because the platform returned a 401/403 (expired token, revoked permissions), reconnecting through the connections page issued a fresh OAuth token but left `metrics_collection_enabled` set to false — so daily collection kept skipping the account. Customers were effectively reconnecting for nothing. Reconnect flows for **Meta Ads, Google Ads, TikTok Ads, and LinkedIn Ads** now automatically clear auth-error pauses on the same user and platform once the new token is saved, restoring daily metric collection without manual intervention. Admin pauses, free-tier pauses, and other auto-pause types are untouched. **April 29, 2026** v2.17.1 ## Sequential sub-agents for Max plan Max plan users can now run sequential sub-agents across multiple active ad accounts in a single conversation. Instead of switching primary accounts one at a time, mark multiple accounts as active and let Adspirer fan out tool calls across each — perfect for agencies running cross-account audits, weekly briefs, or bulk optimizations from a single prompt. ### What's new * **Active accounts model** — Max users can have multiple ad accounts marked active per platform simultaneously. Lower tiers continue with the primary-account model. * **`list_connected_accounts`** — New system tool that returns every active account across platforms with IDs, names, and status. Reads directly from the database (zero API calls, doesn't count against your quota). * **Cross-account workflows** — A single prompt like "run last week's performance brief across all my Google Ads accounts" now triggers per-account sub-agents that aggregate into one consolidated response. * **Active set management** — Add or remove accounts from your active set at [adspirer.ai/connections](https://adspirer.ai/connections). ### Who this is for Agencies, portfolio managers, and anyone managing 3+ ad accounts who currently bounces between primaries. See the updated [Multi-Account Management guide](/docs/knowledge-base/multi-account#sequential-sub-agents-max-plan). **April 23, 2026** v2.17.0 ## Google Display Ads — end-to-end CRUD Full Google Display Network support joins Search, PMax, YouTube, and Demand Gen. Ships with 27 new MCP tools verified live against Google Ads API v21. Standard Display (full manual control) and Smart Display (Google-managed) are both supported. [Display Ads guide →](/docs/ad-platforms/google-display-ads) ### What's new * **`create_display_campaign`** — Standard Display (channel=DISPLAY) and Smart Display (sub\_type=DISPLAY\_SMART\_CAMPAIGN) with a single flag. Creates campaign + default ad group + Responsive Display Ad, all PAUSED. * **5 targeting surfaces — GET / ADD / REMOVE on each:** * `add_display_audiences` — In-market, affinity, custom audiences, user lists, combined audiences * `add_display_topics` — Google content categories * `add_display_placements` — Specific websites, apps, YouTube channels, YouTube videos * `add_display_keywords` — Contextual (always BROAD match on Display) * `update_display_demographics` — Age, gender, parental status, income exclusions * `remove_display_criteria` — Unified removal across all 5 surfaces * **Full CRUD:** `add_display_ad_group`, `add_display_ad`, `update_display_ad_creative` (colors, CTA, images, videos, promo, format\_setting), `update_display_ad_group`, `update_display_campaign_schedule`, `update_display_frequency_caps`, plus remove variants * **Geo + language resolvers** — `resolve_google_locations` and `list_google_languages` reject ambiguous inputs ("Baja" surfaces 5 candidates) instead of silently falling back to US. All Google campaign types benefit. * **RSA + RDA dispatch** — `update_ad_headlines`, `update_ad_descriptions`, and `update_ad_content` now dispatch on ad type. Responsive Search Ads (3–15 headlines, 2–4 descriptions) and Responsive Display Ads (1–5 headlines, 1–5 descriptions, plus `long_headline`) work side-by-side. * **`select_google_campaign_type`** — Now includes `'display'` and `'demandgen'` alongside `'search'`, `'pmax'`, and `'youtube'` with full decision-tree workflows. ### OpenClaw plugin update OpenClaw bumps to **v2026.4.13**. Tool count goes from 95 → 119 — adds all 22 Display Ads tools + 2 helpers. [OpenClaw agent guide →](/docs/agent-skills/openclaw-agent) ### Regressions None. RSA users see identical behavior plus clearer validator errors. PMax, Demand Gen, and YouTube still hit the same unchanged paths. **April 22, 2026** v2.16.0 ## REST API Reference now live Every Adspirer tool is now callable over plain HTTP and documented at [adspirer.com/docs/api-reference](/docs/api-reference/introduction). Same 178 endpoints as the MCP server — same auth, same quota, same write-guards — but over request/response JSON so consumers that can't speak SSE (n8n, Zapier, Make, cron jobs, GitHub Actions, your own backend) can use them. ### What's included * **178 auto-generated endpoint pages** grouped by platform: Google Ads (51), Meta Ads (36), LinkedIn Ads (45), TikTok Ads (29), monitoring (13), general (3), audit (1) * **Interactive "Try it" playground** — authorize once with your `sk_live_...` key, call any endpoint from the browser against the real API * **REST API overview** with use-case patterns for Slack ChatOps, daily account briefings, portfolio rollups, alert / auto-pause, SaaS product embedding, and headless CI * **Architecture sequence diagrams** for each pattern showing how ingress → Adspirer → egress wires up ### Base URLs | | | | :- | :- | | Endpoints | `https://api.adspirer.ai/api/v1/tools//execute` | | Swagger UI | [api.adspirer.ai/docs](https://api.adspirer.ai/docs) | | OpenAPI spec | [api.adspirer.ai/openapi.json](https://api.adspirer.ai/openapi.json) | ### Auth Pass your API key as `Authorization: Bearer sk_live_...` — same keys you already use for headless MCP. Generate one at [adspirer.ai/keys](https://adspirer.ai/keys). Free tier includes 15 calls / month. ### Idempotency Write operations accept an `Idempotency-Key` header. Strongly recommended for n8n, Zapier, and any retry-prone client — a repeated call with the same key returns the cached result instead of creating duplicates. **April 20, 2026** v2.15.5 ## Pay-as-you-go overage for Plus subscribers Plus plan subscribers no longer hit a hard stop at 150 tool calls. After your included calls are used, you can keep working at **$0.50 per additional call**, capped at **$50/month** in overage charges. ### How it works * Overage billing is **auto-enabled** for all Plus subscribers * Your first 150 calls are included in your \$49/month subscription * After 150 calls, each additional call is billed at \$0.50 through Stripe * Monthly overage is capped at $50 — your maximum bill is $99/month * Disable overage anytime from your billing page to revert to the previous behavior (hard stop at 150 calls) ### Usage notifications * At **135 calls** (90%): one-time notification that overage billing kicks in after 150 * At **151 calls**: one-time notification that you're now on usage-based billing * All other overage calls: no interruptions — just keep working ### Tier-specific messaging * **Plus:** Minimal notifications during overage — you're paying for usage, so no nagging * **Pro:** Usage stats shown without upgrade prompts * **Max:** No usage hints — high included limit, don't worry about it See the updated [Pricing & Tool Calls](/docs/knowledge-base/pricing#overage-billing-plus-plan) page. **April 16, 2026** v2.15.4 ## Raw data mode for all performance tools All 29 performance and analytics tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads now accept a `raw_data` parameter. When set to `true`, tools return a compact JSON code block with only raw metrics (spend, clicks, impressions, conversions, CPA, CPC, CTR, CVR, ROAS) — stripped of severity labels, suggested bids/budgets, industry benchmarks, and optimization recommendations. **Default behavior is unchanged.** Existing markdown output with recommendations is returned unless you explicitly pass `raw_data=true`. ### When to use raw data mode * You run your own attribution model and want raw numbers only * You want to minimize token usage in AI client responses * You're piping metrics into a spreadsheet, dashboard, or external tool ### Supported tools | Platform | Tools with `raw_data` support | | - | - | | Google Ads | `get_campaign_performance`, `analyze_wasted_spend`, `optimize_budget_allocation`, `analyze_search_terms`, `explain_performance_anomaly` | | Meta Ads | `analyze_meta_campaign_performance`, `analyze_meta_ad_performance`, `analyze_meta_wasted_spend`, `optimize_meta_budget`, `analyze_meta_audiences`, `detect_meta_creative_fatigue`, `optimize_meta_placements`, `explain_meta_anomaly`, `get_meta_audience_insights` | | LinkedIn | `get_linkedin_campaign_performance`, `analyze_linkedin_engagement`, `get_linkedin_audience_insights`, `analyze_linkedin_wasted_spend`, `optimize_linkedin_budget`, `explain_linkedin_anomaly`, `analyze_linkedin_creative_performance` | | TikTok | `get_tiktok_campaign_performance`, `get_tiktok_ad_performance`, `analyze_tiktok_wasted_spend`, `optimize_tiktok_budget`, `detect_tiktok_creative_fatigue`, `explain_tiktok_anomaly`, `get_tiktok_audience_insights`, `analyze_tiktok_geo_performance` | ### Example ``` "Show me last 30 days campaign performance with raw data" ``` The tool returns a fenced JSON block like: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "campaigns": [ { "name": "Brand Search - US", "spend": 1250.00, "clicks": 3400, "impressions": 45000, "conversions": 85, "cpa": 14.71, "cpc": 0.37, "ctr": 0.0756, "roas": 4.2 } ] } ``` ### Free tier access fix Free-tier users who previously had a failed or paused Stripe subscription attempt were incorrectly blocked from using MCP tools. This is now fixed — free-tier users are gated only by their usage quota, as intended. **April 16, 2026** v2.15.3 ## TikTok Ads: correct optimization event values The `optimization_event` parameter on `create_tiktok_campaign`, `add_tiktok_ad_group`, and `add_tiktok_ad` previously listed invalid values (`SUBMIT_FORM`, `ADD_TO_CART`, `VIEW_CONTENT`, `COMPLETE_REGISTRATION`, `DOWNLOAD`, `CONTACT`, `BUTTON_CLICK`) that TikTok's API would reject. **Correct values you should use:** | Old (invalid) | New (correct) | Meaning | | - | - | - | | `SUBMIT_FORM` | `FORM` | Form submission | | `ADD_TO_CART` | `ON_WEB_CART` | Add to cart | | `VIEW_CONTENT` | `ON_WEB_DETAIL` | View content / product page | | `COMPLETE_REGISTRATION` | `ON_WEB_REGISTER` | Registration | | `DOWNLOAD` | `DOWNLOAD_FINISH` | App or file download | | `CONTACT` | `CONSULT` | Contact / consultation | | `BUTTON_CLICK` | `CLICK_LANDING_PAGE` | Landing page click | Additional supported values: `COMPLETE_PAYMENT`, `CONVERSION_LEADS`, `PAGE_VISIT`, `PHONE_CONNECT`, `SEARCH`, `SUBSCRIBE`, `INITIATE_ORDER`, `ON_WEB_SUBSCRIBE`. If you were passing the old values and getting TikTok API errors, update to the new values above. **April 13, 2026** v2.15.2 ## TikTok Ads: campaign creation reliability 5 fixes to TikTok campaign creation from production testing. * **Spark Ads now work with `create_tiktok_campaign`** — creating campaigns with a `tiktok_item_id` (Spark Ads) or `card_id` (Carousel) no longer fails with "Unknown error". Spark and Carousel ads are now created directly without requiring an image upload. * **All TikTok CTAs accepted** — previously, only 6 call-to-action values (like LEARN\_MORE and SHOP\_NOW) were allowed. Now any CTA supported by TikTok works — including CONTACT\_US, BOOK\_NOW, GET\_QUOTE, and others. TikTok validates CTAs server-side. * **Automatic placement fix** — campaigns using automatic placement no longer fail with "Missing required field(s): placements." * **TikTok page URL detection** — passing a TikTok page URL (e.g., `https://tiktok.com/@user/video/123`) as a video URL now returns a clear error explaining you should use `tiktok_item_id` for Spark Ads or provide a direct MP4/MOV link. * **CTA auto-default** — when creating an ad with a `landing_page_url` but no `call_to_action`, Adspirer now defaults to LEARN\_MORE instead of failing with "External\_URL and Call\_to\_action must exist together." ## Meta Ads: disclaimer acceptance before connecting When connecting your Meta Ads account, you now see a disclaimer checkbox after entering your email. You must accept the disclaimer — confirming you understand that Adspirer operates independently from Meta's account enforcement systems — before the Connect button becomes available. Acceptance is recorded for compliance purposes. See [Connecting Meta Ads](/docs/ad-platforms/meta-ads#connecting-meta-ads). The Meta Ads page and [Security](/docs/knowledge-base/security#what-this-means) page also now confirm Adspirer has Meta approved **Ads Management Standard Access**, so users know the app is verified by Meta to use the Marketing API. ## Platform Terms & Conditions New users now accept Platform Terms & Conditions as part of onboarding before connecting ad accounts. The terms cover account authorization requirements, rate limit safeguards, platform enforcement policies, financial responsibility, and liability. This replaces the previous per-platform disclaimer prompts with a single, comprehensive agreement. ## Faster email support Email support response time improved from 1 business day to **2–4 hours** (San Francisco / PST). Reach us at [support@adspirer.com](mailto:support@adspirer.com). **April 8, 2026** v2.15.1 ## Meta Ads: expanded tool coverage (21 → 36) Meta Ads now has **36 tools** (up from 21), covering the full campaign lifecycle — from browsing and creation to ad set management, creative rotation, and lead form submissions. ### New tools * **Ad set & ad management:** `add_meta_ad_set`, `add_meta_ad`, `update_meta_ad_set`, `update_meta_ad`, `list_meta_ad_sets`, `list_meta_ads` * **Campaign management:** `list_meta_campaigns`, `get_meta_campaign_details`, `duplicate_meta_campaign`, `resume_meta_campaign` * **Creative & lead gen:** `create_meta_dco_ad` (Dynamic Creative Optimization), `get_meta_ad_creatives`, `list_meta_lead_forms`, `get_meta_lead_form_submissions` * **Account discovery:** `list_meta_instagram_accounts`, `list_meta_pixels` * **Analytics:** `analyze_meta_wasted_spend`, `get_meta_audience_insights` ### Monitoring improvements * `create_monitor` now lists all 15 supported metrics (roas, ctr, cpc, cpa, cpm, cpv, spend, conversions, impressions, clicks, cost\_per\_lead, conversion\_rate, budget\_utilization, video\_views, engagement\_rate) * Advanced monitoring: AND/OR logic across multiple conditions, consecutive-day triggers, relative thresholds, percentage change detection, campaign-level targeting, and auto-actions (pause campaign, adjust budget) ## Meta Ads: ad set parity and custom audience reliability ### `add_meta_ad_set` now supports all campaign-level features When adding ad sets to existing Meta campaigns, you can now use the same parameters that were previously only available at campaign creation: * **Lifetime budgets** — set `budget_lifetime` on individual ad sets * **End dates** — set `end_time` on ad sets (required when using lifetime budgets) * **Multi-advertiser opt-out** — control `multi_advertiser` per ad set * **Granular placements** — set `publisher_platforms`, `facebook_positions`, and `instagram_positions` per ad set ### Custom conversion tracking fix `custom_conversion_id` is now properly decomposed into its underlying pixel and event configuration before being sent to Meta. Previously, passing a custom conversion ID could cause a Meta API error on campaign or ad set creation. Adspirer now automatically resolves the conversion via the Meta API and applies the correct pixel ID and event type. ### `list_meta_custom_audiences` reliability * Timeout increased from 30 seconds to 90 seconds — accounts with 1,000+ audiences no longer time out * Audience status now displays as clean labels ("Active", "Paused") instead of raw SDK objects **April 7, 2026** v2.15.0 ## TikTok Ads: full performance analytics 8 new performance analytics tools bring TikTok to parity with Google and Meta for campaign analysis. Total TikTok tools: 4 → 31. ### New analytics tools | Tool | Description | | - | - | | `get_tiktok_campaign_performance` | Campaign summary with TikTok-specific video and engagement metrics | | `get_tiktok_ad_performance` | Ad-level analysis with hook rate, video completion, and engagement | | `analyze_tiktok_wasted_spend` | ROAS-based waste detection with campaign status awareness | | `optimize_tiktok_budget` | LP-based budget allocation recommendations | | `detect_tiktok_creative_fatigue` | Hook rate decline as the primary fatigue signal | | `explain_tiktok_anomaly` | Statistical deviation detection with TikTok-specific metrics | | `get_tiktok_audience_insights` | Age/gender breakdown with CPA ranking | | `analyze_tiktok_geo_performance` | Country-level performance analysis | ### TikTok now fully available TikTok Ads is no longer marked "Coming Soon" during onboarding. You can connect your TikTok Ads account directly from the setup flow. **April 5, 2026** v2.14.1 ## TikTok campaign management and creation 19 new tools for full campaign lifecycle management on TikTok — from campaign creation through ad group and ad management, including Spark Ads, Carousel, and APP\_PROMOTION support. ### New campaign management tools (12) * `list_tiktok_campaigns` — List all campaigns with status, objective, and budget * `get_tiktok_campaign_details` — Detailed campaign info * `pause_tiktok_campaign` / `resume_tiktok_campaign` — Control campaign status * `update_tiktok_campaign` — Update name, budget, budget mode * `list_tiktok_ad_groups` / `pause_tiktok_ad_group` / `resume_tiktok_ad_group` / `update_tiktok_ad_group` — Full ad group management * `list_tiktok_ads` / `pause_tiktok_ad` / `resume_tiktok_ad` — Ad-level management ### New campaign creation tools (7) * `add_tiktok_ad_group` — Add ad groups with full targeting to existing campaigns * `add_tiktok_ad` — Add ads to existing ad groups (image, video, Spark Ads, Carousel) * `create_tiktok_carousel_card` — Create carousel cards from multiple images * `upload_tiktok_images` — Upload images to TikTok Asset Library * `search_tiktok_targeting` — Search interests, keywords, regions, languages, action categories, carriers, and device models ### New ad formats * **Spark Ads** — Boost existing TikTok organic posts as ads * **Carousel Ads** — Multi-image carousel format * **APP\_PROMOTION** — App install campaign objective with app ID configuration ### Campaign Budget Optimization (CBO) TikTok campaigns now support `budget_optimize_on` for campaign-level budget optimization. TikTok CBO is on by default — set to `false` to manage budgets per ad group manually. ### Google Ads fixes * `get_campaign_targeting` — New tool to view location targeting on existing campaigns * `get_campaign_structure` — Now paginated for large accounts * `analyze_search_terms` — New `raw_report` mode shows actual search terms users type into Google * Keyword removal now validates IDs before attempting deletion, with per-keyword error reporting **April 3, 2026** v2.13.1 ## LinkedIn Ads overhaul + Meta Ads gaps closed ### LinkedIn campaign hierarchy and targeting Complete overhaul of LinkedIn campaign tools with campaign group support, rollback logic, and 14 new targeting facets. * **Campaign groups** — `campaign_group_id` and `campaign_group_name` on all create tools. New `add_linkedin_campaign_to_group` tool for adding campaigns to existing groups. * **Carousel creatives** — New `add_linkedin_carousel_creative` tool * **Creative naming** — `creative_name` field added to all 4 campaign creation tools * **14 new targeting facets** — skills, job functions, interests, degrees, fields of study, employers, groups, age ranges, genders, schools, member behaviors, years of experience, followed companies, and buyer groups. All facets work on both create and update. * **Video discovery** — Now finds videos uploaded via LinkedIn Campaign Manager UI, not just API uploads * **Rollback logic** — Failed campaigns are automatically archived to prevent duplicates on retry * **Campaign filtering** — `list_linkedin_campaigns` now filters by campaign group ### Meta Ads: 6 critical gaps * **Lifetime budgets** — Set `budget_lifetime` at campaign creation (mutually exclusive with daily budget) * **End dates** — `end_time` support on campaigns and ad sets * **Custom audiences** — New `list_meta_custom_audiences` tool for viewing database lists, lookalikes, website, and engagement audiences * **Granular placements** — Control `publisher_platforms`, `facebook_positions`, and `instagram_positions` at campaign creation * **Multi-advertiser opt-out** — New `multi_advertiser` field to opt out of Meta's multi-advertiser ads * **Custom conversion tracking** — Fixed `custom_conversion_id` being silently dropped on image and carousel campaigns ### Monitoring * New `delete_monitor` tool — Previously, deleting monitors required knowing about `manage_scheduled_task`, which AI clients couldn't discover **April 3, 2026** v2.13.0 ## Gemini CLI Extension Adspirer is now available on the [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/?name=amekalaads-mcp). Google's terminal-based AI tool can now manage your ad campaigns across all 4 platforms. ### Install ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} gemini extensions install https://github.com/amekala/ads-mcp ``` ### What's Included * **MCP Server** — 100+ tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads * **5 Slash Commands** — `/adspirer:setup`, `/adspirer:performance-review`, `/adspirer:write-ad-copy`, `/adspirer:wasted-spend`, `/adspirer:refresh` * **OAuth authentication** — browser opens automatically on first use See the full [Gemini CLI Setup Guide](/docs/ai-clients/gemini-cli). **March 30, 2026** v2.12.0 ## Official Claude Plugin Adspirer is now an **official plugin** in the Claude plugin marketplace (`claude-plugins-official`). Available on both [Claude Code](/docs/ai-clients/claude-code) and [Claude Cowork](/docs/ai-clients/claude-cowork). ### What Changed * **No more custom marketplace setup.** Previously, you had to manually add the `amekala/ads-mcp` marketplace before installing. Now just search for "adspirer" in the plugin browser. * **Claude Code:** Type `/plugin`, search "adspirer", and install `adspirer-ads-agent` directly. Or run `/plugin install adspirer-ads-agent`. * **Claude Cowork:** Go to Customize → Browse Plugins and search for "adspirer" — install with one click. * **Plugin page:** [claude.com/plugins/adspirer-ads-agent](https://claude.com/plugins/adspirer-ads-agent) ### What's Included The official plugin bundles everything in a single install: * **MCP Server** — 100+ tools across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads * **5 Slash Commands** — `/setup`, `/performance-review`, `/write-ad-copy`, `/wasted-spend`, `/refresh-brand-context` * **2 Skills** — Ad campaign management and best practices * **1 Agent** — Performance marketing agent with safety rules Updated setup guides for [Claude Code](/docs/ai-clients/claude-code) and [Claude Cowork](/docs/ai-clients/claude-cowork) to reflect the simplified installation flow. **March 25, 2026** v2.11.0 ## Lead Gen Campaign Support Full lead generation support across Google Ads and Meta Ads — performance analysis, wasted spend, and audience tools now handle lead gen campaigns correctly. ### Google Ads Lead Gen * Performance analysis, wasted spend, and audience tools now work for campaigns optimized for leads. Previously, tools could crash or show incorrect metrics for lead gen campaigns. * Conversion metrics now use primary conversions only (`metrics.conversions`), matching what you see in the Google Ads UI. Previously, Adspirer reported all conversions including secondary actions, which inflated numbers. * PMax search themes now correctly apply to the specified asset group, not the first one found. ### Meta Ads Lead Gen * All performance tools — `analyze_meta_campaign_performance`, `analyze_meta_ad_performance`, `get_meta_wasted_spend`, and audience analysis — now support lead gen campaigns (OUTCOME\_LEADS optimization). * CPA calculation now uses the ad set's optimization event instead of dividing by total conversions. If you're optimizing for leads, CPA reflects cost-per-lead, not cost-per-all-actions. * Audience CPA sort order now shows lowest CPA first for lead gen campaigns. ### Audience Search Fix * `search_audiences` now returns results for multi-word queries (e.g., "digital marketing" or "home improvement"). Previously, multi-word searches returned zero results, causing AI clients to fabricate audience IDs. * DemandGen and YouTube tools now validate audience segment IDs against the API instead of accepting AI-generated IDs that don't exist. ### OpenClaw Plugin Fix Fixed empty-argument bug affecting all 143 tools. The OpenClaw plugin now ships complete input schemas, so tools receive the parameters you provide instead of empty objects. ### Faster Tool Responses * Google Ads account list cached in Redis (3-minute TTL) — subsequent tool calls skip the account discovery API call. * All Google Ads data cache TTLs increased to 10 minutes — repeat queries (e.g., checking campaign performance twice) return instantly from cache. **March 24, 2026** v2.10.0 ## Google Ads Rate Limit Fix & MCC Reliability ### Rate Limit Resolution (P0) Fixed a critical issue where Google Ads API rate limits (HTTP 429) could block **all users** — not just the affected account. The system now caches account list responses and includes an emergency recovery endpoint. Users who were seeing "Resource has been exhausted" errors should no longer be affected by other accounts' API usage. ### MCC Account Fixes * Child accounts under MCC (My Client Center) manager accounts now correctly resolve their `login_customer_id` during onboarding and tool calls. Previously, some MCC child accounts would fail with "The caller does not have permission" errors. * Direct (non-MCC) accounts are no longer incorrectly mapped to an MCC manager, which caused "customer not found" errors for users with standalone ad accounts. * `login_customer_id` is now stored in the database, eliminating a `ListAccessibleCustomers` API call on every tool call — faster and more reliable. ### Meta Ads CPA Fix CPA for Meta campaigns now uses the ad set's optimization event (e.g., cost per lead, cost per purchase) instead of dividing spend by total conversions. This was especially inaccurate for lead gen campaigns where secondary events inflated the denominator. **March 22, 2026** v2.9.7 ## Error Clarity, LinkedIn & Meta Fixes ### Google Ads Error Messages * Centralized error parsing across all 18 Google Ads write operations. Errors now show the specific field and issue (e.g., "headline exceeds 30 characters") instead of raw API codes. * `add_keywords` now detects policy violations (trademark, restricted content) and provides specific guidance. * `update_bid_strategy` returns actionable error details when a strategy change fails, instead of just the strategy name. ### LinkedIn Improvements * `search_linkedin_targeting` now uses LinkedIn's typeahead API for better, faster targeting search results. Facet names (job title, company, industry) are correctly mapped to LinkedIn's API format. * Fixed parameter mismatches, null handling, and error parsing across LinkedIn Ads tools. ### Meta Ads Fixes * `add_meta_ad` and `add_meta_ad_set` now honor the name you provide. Previously, the user-provided name was silently ignored. * `add_keywords` routing fix — calls now use the correct code path with policy violation detection. ### OAuth Fix Fixed a 500 error on the OAuth authorization page. Users connecting via ChatGPT or Claude would see a server error instead of the consent screen. **March 21, 2026** v2.9.6 ## LinkedIn Creatives & Campaign Enhancements ### LinkedIn Creatives * Fixed `list_linkedin_creatives` returning empty results for large accounts (22,000+ creatives). Pagination now handles all account sizes correctly. * Fixed duplicate creatives appearing in results due to pagination overlap. * Rewrote creative filtering to use LinkedIn's server-side FINDER API, eliminating timeouts on campaign-level creative lookups. * Fixed LinkedIn metrics silently dropping to zero, MCP timeout on large result sets, and pagination breaking on no-match scenarios. ### Google Ads Campaign Extensions * Added `MAXIMIZE_CONVERSION_VALUE` as a supported bidding strategy for all campaign types. * Extensions (sitelinks, callouts, snippets) are now added in a single batch operation instead of individually, reducing API calls and errors. * Automatic retry on `CONCURRENT_MODIFICATION` errors when multiple operations target the same campaign. ### PMax, Demand Gen & YouTube Your business logo is now automatically injected into PMax, Demand Gen, and YouTube campaigns during creation — no need to provide it manually if one exists at the account level. ### Monitoring Fixed `create_monitor` using a 30-minute default check interval, which was below the API minimum of 1,440 minutes (24 hours). Monitors now default to a valid interval. **March 21, 2026** v2.9.5 ## Perplexity Computer Support ### New AI Client: Perplexity Adspirer now supports [Perplexity](/docs/ai-clients/perplexity) as an AI client via MCP connector. Connect Adspirer to Perplexity Computer — the autonomous AI agent — and combine real-time web research with 100+ advertising tools. * **OAuth setup** — Add Adspirer as a custom connector in Perplexity Computer → Connectors. OAuth auto-discovery means zero configuration beyond the URL. * **Search + ads** — Perplexity's native web search lets you research competitors and market trends, then immediately act on that research using Adspirer tools. No other client combines real-time search with ad management this seamlessly. * **Perplexity Computer** — Max subscribers get autonomous multi-step workflows: research → create → optimize, all from a single prompt. * **Requires** Perplexity Pro ($20/mo), Max ($200/mo), or Enterprise. Updated all documentation pages, Knowledge Base, and cross-references to include Perplexity as a supported AI client. **March 21, 2026** v2.9.4 ## Audience Targeting Fixes for Demand Gen, YouTube & PMax ### Custom Interest Audiences Now Work in Demand Gen & YouTube Custom interest audiences (custom segments) were not being applied when creating Demand Gen or YouTube campaigns — even though the tool response showed them as set up. Remarketing audiences worked correctly, but custom interest targeting was silently dropped. This is now fixed. All audience segment types (in-market, affinity, custom audiences, and remarketing lists) work consistently across PMax, Demand Gen, and YouTube campaigns. ### PMax: No More Unwanted Search Themes on Remarketing Campaigns When creating a PMax campaign with only remarketing audiences and no search themes, the system was auto-generating search themes from your ad headlines. If you only ask for audience targeting, search themes will no longer be added automatically. **March 19, 2026** v2.9.3 ## Stable MCP Sessions ### No More Intermittent "Invalid Token" Errors Fixed an issue where some tool calls would randomly fail with "Invalid or expired token" — especially after being idle for a while. Sessions are now resilient to Clerk session expiry. If a session token becomes stale, the system automatically recovers without requiring you to reconnect. **March 18, 2026** v2.9.2 ## Billing & Onboarding UX ### Billing Page * Fixed pricing display and plan comparison layout * Fixed broken navigation between billing sections * Improved upgrade/downgrade CTA logic ### Onboarding * Fixed layout and scroll issues on onboarding screens * Plan tier messaging now accurately reflects current pricing * Save badge visibility fixed **March 17, 2026** v2.9.1.1 ## Automation Tools: Multi-Platform Fix Scheduled briefs, monitoring alerts, and on-demand reports now work correctly for **all platforms** — Meta Ads, LinkedIn Ads, and TikTok Ads. Previously, automation tools only worked reliably for Google Ads. Monitors set to track "all platforms" were silently resolving to zero accounts. **March 16, 2026** v2.9.1 ## Persistent MCP Sessions & Faster Auth ### No More Frequent Reconnects MCP access tokens now last **1 week** instead of 1 hour. Claude, ChatGPT, Codex, and Cursor sessions stay authenticated much longer — no more "Error occurred during tool execution" after stepping away for an hour. Diagnostic tools (`get_usage_status`, `get_connections_status`) remain available even when your quota is exhausted, so you can always check your account status. ### Faster Tool Responses Added an in-process auth cache that eliminates repeated token verification overhead. Subsequent tool calls in the same session resolve authentication instantly instead of re-verifying on every request. ### Manus AI Client Support New setup guide for connecting Adspirer to [Manus](/docs/ai-clients/manus) — the autonomous AI agent. Manus connects via API key authentication with Streamable HTTP transport. Import Adspirer skills directly from GitHub for campaign management workflows. ### Meta Ads Fix Meta tools now always pass the correct connected ad account ID. Previously, some Meta tools could fail with "No ad account found" even when an account was connected. ### LinkedIn Ads Fix Fixed currency formatting for LinkedIn campaign metrics. Campaigns with non-USD currencies now display correctly instead of showing raw API values. ### Faster Google Ads Account Loading Google Ads account connections now load with lazy pagination and parallel processing. The connections page loads instantly instead of waiting for all accounts to resolve. **March 15, 2026** v2.9.0 ## Quota Experience & Error Clarity Completely overhauled how Adspirer communicates quota limits and errors across all AI clients. ### Usage Warnings Before You Hit the Wall Tool responses now include a visible usage footer when you're approaching your quota limit: * **75%+ usage** — `📊 12/15 free calls used (80%) — 3 remaining. Upgrade: ...` * **90%+ usage** — `🚨 2 calls remaining! Upgrade now to avoid interruption: ...` Previously, usage warnings were only visible in ChatGPT's widget. Now they appear on **all clients** — Claude, Claude Code, Cursor, Codex, and ChatGPT. ### Diagnostic Tools Always Available `get_usage_status`, `get_connections_status`, and `echo_test` now work even when your quota is exhausted. You can always check your usage and connection status regardless of your remaining calls. These tools don't count against your quota. ### Clear Error Messages * **Quota exceeded** — shows a clean upgrade message with pricing and payment link (previously showed a generic "Error occurred during tool execution" on Claude) * **Session expired** — now tells you exactly what happened and how to reconnect (previously showed the same generic error) * **Server errors** — include the actual error details and retry guidance **March 14, 2026** v2.8.2 ## Demand Gen: Multi-Region Ad Groups Add ad groups to existing Demand Gen campaigns with `add_demandgen_ad_group`: * Each ad group can target **different locations** (e.g., US cities vs India cities vs UAE cities) * Each ad group can have its own **audience signals** (in-market + affinity segments) * Reuse existing account images and YouTube videos across ad groups * Different creative variations per ad group ### Meta Ads: City Targeting & Placement Creatives * **City-level targeting** — target specific cities in Meta campaigns with `search_meta_targeting` * **Placement-specific creatives** — upload different images for Feed, Stories, and Reels placements * **Emoji support** — use emoji in Meta ad headlines and descriptions ### AI Client Input Resilience Adspirer now handles common input mistakes from AI clients automatically: * JSON strings sent as text instead of objects are auto-parsed * Integer IDs sent instead of strings are auto-coerced * Extra whitespace and unknown fields are silently handled * Works across all 100+ tools — no more validation errors from formatting issues **March 12, 2026** v2.8.1 ## PMax: Multiple Asset Groups & Bidding Control * **Multiple asset groups per campaign** — create campaigns with distinct asset groups for different product lines or audiences * **Bidding strategy control** — your explicit bidding choice (Maximize Conversions, Target ROAS, etc.) is now always honored * **Auto-derived search themes** — search themes are automatically suggested from your headlines and descriptions * **Post-creation nudge** — after creating a PMax campaign, you're prompted to add search themes and audience signals **March 10, 2026** v2.8.0 ## Demand Gen Campaign Creation Full support for Google Demand Gen campaigns — reach users across YouTube, Discover, Gmail, Display, and Maps from a single campaign. Create Demand Gen campaigns with `create_demandgen_campaign`: * **Multi-asset format** — landscape, square, and portrait images with headlines and descriptions * **Video responsive format** — YouTube videos with text overlays * Automatic sitelink, callout, and structured snippet extensions * Location and language targeting at the campaign level * All bidding strategies supported: Maximize Clicks, Maximize Conversions, Target CPA, Target ROAS ### Audience Targeting * In-market and affinity audience segments via `search_audiences` * Reuse existing audiences from Google Ads UI * Per-ad-group audience customization ### Meta Ads Fixes * Fixed lead form handling for OUTCOME\_LEADS and OUTCOME\_ENGAGEMENT campaigns * Fixed Meta page and Instagram account lookup for business accounts * Wasted spend analysis now respects learning phase and minimum spend thresholds **March 11, 2026** v2.7.0 ## PMax Search Themes & Audience Signals Added 7 new tools for managing search themes and audience signals on Google Ads Performance Max campaigns. These PMax-only features give you direct control over how Google's automation targets search queries and audience segments. ### New Tools | Tool | Type | Description | | - | - | - | | `add_pmax_search_themes` | Write | Add search themes to guide PMax targeting (max 50 per asset group) | | `get_pmax_search_themes` | Read | View current search themes on a PMax campaign | | `remove_pmax_search_themes` | Write | Remove specific search themes | | `add_pmax_audience_signal` | Write | Add audience signal combining in-market, affinity, custom audiences, and user lists | | `get_pmax_audience_signals` | Read | View current audience signals | | `remove_pmax_audience_signal` | Write | Remove an audience signal | | `search_audiences` | Read | Search for audiences by keyword across all Google Ads audience types | ### Search Themes Short phrases (max 50 per asset group) that tell Google which search queries your PMax campaign should target. They supplement Google's automated targeting with explicit intent signals. Supports add and remove operations — to update, remove and re-add. ### Audience Signals Tell Google which audience segments are most likely to convert. Combine multiple segment types in a single signal: * **In-market audiences** — users actively researching products in a category * **Affinity audiences** — users with sustained interests and habits * **Custom audiences** — account-level custom audience segments * **User lists** — first-party data (website visitors, customer lists, CRM uploads) Only one audience signal per asset group. Signals are suggestions, not hard targeting — Google uses them as starting points and expands. ### Agent Skills Updated The Ad Campaign Management skill and Performance Marketing Agent now include search themes and audience signals in the PMax campaign creation workflow (steps 9-10). The agent will automatically recommend search themes based on keyword research and suggest relevant audience segments. ### Bug Fixes * Fixed GAQL query syntax for asset group signals (`campaign.id` instead of `asset_group.campaign.id`) * Fixed audience search returning zero results (replaced case-sensitive GAQL LIKE with client-side filtering + `taxonomy_type` enum) * Added `user_list_ids` support for remarketing lists in audience signals * Increased max search themes from 25 to 50 (Google's actual limit) **March 7, 2026** v2.6.0 ## API Key Authentication (Personal Access Tokens) Adspirer now supports **Personal Access Tokens** for headless and remote server authentication. Generate API keys from the dashboard and use them on remote servers, Docker containers, and CI/CD pipelines where browser-based OAuth isn't available. ### What's New * **API Key Management UI** — Generate, name, and revoke API keys from [adspirer.ai/keys](https://adspirer.ai/keys) * **OpenClaw `--token` flag** — `openclaw adspirer login --token sk_live_...` for headless authentication * **`ADSPIRER_API_KEY` env var** — Set the environment variable for zero-config server authentication * **Tier-based key limits** — Free: 2 keys, Plus: 5, Pro: 10, Max: 20 * **Key expiration** — Optional expiration (30 days, 90 days, 1 year, or never) * **Admin controls** — Admin dashboard for API key analytics, per-user key management, and emergency revocation * **Auth method tracking** — Tool call logs now track whether each call used OAuth or an API key ### Security * Keys use `sk_live_` prefix for easy identification * SHA-256 hashed storage — raw tokens never stored server-side * Instant revocation with audit trail * Keys cannot be used to create other keys (prevents privilege escalation) ### Documentation * [OpenClaw Remote Server Setup](/docs/ai-clients/openclaw#remote-server-setup) — Step-by-step guide * [Security — API Key Authentication](/docs/knowledge-base/security#api-key-authentication) — Security model and comparison * Updated [How MCP Works](/docs/mcp) — Authentication section * Updated [FAQ](/docs/knowledge-base/faq) — Remote server and API key questions **March 5, 2026** v2.5.0 ## Claude Cowork Setup Guide New documentation page with step-by-step visual guide for connecting Adspirer to [Claude Cowork](/docs/ai-clients/claude-cowork). Includes 9 annotated screenshots covering the full flow: plugin install from marketplace, connector setup, OAuth authentication, and brand folder workspace. ### Claude Connector Simplified [Claude Chat setup](/docs/ai-clients/claude) no longer requires manual OAuth configuration. Just paste the URL — Claude auto-discovers the server name and authentication settings. ### ChatGPT Setup Updated [ChatGPT setup](/docs/ai-clients/chatgpt) updated to match current UI: new field names, OAuth advanced settings callout, "I understand and want to continue" checkbox, and the new **Reference memories and chats** preferences screen. **March 3, 2026** v2.4.0 ## LinkedIn Exhaustive Campaign Features Extended LinkedIn campaign tools with exhaustive targeting and management capabilities. Fixed Google `list_campaign_extensions` returning incorrect data. ### Database Performance Phase 1 database performance improvements for faster query execution across campaign metrics and user analytics. ### Documentation: Agent Pages & Support Added 8 new documentation pages: * **[Claude Code Agent](/docs/agent-skills/claude-code-agent)**, **[Cursor Agent](/docs/agent-skills/cursor-agent)**, **[Codex Agent](/docs/agent-skills/codex-agent)**, **[OpenClaw Agent](/docs/agent-skills/openclaw-agent)** — per-client agent architecture docs * **[How It Works](/docs/how-it-works)** — 5-layer architecture page * **[FAQ](/docs/knowledge-base/faq)**, **[Glossary](/docs/knowledge-base/glossary)**, **[Support](/docs/knowledge-base/support)** — knowledge base expansion * Added Support tab to top navigation **February 28, 2026** v2.3.0 ## Pricing V2 Updated pricing across all tiers: | Plan | Price | Tool Calls | | - | - | :-: | | **Free** | \$0/mo | 15/month | | **Plus** | \$49/mo | 150/month | | **Pro** | \$99/mo | 600/month | | **Max** | \$199/mo | 3,000/month | * Annual pricing option now available with savings * Tool call counter resets to 0 on tier upgrade * Fixed subscription cancellation on upgrade to prevent double-billing * Stripe webhook handlers now sync quota correctly ### MCC/Manager Account Warnings Connections page now warns users attempting to connect MCC (Google) or Business Manager (Meta) accounts instead of individual ad accounts. ### OpenClaw Plugin Updates * `openclaw adspirer uninstall` CLI command added * OAuth retry logic improved * Skill metadata updated with security section and privacy policy **February 27, 2026** v2.2.1 ## Skill Reference & Performance Marketing Agent Docs Added 2 new pages to the Agent Skills section: * **[Skill Reference](/docs/agent-skills/skills)** — Complete reference for all 5 Adspirer skills with invocation commands per IDE (Claude Code, Cursor, Codex), step-by-step execution details, and example prompts * **[Performance Marketing Agent](/docs/agent-skills/agent)** — How the agent orchestrates skills with brand knowledge, strategy persistence, and memory across sessions ### Strategy-Aware Execution Skills now read `STRATEGY.md` before executing — a persistent file where strategic decisions (AVOID, PREFER, CONSTRAINT, REQUIRE directives) survive across sessions: * **Campaign creation** loads strategy directives at Step 0 and flags conflicts with research results * **Keyword research** cross-references results against AVOID/PREFER directives * **Performance review** flags "Strategy Drift" when campaigns violate active directives * **Wasted spend** prioritizes campaigns violating strategy as waste sources ### Agent Documentation Highlights * Mermaid architecture diagram showing Agent → Context + Strategy + Memory → Skills → Tools → Platforms * IDE comparison table for agent features across Claude Code, Cursor, and Codex * Brand Workspace setup flow and context file structure * Cursor Rules and Codex Safety Rules explained with before/after examples **February 26, 2026** v2.2.0 ## Asset Discovery & PMax Validation * Fixed asset discovery across platforms * YouTube logo upload support for PMax campaigns * Mandatory extensions enforcement for Google Ads * PMax logo validation improvements ### CLI OAuth Fix Resolved OAuth failures for CLI clients (Claude Code, Codex). Loopback redirect now correctly routes web vs CLI authentication flows. ### Cross-Domain Attribution Added referrer-based UTM fallback for cross-domain tracking between adspirer.com and adspirer.ai. ### Help & Contact Page Added in-app Help page with documentation link and contact options. **February 22, 2026** v2.1.0 ## YouTube Ads Campaign Support Added YouTube Ads campaign creation to the Google Ads toolset. Create video ad campaigns targeting YouTube viewers with budget controls and audience targeting. ### Automation Tools Launched 8 automation tools: * **Scheduled briefs** — automated performance summaries on a recurring schedule * **Performance monitors** — alerts when campaigns cross KPI thresholds * **Cross-platform reports** — unified reporting across Google, Meta, and LinkedIn ### UI Redesign Mobile dropdown and desktop tab redesign for the main app. Removed trial language from onboarding flow. ### Documentation Updates * Enhanced Mintlify components: Frame, Badge, Check, Info, Tooltip across all pages * Tabbed install methods for Claude Code setup * Resend-style navbar redesign * GA4 tracking added to docs site * 6 new Knowledge Base articles, MCP explainer page, Mermaid workflow diagrams * UTM tracking on all CTA links **February 16, 2026** v2.0.1 ## Expanded Onboarding Setup Guides Onboarding now includes 6 platform-specific setup tabs with step-by-step instructions for connecting Adspirer to each AI client. ### OpenClaw Plugin v0.3.0 Fixed OpenClaw OAuth client registration and plugin authentication flow. **February 2026** v2.0.0 ## Documentation Site Launch Launched comprehensive documentation at [adspirer.com/docs](/docs/introduction) with 24 pages covering all AI clients, ad platforms, agent skills, and in-depth guides. * **AI client guides** for ChatGPT, Claude, Claude Code, Cursor, Codex, OpenClaw, and Windsurf * **Ad platform guides** for Google Ads (39 tools), Meta Ads (20 tools), LinkedIn Ads (28 tools), and TikTok Ads (4 tools) * **Agent skills documentation** with workflows, tool catalog, and safety rules * **7 in-depth guides** covering keyword research, automation, and strategy * Auto-generated `llms.txt`, `llms-full.txt`, and `skill.md` for AI agent discovery * Contextual sharing to ChatGPT, Claude, Cursor, and VS Code ## ChatGPT MCP Connector Added native MCP connector support for ChatGPT Plus and Pro users. Connect Adspirer directly in ChatGPT Settings with OAuth 2.1 authentication. ## Claude MCP Connector Added native MCP connector for Claude Pro, Max, Team, and Enterprise. Includes progress streaming for real-time updates during campaign creation. ## Codex Agent Support Added autonomous agent setup for OpenAI Codex with YAML configuration and skill files. ## OpenClaw Plugin Released zero-configuration OpenClaw plugin with bundled 14.4KB skill file. Install with `openclaw plugins install openclaw-adspirer`. **January 2026** v1.9.0 ## ChatGPT MCP Connector Fix Fixed dynamic client registration to correctly detect Claude vs ChatGPT during OAuth. Claude clients now receive the correct redirect URIs instead of ChatGPT credentials. ### OpenAI Apps SDK Integration Added domain verification, OAuth protected resource endpoints, MCP annotations for tool hints, and OpenAI Platform redirect URI for app submission. ### LinkedIn Campaign Fixes Fixed LinkedIn campaign creation and update workflows. Resolved API version errors. ### Conversion Tracking Set up end-to-end conversion tracking infrastructure for measuring signup-to-paid funnel. Multiple fixes to Google Ads metrics accuracy. ### Onboarding Revamp Redesigned onboarding flow with mobile-responsive screens, auto-completion logic, and MCP OAuth gating to prevent onboarding bypass. ### Enterprise Readiness Account lifecycle management, metrics pause for inactive accounts, and sign-in/sign-up page revamp. ### Meta Ads Traffic Management Added Meta video and carousel campaign creation, ad management workflows, and traffic management tools. ### GTM Cross-Domain Tracking Added Google Tag Manager (GTM-PQGBFK5Q) to frontend. GA4 sessions now persist across domains via the `_gl` parameter. **December 2025** v1.8.0 ## LinkedIn Ads Full Integration Complete LinkedIn Ads integration across 8 phases: * LinkedIn account setup and OAuth * Single image sponsored content campaigns * Campaign performance analytics * Unified tools for cross-platform management ### Meta Video & Carousel Campaigns Added video campaign creation and carousel ad support for Meta Ads. ### Local Currency Support Fixed currency handling across all MCP tools and backend APIs. Campaigns now display metrics in the user's local currency. ### Smart Metric Collection Automated background metric collection for historical performance tracking. **November 2025** v1.7.0 ## Asset Reuse & PMax Improvements * Smart asset discovery and reuse for Performance Max campaigns * Domain filtering for sitelinks * Location targeting fix for MCP/ADK PMax campaigns ### Account Tier System Account tier infrastructure with 120-day metric backfill for new users. Accurate daily metrics via `segments.date` in queries. ### ChatGPT Apps SDK Widgets In-app quota widget and account management tools for ChatGPT users. OAuth improvements for API routes. ### Custom GPT Support Added ChatGPT Actions support with OAuth compatibility for Custom GPT configurations. ### MCP Protocol Improvements * Progress streaming (MCP 2025-03-26) for real-time updates during campaign creation * False success message elimination * OAuth token rotation on reconnect * JWT expiry fix and performance routing improvements **October 2025** v1.6.0 ## TikTok Ads Integration Complete TikTok Ads platform integration: * OAuth setup and multi-platform architecture * In-feed video campaign creation * Image upload and asset validation * Session handling and location targeting ### MCP Server Launch Initial MCP server deployment at `mcp.adspirer.com`: * OAuth 2.1 with PKCE authentication * Complete PMax campaign creation via ChatGPT * Modular architecture for multi-platform support ### Creative Canvas Multi-image upload UX improvements and character limit enforcement for PMax campaigns. **September 2025** v1.0.0 ## Adspirer Launch Initial release with 100+ tools across Google Ads and Meta Ads. ### Google Ads (39 tools) * Keyword research with real CPC data from Google Keyword Planner * Search and Performance Max campaign creation * Wasted spend analysis, budget optimization, and ad extensions * Asset discovery, validation, and ad copy generation ### Meta Ads (20 tools) * Image, video, and carousel campaign creation * Audience targeting and creative fatigue detection * Placement optimization and performance analysis ### Core Features * OAuth 2.1 authentication with PKCE * Multi-platform account management * Agent skills system with SKILL.md instruction files # AI Advertising: Complete Guide to Agentic Marketing in 2025 Source: https://www.adspirer.com/docs/guides/ai-advertising Learn how AI advertising works with ChatGPT and Claude. Discover agentic marketing strategies to automate Google Ads, TikTok Ads, and Meta Ads in 2025. Transform your ad management with AI-powered automation ## What is AI Advertising? AI advertising refers to using artificial intelligence—specifically Large Language Models (LLMs) like ChatGPT and Claude—to manage, optimize, and automate advertising campaigns across platforms like Google Ads, Meta Ads, and TikTok Ads. Instead of manually clicking through complex dashboards, marketers can now use natural language to instruct AI agents to perform tasks like: * **Campaign Creation**: "Launch a Performance Max campaign targeting US customers with a \$100/day budget" * **Budget Optimization**: "Pause all campaigns with ROAS below 2.0" * **Reporting**: "Show me my top 10 performing ads this week" * **Keyword Management**: "Add negative keywords for all irrelevant search terms" This shift from dashboard-based management to conversational AI is called **Agentic Advertising**. ## How Agentic Advertising Works Agentic advertising connects AI assistants directly to advertising platform APIs through tools like Adspirer's MCP (Model Context Protocol — an open standard for connecting AI assistants to external tools) server. **The Traditional Way:** 1. Log into Google Ads dashboard 2. Navigate through multiple screens 3. Click dozens of buttons 4. Wait for loading screens 5. Repeat for each platform **The Agentic Way:** 1. Open ChatGPT or Claude 2. Describe what you want in plain English 3. AI executes the task via API 4. Review and approve changes The AI agent understands your intent and translates it into the exact API calls needed to accomplish your goal. It's like having a junior media buyer who never gets tired and can work across all platforms simultaneously. ## Benefits of AI-Powered Ad Management **Speed**: Tasks that took 30 minutes now take 30 seconds **Scale**: Manage 50 accounts as easily as 5 **Consistency**: No more human errors in campaign setup **24/7 Monitoring**: AI agents can watch for anomalies around the clock **Cross-Platform Efficiency**: Single conversation to manage Google, Meta, and TikTok **Data-Driven Decisions**: AI can analyze thousands of data points to make recommendations ## Getting Started with Adspirer Adspirer provides the MCP server that connects your AI assistant to advertising platforms. Here's how to get started: 1. **Connect Your AI**: Install Adspirer in ChatGPT or Claude 2. **Link Your Ad Accounts**: Authorize access to Google Ads, TikTok Ads, or Meta Ads 3. **Start Conversing**: Ask your AI to perform tasks in natural language No coding required. No complex setup. Just connect and start managing your ads through conversation. ## FAQ > **What is AI advertising?** > > AI advertising uses artificial intelligence, specifically Large Language Models like ChatGPT and Claude, to automate and manage advertising campaigns through natural language conversations instead of manual dashboard navigation. > **How does Adspirer connect AI to advertising platforms?** > > Adspirer provides an MCP (Model Context Protocol) server that acts as a bridge between AI assistants and advertising platform APIs. This allows ChatGPT, Claude, Perplexity, or any MCP-compatible client to execute real actions in Google Ads, TikTok Ads, and Meta Ads. > **Do I need coding skills to use AI for advertising?** > > No coding is required. Adspirer handles all the technical integration. You simply connect your accounts and communicate with your AI assistant in plain English. > **Is AI advertising safe for my ad accounts?** > > Yes. Adspirer includes approval workflows so you can review changes before they're applied. The AI suggests actions, but you remain in control of execution. > **Which advertising platforms does Adspirer support?** > > Adspirer supports Google Ads, Meta Ads, TikTok Ads, and LinkedIn Ads. The platform is designed to be cross-platform from day one. ## Related Documentation * [The Death of the Dashboard: Why 2025 is the Era of Agentic Advertising](https://www.adspirer.com/blog/death-of-the-dashboard) * [How to Launch a Google PMAX Campaign in 30 Seconds](https://www.adspirer.com/blog/launch-google-pmax-30-seconds) * What is an MCP Server? A Beginner's Guide (coming soon) * ChatGPT vs Claude for Ad Management (coming soon) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # How to Automate Facebook Ads in 2025 - Complete Guide Source: https://www.adspirer.com/docs/guides/automate-facebook-ads Learn how to automate Facebook and Instagram Ads with rules, the Meta Marketing API, and AI tools — a complete guide to Meta ads automation for 2025. Master Facebook and Instagram ads automation for scale and efficiency. ## What is Facebook Ads Automation? Facebook Ads automation uses technology to manage, optimize, and scale your Meta advertising across Facebook, Instagram, Messenger, and the Audience Network. Meta has invested heavily in automation, making it central to their advertising platform: **Native Automation Features:** * Advantage+ campaigns with AI-driven optimization * Automated rules for budget and bid management * Dynamic creative optimization * Automated app ads * Advantage Lookalike audiences **External Automation Options:** * Meta Marketing API integrations * Third-party tools and platforms * AI-powered management through MCP **Why Automate Facebook Ads?** 1. **Scale**: Manage more campaigns without proportional time investment 2. **Speed**: React to performance changes instantly 3. **Consistency**: Apply the same logic across all campaigns 4. **Optimization**: Let algorithms find efficiencies 24/7 5. **Cross-Platform**: Manage Facebook and Instagram together In 2025, the question isn't whether to automate, but how much and what type of automation fits your needs. ## Meta's Native Automation Features Meta provides powerful built-in automation that requires no coding: **Advantage+ Campaigns:** Meta's most automated campaign type uses machine learning across all aspects: * **Advantage+ Shopping**: Automated targeting for e-commerce * **Advantage+ App Campaigns**: Optimized for app installs * **Advantage+ Creative**: AI-powered creative optimization Key benefits: * Simplified setup (fewer options to configure) * Machine learning optimizes targeting * Automated audience expansion * Cross-platform delivery optimization **Automated Rules:** Create condition-based automations in Ads Manager: * **Budget Rules**: Increase budget when ROAS exceeds target * **Bid Rules**: Adjust bids based on performance * **Pause Rules**: Stop underperforming ad sets * **Alert Rules**: Get notified of significant changes Rule conditions can include: * Cost per result * ROAS * Frequency * Reach * Impressions * Any metric threshold **Campaign Budget Optimization (CBO):** Automatically distributes budget across ad sets based on performance. The algorithm shifts spend to the best-performing ad sets in real-time. **Dynamic Creative:** Upload multiple images, videos, headlines, and descriptions. Meta's AI tests combinations to find the best performers for each audience segment. ## Advantage+ Campaigns Deep Dive Advantage+ represents Meta's vision for fully automated advertising. Here's what you need to know: **Advantage+ Shopping Campaigns:** Designed for e-commerce, these campaigns automate: * Audience targeting (minimal controls) * Creative testing * Placement optimization * Budget allocation Best practices: * Upload your entire product catalog * Provide diverse creative assets * Set clear conversion goals * Allow 7+ days for learning phase **Advantage+ App Campaigns:** Optimized for mobile app installs and engagement: * Automated targeting based on app signals * Creative optimization for each placement * Automatic bidding adjustments **When to Use Advantage+:** * E-commerce with product catalogs * App install campaigns * Broad targeting goals * Creative testing at scale * Limited time for manual optimization **When to Use Manual Campaigns:** * Specific audience requirements * Need granular control * B2B with narrow targeting * Testing specific creative concepts * Strict brand guidelines **Hybrid Approach:** Many advertisers run both: * Advantage+ for scale and efficiency * Manual campaigns for specific segments * Let data determine the best mix ## API-Based Automation For advanced automation, Meta's Marketing API enables programmatic campaign management: **What's Possible with the API:** * Bulk campaign creation and management * Automated audience creation * Custom reporting and analytics * Inventory-synced ads * Automated creative updates * Cross-account management **Common API Use Cases:** 1. **Product Feed Automation**: Sync ads with real-time inventory 2. **Bulk Management**: Update thousands of ads simultaneously 3. **Custom Reporting**: Pull data into your own dashboards 4. **Dynamic Campaigns**: Create ads based on external triggers 5. **Audience Automation**: Build audiences from CRM data **API Challenges:** * Requires development resources * Complex authentication and permissions * Rate limits and best practices to follow * Ongoing maintenance as API evolves **AI-Powered Alternative:** Tools like Adspirer abstract the API complexity: * Natural language instead of code * No authentication hassles * Automatic API updates * Works alongside other platforms Adspirer fully supports Meta Ads, letting you manage Facebook and Instagram campaigns alongside Google Ads, TikTok, and LinkedIn through a single AI conversation. ## Automation Strategies by Business Type Different businesses need different automation approaches: **E-commerce:** * Use Advantage+ Shopping campaigns * Enable dynamic product ads * Set ROAS-based automated rules * Automate catalog syncing **Lead Generation:** * CBO with multiple audience ad sets * Automated rules based on CPL * Lead form follow-up automation * Quality-based optimization **App Developers:** * Advantage+ App campaigns * Automated event optimization * Deep link automation * Retention campaign triggers **Agencies:** * Cross-account automation * Bulk reporting and alerts * Template-based campaign creation * AI-powered client management **Local Businesses:** * Location-based automated rules * Day-parting automation * Local inventory ads * Review-triggered ads **Key Metrics to Automate Around:** 1. Cost per result (CPA, CPL, CPI) 2. Return on ad spend (ROAS) 3. Frequency (prevent ad fatigue) 4. Click-through rate (CTR) 5. Relevance score / Quality ranking ## Building Your Meta Ads Automation Stack Here's a recommended approach to Facebook Ads automation: **Phase 1: Enable Native Features (Week 1-2)** * Turn on Campaign Budget Optimization * Create automated rules for budget protection * Enable Dynamic Creative on key campaigns * Set up alert notifications **Phase 2: Expand Automation (Week 3-4)** * Test Advantage+ campaigns * Create performance-based rules * Automate reporting * Set up audience automation **Phase 3: Advanced Integration (Month 2+)** * Connect to AI tools (via Adspirer) * Build custom API integrations if needed * Automate cross-platform reporting * Implement advanced attribution **Automation Checklist:** * Budget protection rules active * Performance alerts configured * CBO enabled on prospecting campaigns * Dynamic Creative testing * Automated audience refresh * Regular performance reports scheduled * Cross-platform view established **Future of Meta Ads Automation:** Meta continues pushing toward full automation with Advantage+ suite expansion. The trend is clear: less manual control, more AI-driven optimization. Advertisers who embrace automation now will be better positioned as manual options become limited. **AI-Powered Meta Ads Management** Adspirer is building Meta Ads integration. Soon you'll be able to: * Create campaigns with natural language * Analyze audience insights through AI * Manage Facebook and Instagram alongside Google and TikTok * Get cross-platform optimization recommendations Sign up at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=guide-cta\&utm_content=signup) to be notified when Meta support launches. ## FAQ > **What is the best way to automate Facebook Ads?** > > Start with Meta's native features: Campaign Budget Optimization, automated rules, and Dynamic Creative. For e-commerce, test Advantage+ Shopping campaigns. As you scale, consider API integrations or AI tools like Adspirer for natural language management. > **Should I use Advantage+ campaigns?** > > Advantage+ works well for e-commerce and app install campaigns where you want maximum reach and efficiency. For specific audience targeting or B2B, manual campaigns may still be preferable. Many advertisers run both and let data determine the best mix. > **How do I set up automated rules in Facebook Ads?** > > In Ads Manager, go to Rules > Create Rule. Choose conditions (like cost per result > target), select actions (pause, adjust budget), and set a schedule. Start with budget protection rules to prevent overspend. > **Can I automate Facebook Ads with AI?** > > Yes, though Meta Ads AI automation is still emerging. Adspirer is building Meta integration to allow natural language campaign management alongside Google Ads and TikTok. Sign up at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=guide-cta\&utm_content=signup). > **What's the difference between CBO and Advantage+ campaigns?** > > CBO (Campaign Budget Optimization) automatically distributes budget across ad sets within a campaign. Advantage+ goes further, automating targeting, placements, and creative optimization. CBO gives you more control; Advantage+ is nearly fully automated. ## Related Documentation * [The Death of the Dashboard](https://www.adspirer.com/blog/death-of-the-dashboard) * [AI Advertising Complete Guide](/docs/guides/ai-advertising) * [Marketing Agency Automation](/docs/guides/marketing-agency-automation) * [Meta Ads MCP Integration](/docs/ad-platforms/meta-ads) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # How to Automate Google Ads in 2025 - Complete Guide Source: https://www.adspirer.com/docs/guides/automate-google-ads Learn how to automate Google Ads with scripts, automated rules, and AI tools — a step-by-step guide with examples and best practices for 2025. Stop clicking. Start automating. The complete guide to Google Ads automation. ## What is Google Ads Automation? Google Ads automation refers to using technology—whether native platform features, scripts, third-party tools, or AI—to handle repetitive tasks and optimize campaigns without manual intervention. In 2025, automation has evolved beyond simple rules. Today's options include: **Native Automation:** * Automated bidding strategies (Target CPA, Maximize Conversions) * Dynamic Search Ads that generate headlines automatically * Performance Max campaigns with AI-driven optimization * Responsive Search Ads with automatic asset optimization **Scripts & Rules:** * Google Ads Scripts (JavaScript-based automation) * Automated rules for budget and bid adjustments * Custom alerts and notifications **AI-Powered Automation:** * MCP (Model Context Protocol — an open standard for connecting AI assistants to external tools) integrations with ChatGPT, Claude, and Perplexity * Natural language campaign management * Cross-platform automation tools like Adspirer The key is choosing the right level of automation for your needs—from simple rules to fully AI-driven management. ## Native Google Ads Automation Features Google provides several built-in automation features that require no coding or external tools: **Automated Bidding Strategies:** * **Target CPA**: Sets bids to achieve your target cost per acquisition * **Target ROAS**: Optimizes for your return on ad spend goal * **Maximize Conversions**: Gets the most conversions within budget * **Maximize Conversion Value**: Prioritizes highest-value conversions * **Enhanced CPC**: Adjusts manual bids based on conversion likelihood **Performance Max Campaigns:** Performance Max uses Google's AI to automatically: * Choose the best placements (Search, Display, YouTube, Gmail, Maps) * Generate ad combinations from your assets * Find new audiences * Optimize bids in real-time **Responsive Search Ads (RSAs):** Provide up to 15 headlines and 4 descriptions, and Google's AI tests combinations to find winners. **Automated Rules:** Create conditions-based automations in the Google Ads interface: * Pause keywords with high cost and low conversions * Increase budgets on high-performing campaigns * Send email alerts when metrics change ## Google Ads Scripts: Advanced Automation For advertisers who need more control, Google Ads Scripts offer powerful JavaScript-based automation. **What Scripts Can Do:** * Bulk changes across thousands of keywords * Custom reporting and data exports * Weather-based bid adjustments * Inventory-linked campaign management * Cross-account management for agencies **Popular Script Use Cases:** 1. **N-gram Analysis**: Find wasted spend on poor search terms 2. **Link Checker**: Pause ads with broken landing pages 3. **Hour of Day Bidding**: Adjust bids by time of day 4. **Quality Score Tracker**: Monitor QS changes over time 5. **Budget Pacing**: Prevent overspend or underspend **Script Resources:** * Google Ads Scripts documentation * Brainlabs script library * Search Engine Land script collection * FreeAdWordsScripts.com **Limitations of Scripts:** * Requires JavaScript knowledge * Limited to Google Ads (no cross-platform) * Can be complex to debug * Execution time limits apply ## AI-Powered Google Ads Automation The newest frontier in Google Ads automation is AI-powered management through tools like Adspirer. **How AI Automation Works:** Instead of writing scripts or clicking through interfaces, you simply describe what you want in natural language: * "Create a Search campaign for plumbing services in Chicago with a \$50/day budget" * "Pause all keywords with CPA above \$100" * "Show me campaigns where impressions dropped more than 20% week over week" The AI understands your intent and executes the appropriate Google Ads API calls. **Advantages of AI Automation:** 1. **No Coding Required**: Natural language replaces JavaScript 2. **Cross-Platform**: Same conversation can manage Google, Meta, and TikTok 3. **Intelligent Analysis**: AI can analyze data and provide recommendations 4. **Faster Execution**: Complex tasks completed in seconds 5. **Always Available**: Works 24/7 across time zones **Getting Started with AI Automation:** 1. Connect your Google Ads account to Adspirer 2. Add the MCP connector to ChatGPT or Claude 3. Start managing campaigns through conversation Try asking: "Research keywords for \[your business] and show me estimated CPCs" ## Automation Best Practices Whether using native features, scripts, or AI, follow these best practices: **Start Small:** * Automate one task at a time * Monitor results before expanding * Keep manual oversight initially **Set Guardrails:** * Establish budget limits * Create alert thresholds * Maintain approval workflows for major changes **Monitor Performance:** * Review automated changes regularly * Track KPIs before and after automation * Adjust automation rules based on results **Layer Automation:** * Combine automated bidding with AI analysis * Use scripts for bulk changes, AI for strategy * Let Performance Max handle asset optimization **Document Everything:** * Record what's automated and why * Note any custom rules or thresholds * Create runbooks for troubleshooting **Common Mistakes to Avoid:** * Over-automating too quickly * Setting and forgetting without monitoring * Conflicting automation rules * Not accounting for seasonality * Ignoring business context that AI can't know ## Building Your Automation Stack Here's a recommended automation stack for Google Ads in 2025: **Foundation Layer - Native Features:** * Automated bidding on all campaigns * Responsive Search Ads for testing * Performance Max for discovery **Optimization Layer - Rules & Scripts:** * Automated budget alerts * Negative keyword scripts * Quality Score monitoring * Link checking automation **Intelligence Layer - AI Tools:** * Adspirer for natural language management * AI-powered analysis and recommendations * Cross-platform campaign orchestration **Getting Started Today:** 1. **Week 1**: Enable automated bidding strategies 2. **Week 2**: Set up basic automated rules 3. **Week 3**: Install key scripts (link checker, search query analysis) 4. **Week 4**: Connect to Adspirer for AI-powered management The goal isn't to remove humans—it's to let automation handle the repetitive work so you can focus on strategy, creative, and growth. ## FAQ > **What is the best way to automate Google Ads?** > > The best approach combines multiple layers: native automated bidding for optimization, scripts or rules for bulk operations, and AI tools like Adspirer for intelligent management and analysis. Start with automated bidding, then add complexity as needed. > **Are Google Ads Scripts still useful in 2025?** > > Yes, scripts remain valuable for custom bulk operations and specific use cases like weather-based bidding or inventory syncing. However, AI tools are increasingly handling tasks that previously required scripts, with the advantage of natural language instead of coding. > **Can AI fully automate Google Ads management?** > > AI can automate most tactical execution, but strategic decisions, creative direction, and business context still benefit from human oversight. The ideal is AI-assisted management where automation handles routine work while humans focus on strategy. > **How do I automate Google Ads without coding?** > > Use native features like automated bidding and rules, or connect your account to Adspirer for AI-powered management through natural language. You can create campaigns, analyze performance, and optimize bids without writing any code. > **What's the difference between automated bidding and AI automation?** > > Automated bidding is Google's built-in optimization that adjusts bids based on conversion signals. AI automation (like Adspirer) is broader—it can create campaigns, generate reports, research keywords, and perform any task you describe in natural language. ## Related Documentation * [How to Launch a Google PMAX Campaign in 30 Seconds](https://www.adspirer.com/blog/launch-google-pmax-30-seconds) * [Stop Wasting Money on Zombie Keywords](https://www.adspirer.com/blog/stop-wasting-money-zombie-keywords) * [The Death of the Dashboard](https://www.adspirer.com/blog/death-of-the-dashboard) * [Google Ads Integration Guide](/docs/ad-platforms/google-ads) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Google Ads Keyword Research with ChatGPT: 2026 Guide Source: https://www.adspirer.com/docs/guides/chatgpt-google-ads-keywords Master Google Ads keyword research with ChatGPT Apps in 2026 — get real Keyword Planner data, intent classification, and budget recommendations. Research keywords through conversation—not spreadsheets ## Key Takeaways * ChatGPT Apps can connect directly to Google Ads Keyword Planner for real-time keyword data * Dynamic CPC (Cost Per Click — amount you pay each time someone clicks your ad) thresholds automatically adapt to your industry (legal keywords at $50 CPC vs. retail at $2) * High-intent keywords are identified using percentile-based analysis, not arbitrary thresholds * Budget recommendations are calculated from actual keyword data, not guesswork * You can research, analyze, and select keywords entirely through conversation ## What is Keyword Research with ChatGPT Apps? Keyword research has traditionally required logging into multiple tools, exporting spreadsheets, and manually analyzing data. With ChatGPT Apps—OpenAI's name for connected AI tools—you can now research Google Ads keywords through natural conversation. A ChatGPT App for Google Ads connects directly to your account and Google's Keyword Planner API. Instead of navigating complex interfaces, you describe what you're looking for, and the AI returns organized, actionable keyword data. **Why this matters for advertisers:** * **Speed**: Research that took 2 hours now takes 10 minutes * **Context**: The AI understands your business and adjusts recommendations accordingly * **Accuracy**: Real Google Keyword Planner data, not estimated third-party numbers * **Actionability**: Keywords are automatically grouped by commercial intent This is part of a broader shift toward [AI-powered advertising](/docs/guides/ai-advertising) where natural language replaces complex dashboards. > [!TIP] > > **Ready to research keywords with AI?** Adspirer connects ChatGPT to Google Ads Keyword Planner. [Try Adspirer free →](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide-cta\&utm_content=signup) ## How Keyword Research Works with ChatGPT Apps When you ask a ChatGPT App to research keywords, here's what happens behind the scenes: **1. Seed Keyword Extraction** The AI analyzes your request and extracts seed keywords. If you say "I run a solar panel installation company in Phoenix," it identifies seeds like: * solar panel installation * solar panels phoenix * residential solar * solar energy installation **2. Keyword Planner API Query** The app queries Google's Keyword Planner with your seeds and target location. This returns: * Monthly search volume * Low and high top-of-page bid estimates * Competition level (LOW, MEDIUM, HIGH) * Related keyword suggestions **3. Dynamic Intent Classification** Here's where it gets interesting. Rather than using fixed CPC thresholds (\$3 = high intent), the app calculates **dynamic thresholds** based on your actual keyword set: | Intent Level | Threshold | Logic | | - | - | - | | HIGH | ≥75th percentile CPC | Top 25% most expensive keywords = highest commercial value | | MEDIUM | 25th-75th percentile | Middle 50% | | LOW | Less than 25th percentile | Bottom 25%, lower commercial intent | **Why this matters:** A "high intent" keyword in the legal industry might have a $150 CPC, while in retail it's $3. Fixed thresholds don't work across industries—percentile-based classification does. **4. Quality Filtering** Before presenting results, the app filters out garbage: * Keywords with duplicate words ("solar solar panels") * Nonsensical patterns ("panel panels") * Keywords with fewer than 100 monthly searches * Connector-only phrases ("and solar", "the panels") **5. Budget Recommendations** Finally, the app calculates budget recommendations based on your selected keywords: | Budget Tier | Formula | Use Case | | - | - | - | | Conservative | Median CPC × 50 clicks/day | Safe starting budget | | Moderate | Average CPC × 50 clicks/day | Balanced approach | | Aggressive | Max CPC × 50 clicks/day | Compete for all keywords | Learn more about [how Adspirer works](https://www.adspirer.com) with ChatGPT and Claude. ## Step-by-Step: Keyword Research with Adspirer **Step 1: Create Your Adspirer Account** First, sign up for Adspirer: 1. Go to [adspirer.ai](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide-cta\&utm_content=signup) and click **Sign Up** 2. Create your account with email or Google 3. Verify your email address **Step 2: Connect Your Ad Platforms in Adspirer** Before using ChatGPT, you need to connect your advertising accounts in the Adspirer web app: 1. After signing in, you'll see the **onboarding wizard** 2. Click **Connect Google Ads** (or Meta Ads, TikTok Ads) 3. Sign in with your Google account and authorize access 4. Select the specific ad account you want to manage 5. Repeat for any additional platforms you want to connect **Why connect here first?** This one-time setup securely links your ad accounts to Adspirer. Once connected, any AI assistant (ChatGPT, Claude) can access them without re-authenticating. See our [Google Ads integration guide](https://www.adspirer.com/integrations/google-ads) for detailed setup instructions. **Step 3: Add Adspirer to ChatGPT** Now that your accounts are connected, add Adspirer to ChatGPT: 1. Open [ChatGPT](https://chatgpt.com) 2. Click **Plugins** in the left sidebar, then **Add → Add custom MCP server** 3. Name it `Adspirer-Custom`, keep **Server URL** selected, paste `https://mcp.adspirer.com/mcp`, and set **Authentication** to **OAuth** 4. Tick **I understand and want to continue** and click **Create as a plugin** 5. Click **Try in chat**, then **Connect Adspirer-Custom** This works on every ChatGPT plan, including Free. [Full steps with screenshots →](/docs/ai-clients/chatgpt) **Step 4: Authorize the Connection** When you connect, ChatGPT will ask you to authorize Adspirer: 1. Your browser opens Adspirer 2. Sign in with your **Adspirer account** (the one you created in Step 1) 3. On **Authorize ChatGPT**, click **Authorize** Since you already connected Google Ads in Step 2, your ad account is immediately available—no additional setup needed. Alternatively, you can use Adspirer with [Claude](https://www.adspirer.com/integrations/claude) via MCP. **Step 5: Describe Your Business and Goals** Start with a natural description of what you're advertising: **Example Prompt:** ``` I run a plumbing company in Austin, Texas. We specialize in emergency repairs and water heater installation. I want to find keywords for a Google Ads search campaign with a $100/day budget. ``` The AI will: * Extract seed keywords (emergency plumber, water heater installation, etc.) * Set location targeting to Austin, TX * Note your budget constraint ## Review and Refine Keyword Results **Step 6: Review Initial Keyword Results** The app returns organized results with: * Total keywords found * Recommended keywords for campaign * Dynamic CPC analysis with location-specific data * HIGH, MEDIUM, and LOW intent keyword groupings * Monthly searches, CPC ranges, and competition levels **Step 7: Refine Your Keywords** Ask follow-up questions to refine results: * "Show me only keywords with 500+ monthly searches" * "Remove any keywords mentioning 'cheap' or 'free'" * "Add more keywords related to tankless water heaters" * "What negative keywords should I add based on these results?" **Step 8: Get Budget Recommendations** The app calculates budgets based on your selected keywords across three tiers: * **Conservative**: Based on median CPC, safe starting budget * **Moderate**: Based on average CPC, balanced approach * **Aggressive**: Compete for all high-intent keywords **Step 9: Create Your Campaign (Optional)** Once satisfied, you can ask Adspirer to create the campaign directly: "Create a Google Ads search campaign using these keywords. Name it 'Austin Plumbing - Emergency Services' with a \$75/day budget." See our guide on [Google Ads automation](https://www.adspirer.com/blog/google-ads-automation) for more campaign creation workflows. > [!TIP] > > **Skip the spreadsheets.** Connect Google Ads to ChatGPT and research keywords through conversation. [Try Adspirer free →](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide-cta\&utm_content=signup) ## 10 Prompts for Google Ads Keyword Research Copy and paste these prompts to get started: **Discovery Prompts** **1. Basic Research** ``` Research Google Ads keywords for my [business type] in [location]. I want to target people searching for [product/service]. My budget is around $[X] per day. ``` **2. Competitor-Focused** ``` Find keywords my competitors might be bidding on for [industry]. Focus on commercial intent keywords where people are ready to buy. ``` **3. Long-Tail Discovery** ``` Show me long-tail keywords for [topic] with lower competition. I'm willing to accept lower search volume for easier wins. ``` **Analysis Prompts** **4. Intent Classification** ``` Categorize these keywords by purchase intent: [paste keyword list] Show me which ones indicate someone ready to buy vs. just researching. ``` **5. CPC Analysis** ``` Which of my target keywords have the highest CPCs? Are there cheaper alternatives that could work? ``` **6. Seasonal Analysis** ``` How do search volumes for [keywords] change throughout the year? When should I increase/decrease budget? ``` **Optimization Prompts** **7. Negative Keywords** ``` Based on my target keywords for [business], what negative keywords should I add to avoid wasted spend? ``` **8. Match Type Strategy** ``` For these keywords, which match types would you recommend? Consider my $[X]/day budget and goal of [conversions/traffic]. ``` **9. Ad Group Structure** ``` How should I organize these keywords into ad groups? Group them by theme and search intent. ``` **10. Budget Allocation** ``` I have $[X]/day total budget. How should I split it across these keyword themes based on their potential ROI? ``` For more prompts, check out our ChatGPT Prompts for Google Ads guide (coming soon). ## Best Practices for ChatGPT Keyword Research **Do's** **Be Specific About Location** Google Ads CPCs vary dramatically by location. "Plumber" in New York costs 3x more than in rural Texas. Always specify your target geography. **Include Budget Context** Mentioning your budget helps the AI prioritize realistic keywords. A $50/day budget shouldn't target $30 CPC keywords. **Ask for Negative Keywords** Every keyword research session should include negative keyword discovery. Ask explicitly—the AI won't always surface them unprompted. **Request Multiple Intent Levels** Don't just ask for "high intent" keywords. A healthy campaign includes a mix of intent levels for different funnel stages. **Don'ts** **Don't Ignore Low-Volume Keywords** Keywords with 50-200 searches/month can be highly profitable with low competition. Don't filter them out automatically. **Don't Trust Volume Alone** High search volume doesn't equal high value. A 10,000 search keyword with \$0.50 CPC might be mostly informational traffic. **Don't Skip Quality Score Factors** When selecting keywords, consider whether you can write relevant ads and have relevant landing pages. Keywords you can't support well will have poor Quality Scores. **Don't Forget Mobile vs. Desktop** Some keywords cost 50-100% more on mobile. If your site isn't mobile-optimized, consider device bid adjustments from the start. ## Next Steps Ready to try keyword research with ChatGPT Apps? 1. **Sign up at Adspirer.com** — Create your free account 2. **Connect Google Ads** — Link your ad account in the Adspirer dashboard 3. **Open ChatGPT** — Search for "Adspirer" in Apps and authorize 4. **Start chatting** — Describe your business and get keyword data instantly > [!TIP] > > **Get started in minutes.** No coding required. [Try Adspirer free →](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide-cta\&utm_content=signup) ## FAQ > **How accurate is keyword data from ChatGPT Apps?** > > When connected to Google Ads, ChatGPT Apps pull data directly from Google Keyword Planner—the same source agencies use. The data is as accurate as Google provides. However, CPCs shown are estimates; actual costs depend on Quality Score, competition, and ad rank. > **Can I research keywords without a Google Ads account?** > > You need an active Google Ads account with billing set up to access Keyword Planner data. Google requires this for accurate data. If you don't have an account yet, create one at ads.google.com first. > **How is this different from using Keyword Planner directly?** > > The main differences are: Conversation (describe what you want in natural language), Analysis (automatic intent classification and budget recommendations), Filtering (built-in quality filtering removes garbage keywords), and Speed (no clicking through interfaces—just ask and receive). > **How many keywords should I target per campaign?** > > Start with 15-25 high-intent keywords per ad group. The ChatGPT App typically recommends the top 20 keywords based on intent and volume. You can always expand later based on performance data. > **Does this work for Display or YouTube campaigns?** > > Keyword research through ChatGPT Apps is primarily designed for Search campaigns. Display and YouTube use different targeting methods (audiences, placements) where keyword research is less central. > **Can I use this with Claude instead of ChatGPT?** > > Yes! Adspirer works with both ChatGPT and Claude. See our Claude integration guide for setup instructions. ## Related Documentation * [How to Automate Google Ads](/docs/guides/automate-google-ads) * ChatGPT for Google Ads: Complete 2026 Guide (coming soon) * 50 ChatGPT Prompts for Google Ads (coming soon) * Create Performance Max Campaigns with ChatGPT (coming soon) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Build an Always-On Ad Ops Agent with Claude Cowork Source: https://www.adspirer.com/docs/guides/claude-cowork-ad-ops Set up a Claude Cowork project that builds, verifies, and optimizes your ad campaigns on a schedule. The project-instructions, skills, and scheduled-task pattern that powers production ad ops with Adspirer. [Claude Cowork](/docs/ai-clients/claude-cowork) is Claude's brand-aware workspace mode. Set up a Cowork **project** for ad ops once and it becomes an always-on co-worker: it builds campaigns from your briefs, verifies them against your rules, and optimizes the live ones on a schedule — all through the [Adspirer MCP](/docs/mcp) connector. The teams who get the most out of this don't just chat with the agent ad hoc. They give the Cowork project a durable setup with three moving parts: > **Project instructions** > > The agent's always-on "constitution" — its role, its hard rules, and how it > works. Read on every task. > **Skills** > > On-demand playbooks for specific jobs (build a search campaign, optimize a > portfolio). Loaded only when the task calls for them. > **Scheduled tasks** > > Automation. The same Cowork agent, run unattended on a schedule, making bounded, > guardrailed changes and posting a summary. This guide gives you a copy-paste template for each, plus the safety model that makes unattended automation trustworthy. > [!NOTE] > > Haven't connected Cowork yet? Start with [Connect Claude > Cowork](/docs/ai-clients/claude-cowork), then the [Agent Skills > overview](/docs/agent-skills/overview) and [Core Workflows](/docs/agent-skills/workflows) — then > come back here to wire them into an always-on setup. ## The mental model A Claude Cowork project has four lanes. Keeping them separate is the most important setup decision — mixing them is the most common mistake. | Piece | What it is | Where it lives in Cowork | When the agent reads it | | - | - | - | - | | **Instructions** | The constitution: role + hard rules | The project's **Instructions** field | Every task, always | | **Skills** | Step-by-step playbooks for one job | The **Skills** panel | On demand, when relevant | | **Context** | Your data: briefs, taxonomy, exclusion lists | The project's **Context** folder | Read as data, per task | | **Scheduled tasks** | The agent run unattended on a schedule | The **Scheduled tasks** panel | On its cadence | **Golden rule: skills stay skills.** Reference them *by name* from your instructions and your task prompts. Don't paste a skill into the Instructions field, and don't drop playbooks into the Context folder — Context is for data, not procedure. ## Step 1 — Create the Cowork project and connect **1. Create a Cowork project** In Claude Cowork, create a project for this work (e.g. "Paid Media — Ad Ops"). Everything below lives inside it, so scheduled tasks inherit the same instructions, skills, and connectors. **2. Connect Adspirer MCP** Connect [Adspirer](/docs/mcp) (`mcp.adspirer.com/mcp`, OAuth) and link the ad accounts you'll work in. Confirm the exact account IDs — the agent should never guess which account it's operating on. **3. Connect a notification channel** Add Slack (or email) so scheduled tasks can post what they did. Unattended automation **must** report every run somewhere a human watches. **4. Connect your source of briefs (optional)** If your campaign specs live in Google Drive or a sheet, connect that too so the agent can fetch them as Context instead of you pasting each one. **5. Leave memory on** Project memory lets the agent reuse prior builds, naming conventions, and decisions across sessions. ## Step 2 — Write the project instructions This is the agent's constitution. Paste it into the Cowork project's **Instructions** field. The goal is to make the safe behavior the *default*, so you never have to babysit it. The non-negotiables that make ad-ops agents safe: * **Confirm before building.** Parse the request, show the plan and a validation report, and wait for explicit go-ahead before creating anything live. * **Build paused, never launch.** Every campaign is created **paused**; turning it on is a human decision after sign-off. * **Validate, don't edit.** If approved copy exceeds a platform limit, **stop and report** the exact field and length. The fix is new approved copy, never the agent's own rewrite. * **Preserve what's locked.** Approved creative, tracking parameters, names, and targeting are passed through verbatim. Flag a problem; don't "fix" it. * **Read before you retry.** Creation tools execute for real and can be slow. If one times out, **read the current state first** — a timeout may have succeeded. * **Two monitoring modes, and they're different** (see Step 4): a human chatting with the agent gets **read-only** analysis; a **scheduled task** is pre-authorized to act within guardrails. > **Copy-paste: generic project-instructions template** > > ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} > # Project Instructions — Paid-Media Ad Ops (Adspirer) > > ## Your role > You are the ad-operations agent for our paid-media team. You help us traffic, > verify, and monitor advertising campaigns through the Adspirer MCP connector. You > turn an approved campaign brief into a correctly-built, QA-verified, PAUSED campaign, > then help watch and optimize it. You are precise, literal, and careful. Humans decide > WHAT to run; you make sure it is built EXACTLY as specified and flag anything that isn't. > > ## Golden rules (never break these) > 1. Approved copy is locked. Use every headline, description, and asset verbatim — > exact case, punctuation, spacing. Never rewrite, shorten, "optimize," or reorder it. > 2. Validate, don't edit. If approved copy exceeds a platform limit, STOP and report the > exact field, string, and length. Do not trim it. The fix is new approved copy. > 3. Preserve tracking and names exactly. Pass final URLs and tracking parameters through > verbatim; use campaign/ad-group names character-for-character. Flag a missing required one. > 4. Nothing goes live without a human. Create every campaign PAUSED. Never enable or launch. > 5. No blind retries. Creation tools are real and can be slow. If one times out, READ > current state (list the campaigns) before doing anything again. > 6. Confirm before you build. Present the parsed plan + validation report and get explicit > go-ahead before creating anything live. > > ## Which skill to use > Choose by task and read the skill in full before acting: > - Building a search/display campaign -> the build skill for that platform. > - Optimizing live campaigns on a schedule -> the optimizer skill (the rulebook the > scheduled tasks run). > For builds, follow: parse -> plan -> confirm -> build -> verify -> report. > > ## Standard operating loop (every "build this" request) > 1. Intake. Locate the brief; identify the platform. > 2. Prereqs. Confirm Adspirer + the platform are connected and the CORRECT account is > selected. Never guess the account. > 3. Parse & validate. Build the plan; re-measure every string against tool limits. > 4. Confirm. Show plan + validation + handoff items + open questions. Wait. Stop here if > any copy is over-limit, a required tag is missing, or a source is unreadable. > 5. Build. Execute into a PAUSED campaign. > 6. Verify. Run the read tools and walk the checklist item by item. > 7. Report. Deliver structure + checklist status + handoff list + blockers, and say exactly > what a human must finish in the platform UI before launch. > > ## Handoff items (be upfront — these can't be done via Adspirer MCP today) > List these explicitly with the exact UI step whenever they apply (e.g. start/end dates, > shared exclusion lists, certain ad formats or campaign types). Never approximate a handoff > (don't substitute a different campaign type). Flag it and move on. > > ## Monitoring & optimization — two distinct modes > A. INTERACTIVE (a human is chatting) -> READ-ONLY. Report pacing, delivery health, and > performance; recommend; ask. Never change bids, budgets, keywords, or status as a "fix" > without explicit instruction. > B. SCHEDULED TASK -> PRE-AUTHORIZED within guardrails. Follow the optimizer skill exactly; > its caps, cooldowns, data thresholds, budget cap, and shadow-mode kill switch are the > safety boundary. One task = one portfolio (single writer). Apply only auto-eligible > changes; PROPOSE anything larger; post a summary every run. > > ## Style & escalation > Lead with status, then details, then the ask. When unsure about a value, a budget > interpretation, or whether something is a handoff — ASK, don't assume. Never expose > secrets, account IDs, or internal URLs outside this project. > ``` ## Step 3 — Add skills (on-demand playbooks) A skill is a focused, reusable playbook for one job. Cowork loads it only when the task matches, so you can give the agent deep, exact procedures without bloating every conversation. Adspirer ships a [set of skills](/docs/agent-skills/skills) you can install as a starting point, and you can write your own. What makes a good ad-ops skill: * **One job, fully specified.** "Build a search campaign from a brief" or "optimize a portfolio on a schedule" — not "do marketing." * **A clear workflow.** The exact order of operations and the tools at each step. * **Inherited invariants.** State what it must never do (e.g. never broad match, never touch locked copy) so the rule holds even mid-task. * **Validation built in.** Where it measures against platform limits and stops. > **Copy-paste: generic skill template** > > ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} > --- > name: search-campaign-builder > description: >- > Build a single search campaign from an approved brief via Adspirer MCP. Parse the > brief, validate every string against platform limits, create the campaign PAUSED, > verify it against a checklist, and report. Never edits approved copy or launches. > --- > > # Search Campaign Builder (Adspirer MCP) > > ## 0. Invariants (never violate) > - Approved copy, tracking parameters, names, and targeting are verbatim. Validate, never edit. > - Create PAUSED. Never enable a campaign. > - Keywords are EXACT/PHRASE only — never broad. No Display/partner networks unless the brief says so. > > ## 1. Parse > Read the brief into a structured plan: campaign + ad group(s) + keywords + assets + > budget + targeting + tracking. Note anything missing or ambiguous. > > ## 2. Validate > Re-measure every headline/description/asset against the platform's character limits. > If anything is over, STOP and report the exact field, string, and length. Do not trim. > > ## 3. Confirm > Show the plan + validation report + handoff items. Wait for explicit go-ahead. > > ## 4. Build > Execute the tool sequence into a PAUSED campaign: create campaign -> ad group(s) -> > keywords (EXACT/PHRASE) -> assets -> budget -> targeting -> tracking. > > ## 5. Verify > Read the campaign back and walk the checklist item by item. Report structure + > checklist status + any handoff a human must finish in the platform UI before launch. > ``` ## Step 4 — Automate with scheduled tasks A Cowork scheduled task is the same project agent, run unattended on a cadence. Because no human answers a prompt mid-run, **all the safety has to live in the rules, not in a permission prompt.** This is where the design matters most. ### The safety model for unattended changes These seven properties are what make a self-driving optimizer trustworthy. They are platform-agnostic — the same shape works for Google, Meta, LinkedIn, or TikTok. > **Shadow mode by default** > > A `MODE: shadow` switch makes the task compute and report what it *would* do, but > write nothing. New tasks start here for a week. > **Hard guardrails** > > Per-run change caps (e.g. ≤±20%/run), a spend cap it can never exceed, a daily > floor, and a cooldown so a lever changes at most once per N runs. > **Single writer** > > One task owns one portfolio. No two tasks ever touch the same campaign, so there's > no write conflict and one clear audit trail per scope. > **Propose vs. act** > > Small, reversible changes auto-apply. Pauses, big moves, and anything beyond a cap > are *proposed* — applied next run only after a human approves. > **Catch-up safe** > > Every number is read from live state at run time. A skipped or late run recomputes > from current spend instead of compounding a stale assumption. > **Notify every run** > > Acted, proposed, or nothing — each run posts a summary to your channel so a human > can always see and reverse it. Plus a **kill switch**: flip `MODE: shadow` (or pause the task) and all writes stop immediately, everywhere that task runs. ### Put the rules in the skill, the scope in the task Keep the thresholds, decision logic, math, and report format in **one optimizer skill**, so a single edit updates every task. The task prompt just names the skill, the platform, the campaigns/pool, and the cap. > **Copy-paste: generic scheduled-task prompt** > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > You are our paid-media PORTFOLIO optimizer. Run via Adspirer MCP, following > the portfolio-optimizer skill — the skill holds the exact thresholds, guardrails, and > math; obey it. > > SCOPE: all live campaigns in the "" budget pool. > POOL CAP: $/month. > > Each run: > 1. READ every campaign in scope — trailing 7d & 30d performance, conversions, spend, > current daily budget, whether it is budget-limited, month-to-date spend, days left. > 2. SCORE each: winner / efficient-but-not-capped / steady / underperformer / dead / > insufficient-data (per the skill). > 3. DECIDE one move per campaign: INCREASE (strong + budget-limited), HOLD, REDUCE (weak), > or PROPOSE PAUSE (dead with ~0 conversions). > 4. SHIFT the budget freed by reductions/pauses to the budget-limited winners, keeping > total spend within the pool cap. Shift only within this one pool. > 5. APPLY only auto-eligible changes within the skill's guardrails; PROPOSE pauses, big > moves, and anything beyond caps. Post a one-line-per-campaign summary to the channel. > > Respect MODE: shadow (make no changes; post what you WOULD do), the once-per-day-per- > campaign cap, and catch-up recompute from live month-to-date. Never touch locked copy, > tracking, or targeting; never launch a paused campaign. > ``` > **How the optimizer skill decides (the rulebook shape)** > > The task prompt is short because the skill carries the logic. A portfolio-optimizer > skill is typically organized as: > > * **Operating principles** — guardrails are hard limits; compute from live state; don't > double-act; smallest reversible change first; kill switch; always notify. > * **Per-run flow** — `READ → GUARD → SCORE → DECIDE → SHIFT → APPLY → LOG + NOTIFY`. > * **Signals** — what to read per campaign over trailing 7d and 30d (discount the last > 1–2 days for attribution lag). > * **Classification** — winner / efficient-not-capped / steady / underperformer / dead / > insufficient-data, each with a numeric condition you tune to your targets. > * **Decision tree** — efficiency × capacity: a strong campaign that is *budget-limited* > gets more budget; a strong one that *isn't* limited just holds (more budget buys no > extra volume); weak ones reduce; dead ones propose a pause. > * **Pacing math** — every budget number is clamped to a glide path: `remaining ÷ > days_left`, never letting projected month-to-date exceed the cap. > * **Hard guardrails** — the per-run caps, cooldown, data minimums, and pool integrity. > * **Auto vs. propose table** — exactly which changes apply automatically and which wait > for approval. > * **Report template** — the per-run summary format. > > Keep every threshold as a tunable default and refine it from real results. The > *structure* is the contract; the *numbers* are yours to tune. ### Rolling it out safely **1. Start in shadow mode** Set the optimizer skill to `MODE: shadow`. The task computes and posts what it would do, but changes nothing. **2. Run once and approve its tools** Trigger a manual run and approve the tools it needs (reads + your channel) so future automatic runs don't stall on a permission prompt. **3. Watch for about a week** Read the daily summaries. Tune the thresholds in the skill until the proposed moves match what you'd have done by hand. **4. Flip to live** Switch to `MODE: live` and re-approve the write tools. Start with one portfolio, then add platforms and a read-only digest once you trust it. > [!WARNING] > > Scale by adding campaigns to a task's **scope**, not by adding more tasks to the same > campaigns. One writer per portfolio keeps the audit trail clean and avoids conflicting > changes. ## Where to go next > **[Connect Claude Cowork](/docs/ai-clients/claude-cowork)** > > Connect a Cowork project to your ad accounts. > **[Agent Skills overview](/docs/agent-skills/overview)** > > What skills are, the safety rules, and how to install them. > **[Core workflows](/docs/agent-skills/workflows)** > > The exact tool sequences for builds, analysis, and automation. > **[Always-on on a VPS](/docs/guides/deploy-paid-media-agent-hostinger)** > > Run an agent 24/7 on your own server. > **FAQ** > > **Do I need to write all of this myself?** > No. Start from Adspirer's [shipped skills](/docs/agent-skills/skills) and the templates above, > then tune. Most teams begin with one build skill and one read-only digest task. > > **What if a scheduled run fires late or gets skipped?** > That's expected. Every run reads live state (current budgets and month-to-date spend), so > a late run recomputes from where things actually are rather than compounding an old number. > > **How do I stop everything fast?** > Flip the optimizer skill to `MODE: shadow`, or pause the task. Both stop all writes > immediately while the task keeps reporting. > > **Can one Cowork project manage multiple accounts?** > Yes — see [running multiple agents and accounts](/docs/knowledge-base/multi-client). Keep one > writer per portfolio so scheduled tasks never collide. # Deploy Your Own AI Ad Manager on Hostinger — No Coding Source: https://www.adspirer.com/docs/guides/deploy-paid-media-agent-hostinger Step-by-step guide to deploying an always-on AI advertising agent on Hostinger VPS with OpenClaw and Adspirer — manage ads from WhatsApp or Telegram. Deploy a paid media agent that runs 24/7, manages ads across 6 platforms, and responds on WhatsApp, Telegram, or any browser — no coding, no dashboards, no IT team. ## Why Deploy Your Own Ad Agent? You already use AI tools like ChatGPT or Claude to manage ads. But they have limits: * **They shut off when you close the tab.** Your agent stops working when you stop working. * **They don't connect to your messaging apps.** You can't text your AI "pause that campaign" from WhatsApp at 10pm. * **They don't remember context between sessions.** Every new conversation starts from scratch. * **Your team can't share access.** One person's AI session isn't accessible to the rest of the team. A self-hosted agent solves all of this. It runs on a server you own, stays online 24/7, connects to WhatsApp and Telegram, and any team member can interact with it. **What you're building:** | Component | What It Does | | - | - | | **Hostinger VPS** | A server in the cloud that keeps everything running 24/7 | | **OpenClaw** | The agent platform — connects AI to WhatsApp, Telegram, Discord, and a web dashboard | | **Adspirer Plugin** | The advertising brain — 400+ tools for Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads | The end result: you (or your team, or your clients) message the agent on WhatsApp and say *"show me last week's Google Ads performance"* or *"create a Meta campaign for our spring sale"* — and it just works. ## What You Need Before Starting > [!NOTE] > > **Time required:** About 15 minutes from start to finish. > > You'll need: > > * A **Hostinger account** — [hostinger.com](https://www.hostinger.com/) (VPS plans start around \$5/month) > * An **Adspirer account** — [adspirer.ai/sign-up](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide\&utm_content=hostinger-guide) (free to start, 15 tool calls/month) > * A **credit or debit card** for Hostinger billing > * Your **ad platform logins** (Google Ads, Meta Business Manager, LinkedIn Campaign Manager, or TikTok Ads — whichever you use) ## Step 1: Buy a Hostinger VPS with OpenClaw Pre-Installed A VPS (Virtual Private Server — a computer in a data center that you rent by the month. It runs 24/7 and you access it over the internet.) is just a computer in the cloud that stays on all the time. Hostinger makes this easy because OpenClaw comes pre-installed — you don't need to install anything manually. **1. Go to Hostinger's OpenClaw VPS Page** Visit the [Hostinger VPS marketplace](https://www.hostinger.com/vps) and look for the OpenClaw hosting option. **2. Choose a Plan** Any plan works. For a single-brand or small agency setup, the entry-level plan is more than enough. OpenClaw is lightweight — it doesn't need a powerful server. > [!TIP] > > If you're an agency managing 5+ client accounts, consider a mid-tier plan for extra headroom. But you can always upgrade later. **3. Click Deploy** OpenClaw is auto-selected as the application to install. Just click **Deploy** to continue. ## Step 2: Configure Your Server After clicking Deploy, Hostinger asks you to set some configuration values. This is where you connect Adspirer. **1. Set Your Gateway Token** Hostinger auto-generates an `OPENCLAW_GATEWAY_TOKEN` for you. This is your password to access the OpenClaw dashboard. **Copy this token and save it somewhere safe** (a password manager, a note on your phone — anywhere you won't lose it). You'll need it to log in. **2. Generate Your Adspirer API Key** In a new browser tab: 1. Go to [adspirer.ai/keys](https://adspirer.ai/keys) 2. Click **Generate New Key** 3. Name it something like "Hostinger server" 4. Copy the key — it starts with `sk_live_` and **won't be shown again** > [!WARNING] > > Treat this API key like a password. Don't share it publicly or paste it in chats. If compromised, revoke it from the Adspirer dashboard and generate a new one. **3. Enter Your API Keys in Hostinger** Back in the Hostinger setup screen, you'll see fields for API keys. You have two options: **Option A — Use Adspirer as your AI provider (recommended):** * Leave the `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and other AI keys **empty** * The Adspirer plugin handles the AI model connection for you **Option B — Bring your own AI key:** * Paste your Anthropic or OpenAI API key in the appropriate field * This gives you a separate AI model alongside Adspirer's ad tools Either way, you'll add the Adspirer API key in a later step (Hostinger's setup screen doesn't have a dedicated field for it yet). **4. Optional: Add Your WhatsApp Number** If you want to control your ad agent from WhatsApp, enter your phone number in the `WHATSAPP_NUMBER` field. You can also set this up later. **5. Complete the Purchase and Deploy** Review your settings and click **Deploy**. Hostinger will set up your server with OpenClaw pre-installed. This takes 1–2 minutes. When the status shows **Running**, your server is live. ## Step 3: Access Your OpenClaw Dashboard **1. Find Your Server Address** In Hostinger's Docker Manager (or the Overview section), you'll see your server's IP address and port number. Your dashboard URL looks like: ``` http://your-server-ip:port ``` For example: `http://145.223.xxx.xxx:3000` **2. Log In** Open that URL in your browser. Enter the `OPENCLAW_GATEWAY_TOKEN` you saved earlier and click **Login**. You're now inside the OpenClaw control panel — this is where you manage channels, view conversations, and monitor your agent. ## Step 4: Install the Adspirer Plugin This is the step that turns your OpenClaw server into an advertising agent. You'll connect to your server via a terminal (A terminal is a text-based interface for talking to a computer. You type commands and the computer responds. Think of it like texting your server.) and run a few commands. **1. Open the Terminal** In Hostinger's hPanel, find the **Terminal** or **SSH Access** option for your VPS. Click to open it. > [!NOTE] > > If you've never used a terminal before — don't worry. You'll copy and paste 4 commands. That's it. **2. Install the Adspirer Plugin** Copy and paste this command, then press Enter: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins install openclaw-adspirer ``` This downloads the Adspirer plugin — including 400+ advertising tools and a built-in instruction manual (SKILL.md) that teaches your agent how to manage campaigns like an expert. **3. Set Your Adspirer API Key** Copy and paste this command, replacing `sk_live_your_token_here` with the API key you generated in Step 2: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer login --token sk_live_your_token_here ``` **4. Restart the Gateway** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw gateway restart ``` This loads the Adspirer plugin and registers all 400+ tools. Your agent is now an advertising expert. **5. Verify Everything Works** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer status ``` You should see: ``` ✅ Authenticated via API Key Server: https://mcp.adspirer.com Key prefix: sk_live_a1b2... ``` ## Step 5: Connect Your Ad Platforms Your agent needs permission to access your ad accounts. This is a one-time setup done from your browser — not the terminal. **1. Open the Connections Page** Go to [adspirer.ai/connections](https://adspirer.ai/connections) from any device with a browser (your laptop, phone, etc.). **2. Connect Your Platforms** Click **Connect** next to each platform you use: * **Google Ads** — sign in with your Google account and select your ad account * **Meta Ads** — sign in with Facebook and select your Business Manager * **Amazon Ads** — sign in with Amazon and select your ad account * **ChatGPT Ads** — paste your ChatGPT Ads API key to connect * **LinkedIn Ads** — sign in with LinkedIn and select your ad account * **TikTok Ads** — sign in with TikTok and authorize access You can connect one platform or all six. Connect whichever ones you actively manage. **3. Verify on Your Server** Back in the terminal, run: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw adspirer accounts ``` You should see your connected accounts listed. > [!TIP] > > Your ad agent is live. It's running 24/7 on your Hostinger server, connected to your ad platforms, and ready to work. ## Step 6: Connect a Messaging Channel This is what makes a self-hosted agent different from using ChatGPT or Claude in a browser. You can talk to your agent from **WhatsApp, Telegram, Discord**, or the **web dashboard** — whatever your team already uses. ### WhatsApp (Most Popular for Agencies) **1. Open the Channels Section** In your OpenClaw dashboard (the browser URL from Step 3), navigate to **Channels**. **2. Scan the QR Code** Click **Show QR code** next to WhatsApp. On your phone: 1. Open **WhatsApp** → **Settings** → **Linked Devices** 2. Tap **Link a Device** 3. Scan the QR code on your screen > [!TIP] > > If the connection fails with a "status=515" error, go to **Settings → Config** in the dashboard, click **Update**, then try scanning again. **3. Send a Test Message** Open WhatsApp and send a message to yourself (or to the linked number). Try: > "Show me my Google Ads performance for the last 7 days" Your agent will respond with a performance summary — right in WhatsApp. ### Telegram, Discord, or Web Dashboard OpenClaw supports multiple channels. Set them up from the **Channels** section in your dashboard. The web dashboard works immediately — no extra setup needed. ## What Your Agent Can Do Now that your agent is live, here's what you can ask it — from WhatsApp, Telegram, or the web dashboard: ### Performance Reports ``` "Give me a full performance report for the last 30 days across all platforms" ``` ``` "What's my Google Ads ROAS this week?" ``` ``` "Which Meta campaigns have the highest CPA?" ``` ### Campaign Creation ``` "Create a Google Search campaign for our accounting firm: - Service: tax preparation for small businesses - Budget: $50/day - Target: small business owners in Austin, TX" ``` ``` "Launch a Meta image campaign for our new product: - Product: wireless earbuds, $79 - Target: 18-35 year olds interested in fitness and tech - Budget: $40/day - Image URL: [paste URL]" ``` ### Optimization ``` "What keywords are wasting spend in my Google Ads?" ``` ``` "Which Meta ad creatives are showing fatigue?" ``` ``` "Optimize my budget allocation across all active campaigns" ``` ### Quick Actions ``` "Pause the spring sale campaign" ``` ``` "Add negative keywords 'free' and 'jobs' to all search campaigns" ``` ``` "What's my LinkedIn lead cost this month?" ``` ## How the Skill File Works When you installed the Adspirer plugin, it included a 14,400-character instruction file called **SKILL.md**. This file is what makes your agent smart about advertising — it's not just connecting to tools, it's been taught: * **400+ tools documented** — every parameter, every return value * **6 complete workflows** — performance analysis, keyword research, campaign creation, budget optimization, account management, automation * **Platform-specific knowledge** — minimum budgets, best practices, when to use each platform * **Safety rules** — always creates campaigns paused, always asks before spending money, always checks account context first This is the difference between "an AI with access to ad tools" and "an AI advertising expert." Other setups require you to train the agent yourself. With OpenClaw + Adspirer, the training is built in. ## Agency Use Cases ### Manage Multiple Clients Connect multiple ad accounts across platforms. Use the `switch_primary_account` command to jump between clients: ``` "Switch to client ABC's Google Ads account" ``` ``` "Show me all campaigns for client XYZ" ``` Each client's data stays separate. Your agent knows which account it's managing. ### Team Access Your entire team can interact with the same agent: * **Account managers** ask for performance reports via WhatsApp * **Media buyers** create and optimize campaigns from Telegram * **Executives** get high-level summaries from the web dashboard Everyone talks to the same agent, which has the same context, the same connected accounts, and the same expertise. ### Always-On Monitoring Your agent runs 24/7. Set up monitoring and alerts: ``` "Monitor my Google Ads campaigns and alert me if CPA exceeds $30" ``` ``` "Send me a daily spend summary at 9am" ``` No more logging into dashboards every morning. Your agent watches your campaigns while you sleep. ### Scaling Without Hiring The traditional agency model: more clients = more hires = more overhead. The AI agent model: more clients = more ad accounts connected to the same agent. One strategist with an always-on AI agent can manage what previously required a team of 3–5 junior media buyers. > **[Read more: Marketing Agency Automation](/docs/guides/marketing-agency-automation)** > > Deep dive into how agencies are scaling with AI — team structures, automation roadmaps, and ROI analysis. ## Cost Breakdown | Item | Monthly Cost | What You Get | | - | - | - | | **Hostinger VPS** | \~\$5–13/mo | 24/7 server, OpenClaw pre-installed | | **Adspirer Free** | \$0/mo | 15 tool calls/month — enough to test | | **Adspirer Plus** | \$49/mo | 150 tool calls — good for 1–3 clients | | **Adspirer Pro** | \$99/mo | 600 tool calls — good for 5–10 clients | | **Adspirer Max** | \$199/mo | 3,000 tool calls — agency scale | Compare this to hiring a junior media buyer ($4,000–6,000/month) or an agency retainer ($2,000–5,000/month per client). A self-hosted AI agent costs under \$250/month at full scale. > **[Start free — 15 tool calls/month, no credit card](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide\&utm_content=hostinger-guide)** > > Sign up for Adspirer, connect your ad accounts in 2 minutes, and try it before committing. ## Troubleshooting > **I lost my gateway token** > > In Hostinger's hPanel, go to your OpenClaw project settings and look under **Environment variables**. Your `OPENCLAW_GATEWAY_TOKEN` is stored there. > **WhatsApp QR code won't scan or connection fails** > > Go to **Settings → Config** in the OpenClaw dashboard, click **Update**, then return to **Channels** and try scanning again. Make sure you're using WhatsApp's **Link a Device** option (not the regular QR scanner). > **'Not authenticated' error from Adspirer** > > Your API key may have expired or been revoked. Generate a new one at [adspirer.ai/keys](https://adspirer.ai/keys), then re-authenticate: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > openclaw adspirer login --token sk_live_new_key_here > openclaw gateway restart > ``` > **'No ad platforms connected' warning** > > You authenticated with Adspirer, but haven't connected your ad accounts yet. Go to [adspirer.ai/connections](https://adspirer.ai/connections) in your browser and connect at least one platform (Google, Meta, Amazon, ChatGPT Ads, LinkedIn, or TikTok). > **Agent isn't responding or tools aren't working** > > Check your Adspirer usage at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=guide\&utm_content=hostinger-guide). Free accounts get 15 tool calls/month. If you've hit the limit, upgrade to Plus (\$49/mo) or wait for the next billing cycle. > **How do I update OpenClaw?** > > In Hostinger's Docker Manager, navigate to your OpenClaw project and click the update option. This pulls the latest version automatically. > **Can I use this with multiple Adspirer accounts?** > > Yes. If you manage ads for multiple clients, each with their own Adspirer account, use the `switch_primary_account` tool to switch between them. Or connect all client ad accounts under a single Adspirer account with multi-account support. ## What's Next > **[Google Ads Guide](https://www.adspirer.com/blog/google-ads-automation)** > > Automate keyword research, campaign creation, and optimization > **[Meta Ads Guide](/docs/guides/automate-facebook-ads)** > > Create image, video, and carousel campaigns with AI > **[Agency Automation](/docs/guides/marketing-agency-automation)** > > Scale your agency with AI — team structures and workflows > **[OpenClaw Setup Docs](/docs/ai-clients/openclaw)** > > Full OpenClaw plugin reference, CLI commands, and configuration # An Advertising Assistant for Small Businesses with Hermes Source: https://www.adspirer.com/docs/guides/hermes-advertising-assistant Illustrative workflows for using Hermes and Adspirer to plan local campaigns, prepare growth briefs, and review client advertising accounts. By **Adspirer** · Published September 20, 2026 You know your products, your customers, and what it takes to run your business. Advertising adds another specialty: keywords, targeting, bidding, tracking, and deciding what to change next. Hermes and Adspirer offer a way to bring that work into a conversation. > [!NOTE] > > The florist, plumber, and agency workflows below are illustrative use cases, not customer testimonials or measured Hermes results. They describe ways to use the published Adspirer integration; they do not claim these businesses have deployed it or achieved a particular outcome. ## What we built Adspirer provides a company-maintained Hermes plugin with fourteen paid-media workflow skills and a connection to its hosted MCP service. The skills cover campaign planning, creation, optimization, creative work, and performance review across Google Ads, Meta Ads, Amazon Ads, LinkedIn Ads, TikTok Ads, and ChatGPT Ads. The plugin is [listed in the Hermes plugin catalog](https://github.com/NousResearch/hermes-agent/blob/main/plugin-catalog/adspirer.yaml). A [separate direct MCP catalog submission](https://github.com/NousResearch/hermes-agent/pull/117421) has been opened; it is a distinct review process. See the [company repository](https://github.com/Adspirer/adspirer-hermes-plugin) for current installation instructions and requirements. ## A neighborhood florist plans a local campaign Illustrative use case: a neighborhood florist knows its customers but has little time to learn advertising. With Hermes and Adspirer, the owners can work toward a local campaign plan: research relevant keywords, draft ads, review the delivery area and budget, then approve creation before a separate launch decision. The owners spend their day arranging flowers, serving walk-ins, and organizing deliveries. They want more local orders, but an advertising dashboard does not tell them which decisions matter first. The useful starting point is their business context: delivery radius, profitable products, seasonal demand, order capacity, landing page, and a budget they can afford. The assistant should ask for missing details and check how orders are measured before proposing a launch. Plan a local florist campaign with clear approval steps. We run a neighborhood florist and want more local delivery orders. Help us plan a Google Search campaign. Ask about our delivery area, products, margins, order capacity, website and budget first. Research relevant keywords and estimated costs, then draft ads and explain your choices in plain language. Show us the full plan before creating anything. After we approve creation, create the campaign paused and show us what was created. Ask separately before launch. After launch, the question becomes: what did we spend, which orders can we attribute, and what should we test next? If tracking is incomplete, the assistant should explain that limitation rather than equate clicks with sales. ## A local service owner's personal growth assistant Illustrative use case: a plumbing business owner spends the day on customer jobs. A proposed Hermes schedule uses Adspirer to prepare a short advertising brief with spend, tracked leads, unusual changes, and one recommended next action. The owner keeps control of campaign edits and budgets. More leads are not always the right goal. The business may want jobs in a particular neighborhood, higher-value work, or fewer calls when its calendar is full. The owner's knowledge should guide recommendations. Design a recurring advertising brief for a local service business. Help me set up a weekday advertising brief for my plumbing business. First confirm my connected accounts, service area, target jobs, capacity, time zone and delivery channel. Propose a Hermes schedule for my approval. Each brief should show recent spend, tracked leads, unusual changes, and one recommended action. Explain missing data and conversion lag. Do not edit campaigns or budgets as part of the scheduled review. A recurring brief requires configuring a Hermes scheduled job and an available delivery channel. Merely connecting the MCP server does not create a schedule or enable continuous monitoring. Review runs consume tool calls and model usage. ## A small agency prioritizes client work Illustrative use case: a small agency asks Hermes and Adspirer to review connected client accounts and prepare a prioritized worklist. Reports keep account identities, currencies, and reporting periods separate, and proposed campaign changes go to the operator for review. The practical benefit is a clear queue of decisions: which account needs investigation, which campaign has insufficient evidence, and which change is worth proposing. A shared report must not accidentally mix one client's campaign data or budget with another's. Prepare a cross-client advertising worklist without modifying campaigns. List my connected advertising accounts and ask which clients to include. Compare the last seven complete days with the preceding seven days. Keep each client's results, currency and conversion definitions separate. Flag unusual spend, delivery problems and performance changes. Give me a prioritized worklist with the evidence behind each recommendation. Do not modify campaigns or share client data externally. ## Start with a read-only check Follow the [Hermes plugin installation guide](https://github.com/Adspirer/adspirer-hermes-plugin#install), complete authorization, and connect your advertising accounts in [Adspirer Connections](https://adspirer.ai/connections). The plugin currently requires Node.js 20.18.1 or newer and npm/npx for its OAuth bridge. Ask for connected accounts and a small performance report before attempting campaign creation. Verify that the returned accounts and dates match what you intended. > [!NOTE] > > The plugin's skills instruct the assistant to seek approval for spending changes, create campaigns paused, and read back changes. These instructions are not a technical guarantee against unwanted actions. The direct MCP connection does not automatically include those skills. Review tool access and proposed actions before execution. Available actions depend on the platform, permissions and account eligibility. Adspirer plan limits and advertising-platform API limits apply; advertising spend is billed separately. None of these workflows guarantees orders, leads, or profitable growth. ## Learn more * [Adspirer MCP connection and authentication](/docs/mcp) * [Advertising tool catalog](/docs/agent-skills/tools) * [Plans and usage limits](/docs/knowledge-base/pricing) * [Hermes plugin source and installation](https://github.com/Adspirer/adspirer-hermes-plugin) * [Support](mailto:support@adspirer.com) # Marketing Agency Automation: Scale With AI in 2025 Source: https://www.adspirer.com/docs/guides/marketing-agency-automation Discover how marketing agencies scale with AI automation. Learn to manage more clients, reduce overhead, and improve campaign performance with Adspirer. Serve 10x more clients without 10x the headcount ## The Agency Scaling Problem Every agency hits a wall. You can only hire so many people, train them so fast, and bill so many hours. Traditional agency scaling means: **Linear Growth**: 2x clients = 2x staff = 2x overhead **Training Burden**: New hires take months to become productive **Quality Variance**: Different team members deliver different results **Margin Pressure**: More clients means more management overhead AI automation breaks this linear relationship. With the right tools, one strategist can manage what previously required a team. ## What Agencies Can Automate **Campaign Management** * Launch campaigns across platforms from templates * Bulk changes across multiple client accounts * Standardized naming conventions and settings **Optimization** * Automated bid adjustments based on performance * Negative keyword management at scale * Budget pacing and reallocation **Reporting** * Auto-generated client reports * Cross-platform performance aggregation * Anomaly detection and alerts **Client Communication** * Performance summaries on demand * Quick answers to client questions * Proactive optimization recommendations **Quality Assurance** * Campaign audit checklists * Consistency verification * Error detection before launch ## The AI-Powered Agency Model The agencies winning in 2025 are structured differently: **Traditional Model:** * Account Managers manually execute * Limited by hours in the day * Inconsistent execution quality * High operational overhead **AI-Augmented Model:** * Strategists direct AI agents * Execution happens instantly * Consistent, error-free setup * Dramatically lower overhead **Team Structure Evolution:** * Fewer junior executors * More strategic advisors * AI handles routine tasks * Humans handle relationships and strategy This doesn't mean fewer jobs---it means different jobs. The agency of 2025 employs strategists who orchestrate AI, not button-clickers who navigate dashboards. ## Getting Started: Agency Automation Roadmap **Phase 1: Connect & Consolidate** * Connect all client accounts to Adspirer * Establish standard operating procedures * Train team on AI-assisted workflows **Phase 2: Automate Routine Tasks** * Start with reporting and monitoring * Add negative keyword automation * Implement bid management rules **Phase 3: Scale Operations** * Launch campaigns via AI * Cross-platform management * Proactive optimization suggestions **Phase 4: Productize Services** * Package AI-powered services * Premium automation offerings * Competitive differentiation Start small, prove value, then expand. Most agencies see ROI within the first month of implementation. ## FAQ > **Will AI replace agency jobs?** > > AI changes jobs, not eliminates them. Routine execution tasks will be automated, but strategic thinking, client relationships, and creative direction still require humans. The best agencies will use AI to enhance their team's capabilities. > **How many clients can one person manage with AI?** > > It depends on complexity, but agencies report managing 3-5x more clients per team member when using AI automation for routine tasks like reporting, bid management, and negative keyword optimization. > **Is AI reliable enough for client work?** > > When used correctly, yes. Adspirer includes approval workflows so you review changes before they're applied. The AI suggests, humans approve. This maintains quality while saving time. > **How do clients feel about AI-managed campaigns?** > > Most clients care about results, not methods. When AI improves performance and enables faster service, clients are happy. Be transparent about your tools---it can be a competitive advantage. > **What's the ROI of agency automation?** > > Agencies typically see ROI within 30 days through time savings alone. The bigger win is capacity---serving more clients with the same team. Some agencies report 50%+ margin improvements. ## Related Documentation * [The Death of the Dashboard: Why 2025 is the Era of Agentic Advertising](https://www.adspirer.com/blog/death-of-the-dashboard) * [Stop Wasting Money on Zombie Keywords](https://www.adspirer.com/blog/stop-wasting-money-zombie-keywords) * How to Price AI-Powered Agency Services (coming soon) * Agency SOPs for AI-Assisted Campaign Management (coming soon) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # How to Manage Ads with Perplexity Computer and Adspirer Source: https://www.adspirer.com/docs/guides/perplexity-computer-ads Use Perplexity Computer as your autonomous ad manager: research competitors, create Google Ads campaigns, audit performance, and optimize budgets. Perplexity Computer is an autonomous AI agent that can research, plan, and execute complex tasks. When connected to Adspirer, it becomes a **search-powered ad manager** — combining real-time web research with direct access to your Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads accounts. This guide walks through real workflows showing what Perplexity Computer + Adspirer can do together. ## Why Perplexity Computer for Ads? Most AI ad tools give you either **research** or **execution**. Perplexity Computer gives you both in a single workflow: | Traditional Approach | Perplexity Computer + Adspirer | | - | - | | Research competitors manually in browser | Computer searches the web for competitor ads, strategies, and spend | | Copy insights into a spreadsheet | Computer stores context and uses it in the next step | | Switch to Google Ads dashboard to create campaign | Computer calls Adspirer tools to create the campaign directly | | Manually pull performance data weekly | Computer fetches metrics via Adspirer and formats a report | The key difference: **no context switching**. Research flows directly into action. ## Prerequisites > [!NOTE] > > * **Perplexity Max** subscription ($200/mo) for Computer — or **Pro** ($20/mo) for connector-only access > * **Adspirer account** ([free to start](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=guide\&utm_content=signup)) — 15 free tool calls/month > * At least one connected ad platform (Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads) > * Adspirer connector already set up in Perplexity — see [Perplexity Setup Guide](/docs/ai-clients/perplexity) ## Workflow 1: Competitor Research → Campaign Creation The most powerful workflow. Perplexity researches your market on the web, then creates a campaign based on real competitive intelligence. ### The Prompt Research competitors on the web, then create a Google Ads campaign using real keyword data from Adspirer. I'm launching a B2B SaaS for project management targeting remote teams. 1. Research the top 5 competitors in this space — what are they spending on Google Ads? What keywords are they targeting? 2. Using Adspirer, research Google Ads keywords for "project management software for remote teams" — show me search volume, CPC, and competition 3. Identify keyword gaps — terms competitors aren't targeting that have decent volume 4. Create a Google Search campaign with \$50/day budget targeting the best opportunities 5. Give me a summary of what you created and why ### What Computer Does ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[Receive prompt] --> B[Search web for competitor ads] B --> C[Analyze competitor strategies and spend] C --> D[Call research_keywords via Adspirer] D --> E[Compare keywords with competitor gaps] E --> F[Call suggest_ad_content for headlines/descriptions] F --> G[Call validate_and_prepare_assets] G --> H[Call create_search_campaign — PAUSED] H --> I[Deliver summary with reasoning] ``` The campaign is created **PAUSED** — you review targeting, keywords, and ad copy before enabling it. ## Workflow 2: Cross-Platform Performance Audit Use Perplexity's search to benchmark your performance against industry standards, then audit your actual data. ### The Prompt Benchmark your ad performance against industry data from the web, then audit via Adspirer. Audit my ad performance across all connected platforms for the last 30 days. First, search the web for current industry benchmarks for SaaS companies: * Average CPC, CTR, conversion rate, and ROAS for Google Ads * Average CPL and engagement rate for LinkedIn Ads * Average CPA and frequency benchmarks for Meta Ads Then pull my actual performance data from Adspirer and compare against those benchmarks. Flag anything significantly above or below industry average. Give me a prioritized action list. ### What Computer Does 1. **Searches the web** for current SaaS advertising benchmarks 2. **Calls `get_campaign_performance`** for each connected platform via Adspirer 3. **Calls `analyze_wasted_spend`** to find zero-conversion keywords 4. **Compares** your metrics against industry benchmarks 5. **Delivers** a prioritized action list with estimated savings ## Workflow 3: Market Entry Research Planning to advertise in a new market? Let Computer research the landscape before you spend a dollar. ### The Prompt Full market research before launching ads in a new vertical. I'm considering advertising my accounting software to small businesses in Texas. Research this market for me: 1. Search the web — who are the top advertisers in this space? What channels are they using? 2. Research Google Ads keywords for "small business accounting software Texas" via Adspirer 3. Research LinkedIn targeting options for small business owners in Texas 4. Estimate a 30-day test budget across Google + LinkedIn 5. Don't create anything yet — just give me a go/no-go recommendation with data This workflow is **read-only** — Computer researches and recommends without creating any campaigns. ## Workflow 4: Wasted Spend Recovery Find and fix wasted ad spend across all platforms. ### The Prompt Find wasted spend across all platforms and create an optimization plan. Where am I wasting money on ads? 1. Analyze Google Ads search terms — find keywords with 10+ clicks and zero conversions 2. Check Meta Ads for creative fatigue — any ads with frequency > 3 and declining CTR? 3. Review LinkedIn campaigns — which audience segments have the highest CPA? 4. Search the web for current best practices on Google Ads negative keyword strategy 5. Give me a step-by-step plan to cut waste and reallocate budget to winners ## Workflow 5: Ad Copy Optimization Let Computer research what's working in your industry, then improve your ads. ### The Prompt Research winning ad copy patterns, then optimize your existing ads. I want to improve my Google Ads copy. 1. Search the web for high-performing Google Ads copy examples in the SaaS/project management space 2. Pull my current ad headlines and descriptions from Adspirer 3. Analyze what my top competitors are saying in their ads 4. Suggest 5 new headline variations and 3 new description variations based on: * Competitor differentiation * Benefit-focused messaging * Current CTR data from my account 5. Update my ad copy with the best variations using Adspirer ## Tips for Better Results ### Be Specific About Research vs Action Computer can both research and act. Be explicit about which you want: | Prompt | What Happens | | - | - | | *"Research keywords for my SaaS"* | Computer calls `research_keywords` — **read-only** | | *"Create a campaign for my SaaS"* | Computer researches AND creates — **write action** | | *"Research the market but don't create anything"* | Computer researches only — **read-only** | ### Chain Web Research with Adspirer Tools The most valuable prompts combine web research with platform data: * *"Search the web for \[industry] benchmarks, then compare against my actual performance"* * *"Research what competitors are doing, then find keywords they're missing"* * *"Find industry best practices for \[strategy], then audit my account against them"* ### Use Multi-Step Instructions Computer excels at complex, numbered instructions. Give it a clear sequence: ``` 1. Do this first 2. Then do this 3. Based on steps 1-2, do this 4. Finally, summarize everything ``` ### Review Before Enabling Every campaign Computer creates via Adspirer starts **PAUSED**. Always review: * Keyword targeting and match types * Ad copy and headlines * Budget and bid strategy * Audience targeting * Geographic targeting ## Perplexity Computer vs Other Agents for Ads | Feature | Perplexity Computer | Manus | Codex | | - | :-: | :-: | :-: | | Web research + ads | Yes (native) | Yes | No | | Campaign creation | Yes | Yes | Yes | | Interactive dashboards | Yes | Yes | No | | Scheduled briefs | No | Yes | Yes | | Monitoring alerts | No | Yes | Yes | | Auth method | OAuth | API Key | OAuth | | Price | \$200/mo (Max) | Varies | Varies | **Bottom line:** Perplexity Computer is best when you need **research-driven ad management** — combining market intelligence with campaign execution. For ongoing monitoring and scheduled tasks, pair it with [Manus](/docs/ai-clients/manus) or [Codex](/docs/ai-clients/codex). ## Get Started **1. Set up Perplexity + Adspirer** Follow the [Perplexity Setup Guide](/docs/ai-clients/perplexity) to add Adspirer as a custom connector in Perplexity Computer. **2. Connect your ad platforms** Link your Google Ads, Meta Ads, LinkedIn Ads, and/or TikTok Ads accounts at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=guide\&utm_content=perplexity-computer). **3. Try the competitor research workflow** Copy the Competitor Research → Campaign Creation prompt from Workflow 1 above and customize it for your business. ## Related Documentation * [Perplexity Setup Guide](/docs/ai-clients/perplexity) — Connect Adspirer to Perplexity Computer * [Computer Use Agents](/docs/knowledge-base/computer-use-agents) — Overview of all supported autonomous agents * [Agent Skills Overview](/docs/agent-skills/overview) — Teach your AI the right workflows * [Google Ads Integration](/docs/ad-platforms/google-ads) — Full Google Ads tool reference * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Automate Ad Ops with Scheduled Tasks Source: https://www.adspirer.com/docs/guides/scheduled-tasks Run your Adspirer project on a schedule — a Monday scorecard, a mid-month pacing check, an alert when CPA drifts. What each assistant calls scheduling, how to write a recurring-task prompt that behaves, and what a cadence costs. Once your [project is set up](/docs/guides/set-up-your-project), the real payoff is automation: the same agent, run unattended on a cadence. A Monday performance scorecard. A mid-month pacing check. An alert the moment a campaign's CPA drifts past your target. You wake up to the answer instead of remembering to ask. ## What your assistant calls it Every client has this feature — the name and the reliability differ. | Assistant | Feature | Runs when your computer is off? | | - | - | - | | **ChatGPT** | Scheduled tasks | Yes — cloud-run, notifies by push + email | | **Codex** | Scheduled tasks (automations) | Yes | | **Claude Cowork** | Scheduled tasks, via the `/schedule` skill | Yes — they run remotely | | **Claude Code** | Routines: a *local* task **or** a *remote* routine | Local: **no**. Remote: yes | On most hosts you create one just by asking — *"every Monday at 9am, review my campaigns and post the three things worth my attention."* No UI hunting required. > [!WARNING] > > **The one that bites: a Claude Code *local* scheduled task only runs while the desktop app is open > and your computer is awake.** A laptop asleep at 9am silently skips the run (on wake it starts one > catch-up for the most recently missed time and discards the rest). For anything that matters — > budget pacing, spend spikes, disapprovals — create a **remote routine** instead: it runs on > Anthropic's infrastructure with the machine off. Cowork and ChatGPT scheduled tasks don't have > this problem. Codex **hooks** (`SessionStart`, `PostToolUse`, …) are event handlers, not a scheduler — never use one for a recurring report. ## Write a recurring prompt that behaves A scheduled prompt is different from a chat message: no one is there to answer a follow-up, and it may fire hours late. Write for that. > **Describe the result, not the steps** > > Say what you want to arrive — "a scorecard with spend, conversions, CPA, ROAS, and the three > things worth my attention" — and let the agent plan the tool calls. > **Goal · Context · Output · Boundaries** > > The four parts of a good work prompt: what to do, what to look at, the format and length, and > what must stay unchanged. > **Add a late-run guardrail** > > A 9am task might fire at 11pm after a sleep. Add: *"Only look at today's spend; if it's past > 6pm, just summarize what changed."* > **Refine first, then schedule** > > Get the prompt producing a reliable result in a normal chat, then turn that into the scheduled > version. Don't schedule a prompt you haven't seen run. Keep it read-only unless you mean otherwise. A scheduled run that changes budgets or status spends real money with no one watching — say **"propose, don't change"** unless you've built the full [safety model](/docs/guides/claude-cowork-ad-ops) for unattended writes. ## What a schedule costs Every scheduled run re-runs the work, which means it calls Adspirer tools again — each run draws on your monthly tool-call quota exactly like a live conversation. A **daily** review costs roughly thirty times a monthly one. Pick a cadence your plan can carry, and say what it should watch. **Weekly is the right default for a review; daily is for accounts spending enough to justify it.** Checking your usage is free — ask "what's my usage this month?" any time. ## Example task prompts > **Weekly performance scorecard (read-only)** > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > Every Monday at 9am, pull a cross-channel scorecard for my accounts — trailing 7d and 30d spend, > conversions, CPA, and ROAS per campaign — and post the three things worth my attention this week. > Read-only: propose changes, don't make any. If it runs late in the day, just summarize what > changed; don't start fresh analysis. > ``` > **Mid-month pacing check** > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > On the 15th, check month-to-date spend against my monthly budgets. For each budget pool, tell me: > projected end-of-month spend at the current pace, and whether I'm on track, under, or over. Flag > any campaign pacing to blow its cap. Don't change any budgets — just report. > ``` > **CPA alert (a monitoring task)** > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > Check my account once a day. If any campaign's CPA rises above my target, or spend pace projects > over budget for the month, tell me which campaign and by how much. Otherwise stay silent. Never > change budgets or status — only alert. > ``` > > A monitoring task re-checks and stays quiet until there's something worth saying — the right shape > for "tell me if my CPA moves." > **Competitor landing-page watch** > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > Every Monday, check for changes to their offer, pricing, or hero message, and > tell me what's different from last week. Summary only. > ``` ## Going further: unattended optimization The examples above only *read* and *propose*. To let a scheduled task actually **write** changes — reallocate budget, pause dead campaigns — you need the full safety model: shadow mode, per-run change caps, one writer per portfolio, propose-vs-act, and a kill switch. That's covered in depth here: > **[Cowork for Ad Ops](/docs/guides/claude-cowork-ad-ops)** > > The seven-property safety model for a self-optimizing task you can trust. > **[Set up your project](/docs/guides/set-up-your-project)** > > Instructions, context, memory, and connectors — the foundation a schedule runs on. # The Best Way to Set Up Your Project (Claude Cowork, ChatGPT, Claude Code, Codex) Source: https://www.adspirer.com/docs/guides/set-up-your-project The best way to set up an ad-ops project in Claude Cowork, ChatGPT, Claude Code, or Codex Desktop: one project per ad platform, agent instructions, agent context, scheduled tasks and routines, and agent skills — plus the Adspirer playbook that fills them in for you. The best way to run ads with an AI assistant is not a chat. It is a **project**: a persistent workspace where the agent already knows your business, your accounts, your rules, and your goals before you type a word. Claude Cowork, ChatGPT, Claude Code, and Codex Desktop all have one. The names differ; the shape is the same. > [!NOTE] > > Not connected yet? Connect [Adspirer](/docs/mcp) in your client first — > [Claude Cowork](/docs/ai-clients/claude-cowork), [ChatGPT](/docs/ai-clients/chatgpt), > [Claude Code](/docs/ai-clients/claude-code), [Codex Desktop](/docs/ai-clients/codex-desktop) — then come > back here. A project is where the connection lives; it is not a substitute for it. ## Set it up in your client Pick your client and follow the numbered steps. Each one puts the same five things in place: one project per ad platform, agent instructions, agent context, scheduled tasks, and agent skills. [What each part is for](#what-goes-in-a-project) is explained further down. For the folder-based clients (Claude Code Desktop, Claude Code Terminal, Codex Desktop) the whole install is one move: download the kit `.zip` from [Expert Space](#skip-the-blank-page-buy-an-agent-playbook), attach it to a chat, and send the install prompt. The agent unzips it, puts the skill where it loads skills from, checks that Adspirer is connected, and updates its own instructions and memory so every future session knows the expert exists. You never copy a file by hand. **Claude Cowork** Cowork has a dedicated field for every one of the five parts. Requires Claude Max, Team, or Enterprise, and the Adspirer plugin added from **Customize → Plugins** (Anthropic Directory) ([setup](/docs/ai-clients/claude-cowork)). **1. Open Cowork** In the Claude desktop app (or claude.ai), click the **Cowork** tab at the top. ![Claude desktop app with the Cowork tab selected](https://mintcdn.com/adspirer/0GXeYWLZAEKikC6R/images/claude-cowork/cowork-tab.png?fit=max\&auto=format\&n=0GXeYWLZAEKikC6R\&q=85\&s=5e3d0544af32ac28750034269dcdf5f5) The Cowork tab in the Claude desktop app **2. Create one project per platform** Click **+** next to **Projects** in the left sidebar. Start from scratch or **use an existing folder on your computer**; pointing it at a folder that already holds your brand documents is the fastest route. Name it *"Brand — Google Ads"*. **3. Paste the agent instructions** Open the project's **Instructions** panel and paste your instructions: the [template below](#2-agent-instructions), or the kit's `AGENTS.md` (the kit page's **Copy instructions** button puts it on your clipboard). Every task and every scheduled run in the project inherits them. **4. Add context to the Context folder** Drop your business docs, exemplars, P\&L summary, marketing docs, past-test log, and the kit's `references/account-profile.md` into the project's **Context** folder. Run `/setup` once and the plugin scans the folder, pulls live campaign data, and writes a brand context file alongside them. Leave **Memory** on. **5. Upload the skill** Click **Customize** in the left sidebar, open **Skills**, and upload the kit `.zip` as-is. It sits next to the skills the Adspirer plugin installed: those cover advertising in general, this one covers your account. **6. Confirm Adspirer and a notification channel** In **Customize → Connectors**, confirm **Adspirer Ads & Performance Marketing Agent** (the Anthropic-verified connector the plugin installs) shows **connected**, and link the ad accounts for this platform only. Set Interactive and Read-only tools to **Always allow** and leave Write/delete on **Needs approval**. Add Slack or email so scheduled runs can report. **7. Schedule the routines** In a chat inside the project, ask for the routine and Cowork offers to schedule it with `/schedule`. It appears in the **Scheduled** panel and runs remotely, laptop closed or not. Start with the weekly dashboard, read-only. The full Cowork build, including the seven-property safety model for self-optimizing tasks, is in [Cowork for Ad Ops](/docs/guides/claude-cowork-ad-ops). **ChatGPT** Projects, files, plugins, and skills all live in ChatGPT's **Work** mode. Connect the Adspirer app first ([setup](/docs/ai-clients/chatgpt)); Projects are on Plus, Pro, Business, and Enterprise. **1. Switch to Work** At the top of ChatGPT, flip the toggle from **Chat** to **Work**. The composer gains three chips underneath it: **Project**, **Files**, and **Plugins**. Everything below happens here. ![ChatGPT with the Work toggle selected, showing the Project, Files, and Plugins chips under the composer](https://mintcdn.com/adspirer/FUoqnFA1T6kM-gcS/images/set-up-your-project/chatgpt-work-mode.png?fit=max\&auto=format\&n=FUoqnFA1T6kM-gcS\&q=85\&s=0509e5e162243426280a4bcf7ffcf0dc) Work mode: the Project, Files, and Plugins chips under the composer **2. Create one project per platform** In the left sidebar, under **Projects**, create a new project and name it for the platform: *"Brand — Google Ads"*. Every chat you start inside it inherits the instructions, files, and plugins you set up next. ![ChatGPT sidebar with the Projects section expanded and a project listed](https://mintcdn.com/adspirer/FUoqnFA1T6kM-gcS/images/set-up-your-project/chatgpt-projects-sidebar.png?fit=max\&auto=format\&n=FUoqnFA1T6kM-gcS\&q=85\&s=afcb475574d7995c0afdd82429ac3887) Projects in the ChatGPT sidebar **3. Open Project settings** Open the project, click the **⋯** menu at the top right, and choose **Project settings**. ![ChatGPT project page with the three-dot menu open, showing Project settings and Pin project](https://mintcdn.com/adspirer/FUoqnFA1T6kM-gcS/images/set-up-your-project/chatgpt-project-menu.png?fit=max\&auto=format\&n=FUoqnFA1T6kM-gcS\&q=85\&s=6550872cbb71e4ca0763bd1efbebc816) The ⋯ menu on a project page **4. Paste the instructions and scope the memory** Paste your agent instructions into **Instructions**: the [template below](#2-agent-instructions), or the kit page's **Copy instructions** button. This field is the whole mechanism on Plus and Pro, so make it complete: business, role, goal, scope, rules. Under **Memory**, switch from **Default memory** to project-only memory so what the agent learns about Google Ads never leaks into your Meta project, or into chats outside it. Leave **Library access** enabled if your brand documents already live in your ChatGPT file library. ![ChatGPT Project settings dialog with the Instructions field, a Memory dropdown set to Default memory, and Library access enabled](https://mintcdn.com/adspirer/FUoqnFA1T6kM-gcS/images/set-up-your-project/chatgpt-project-settings.png?fit=max\&auto=format\&n=FUoqnFA1T6kM-gcS\&q=85\&s=60c9edf14eb40224a728548adb830777) Project settings: Instructions, Memory, and Library access **5. Upload context under Files** Click the **Files** chip and add your business docs, exemplars, P\&L summary, marketing docs, past-test log, and the kit's `references/account-profile.md` and `PROMPTBOOK.md`. Keep them short; ChatGPT reads them on demand. **6. Turn on Adspirer under Plugins** Click the **Plugins** chip and make sure your Adspirer custom MCP server is on for this project. It appears under the name you gave it, e.g. **Adspirer-Custom**. **7. Upload the skill** Open the **Plugins** page, switch the toggle at the top to **Skills**, click **+**, and choose **Upload from your computer**. Pick the kit `.zip`. ChatGPT scans it and the skill is available in every project. ![ChatGPT Skills page with the plus menu open, showing Create with chat, Create with editor, and Upload from your computer](https://mintcdn.com/adspirer/FUoqnFA1T6kM-gcS/images/set-up-your-project/chatgpt-skills-upload.png?fit=max\&auto=format\&n=FUoqnFA1T6kM-gcS\&q=85\&s=7dcc335bfb50c03b75f0b842a150df7b) Skills: + → Upload from your computer Don't see **Skills**? Your plan doesn't include it yet. The instructions field and the Adspirer plugin's built-in skills carry the same behavior; see the [plan note](/docs/agent-skills/prompt-engineering-playbook#chatgpt). **8. Schedule the routines** In a chat inside the project, ask: *"Every Monday at 8am, build my dashboard…"*. ChatGPT creates a **scheduled task** that runs in the cloud and notifies you by push and email. Mention your Adspirer plugin by name (e.g. **@Adspirer-Custom**) if ChatGPT is slow to call tools on its own. > [!NOTE] > > Connect Adspirer as a [custom MCP server](/docs/ai-clients/chatgpt), not the Adspirer plugin > from ChatGPT's directory. The plugin is having issues right now and has no Amazon Ads, > ChatGPT Ads, or Google Analytics tools. **Claude Code Desktop** Claude Code's desktop app works inside a folder. The folder *is* the project: instructions are `CLAUDE.md`, context is the files beside it, skills live in `.claude/skills/`, and routines run the folder on a schedule. Install the Adspirer plugin first ([setup](/docs/ai-clients/claude-code)). **1. Download the kit** Go to [adspirer.ai/expert-space](https://adspirer.ai/expert-space), open the kit for this account, and click **Download kit (.zip)**. Don't unzip it. **2. Open one folder per platform** Create a folder per platform, *`acme-google-ads/`*, *`acme-meta-ads/`*, and open it in the Claude Code desktop app. Everything the agent knows about this platform lives in this folder and nowhere else. **3. Attach the zip and send the install prompt** Drag the `.zip` into the composer (or click **+** and attach it), then send: The install prompt. Claude Code unzips the kit, installs the skill, checks Adspirer, and updates its own instructions and memory. Here are the agent skills I want to install. Unzip this kit and install it for this project: * Put the skill folder in .claude/skills/ and register the agent definition it ships in .claude/agents/. * Keep AGENTS.md inside the skill folder; don't overwrite anything at my project root. * Make sure the Adspirer connector ([https://mcp.adspirer.com/mcp](https://mcp.adspirer.com/mcp)) is set up and active. If it isn't, install the adspirer-ads-agent plugin and walk me through signing in. * Update this project's CLAUDE.md and your memory so every future session knows this expert exists, which ad account it covers, and to use it for any work on that account. * Verify every file against the zip, then tell me what you installed and where. Claude Code reports the skill path, the agent it registered, the Adspirer connection status, and what it added to `CLAUDE.md`. Skills are picked up without a restart. **4. Put context in the folder** Add a `context/` subfolder with your business docs, exemplars, P\&L summary, marketing docs, and past-test log. Run `/adspirer:refresh-brand-context` whenever the folder changes materially. Files on disk persist, so this is your memory too. **5. Create remote routines** Ask Claude Code to run the dashboard every Monday. Choose a **remote routine**, which runs on Anthropic's infrastructure with your laptop closed, over a local task, which silently skips if your machine is asleep. **Claude Code Terminal** Same folder, same files, same install prompt as the desktop app; the only difference is how you hand over the zip. Install the Adspirer plugin first ([setup](/docs/ai-clients/claude-code)). **1. Download the kit** Go to [adspirer.ai/expert-space](https://adspirer.ai/expert-space), open the kit for this account, and click **Download kit (.zip)**. Don't unzip it. **2. Open the platform folder in Claude Code** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} cd ~/Clients/acme-google-ads claude ``` One folder per platform. Everything the agent knows about Google Ads lives here. **3. Send the install prompt with the zip path** Drag the `.zip` from Finder into the terminal window to paste its path, then send: The install prompt. Replace the path with wherever the zip landed. Here are the agent skills I want to install: \~/Downloads/google-ads-expert-acme.zip. Unzip it and install it for this project: * Put the skill folder in .claude/skills/ and register the agent definition it ships in .claude/agents/. * Keep AGENTS.md inside the skill folder; don't overwrite anything at my project root. * Make sure the Adspirer connector ([https://mcp.adspirer.com/mcp](https://mcp.adspirer.com/mcp)) is set up and active. If it isn't, install the adspirer-ads-agent plugin and walk me through signing in. * Update this project's CLAUDE.md and your memory so every future session knows this expert exists, which ad account it covers, and to use it for any work on that account. * Verify every file against the zip, then tell me what you installed and where. Confirm with `/skills`, or invoke the expert directly as `/google-ads-expert-`. **4. Put context in the folder** Add a `context/` subfolder with your business docs, exemplars, P\&L summary, marketing docs, and past-test log, then run `/adspirer:refresh-brand-context`. **5. Create remote routines** Ask for the weekly dashboard as a **remote routine**. A local task only runs while the machine is awake. **Codex Desktop** Codex inside the ChatGPT desktop app works the same way: a folder is the project, and you hand Codex the zip. Install the Adspirer plugin with three chat messages first ([setup](/docs/ai-clients/codex-desktop)). **1. Download the kit** Go to [adspirer.ai/expert-space](https://adspirer.ai/expert-space), open the kit for this account, and click **Download kit (.zip)**. Don't unzip it. **2. Open one folder per platform** Switch to **Codex** in the top-left dropdown, click **New chat**, and when Codex asks where to work, pick or create a folder for this platform: *`acme-google-ads/`*. Keep other platforms in their own folders. ![ChatGPT desktop app with Codex selected, showing the Codex sidebar and a new chat asking what to work on](https://mintcdn.com/adspirer/My0vMqzyp3JsH-jn/images/codex-desktop/codex-home.png?fit=max\&auto=format\&n=My0vMqzyp3JsH-jn\&q=85\&s=526c9a678d6cb3b02ecd6bfd0d0ee561) Codex selected in the top-left dropdown, ready for a new chat **3. Attach the zip and send the install prompt** Click **+** in the composer (or drag the `.zip` in), then send: The install prompt. Codex unzips the kit, installs the skill and agent, checks Adspirer, and updates AGENTS.md. Here are the agent skills I want to install. Unzip this kit and install it for this project: * Put the skill folder in .agents/skills/ and register the agent definition it ships in .codex/agents/. * Keep the kit's AGENTS.md inside the skill folder; don't replace the AGENTS.md at my project root. * Make sure the Adspirer connector ([https://mcp.adspirer.com/mcp](https://mcp.adspirer.com/mcp)) is set up and active. If it isn't, install the adspirer-ads-agent plugin and walk me through signing in. * Update this project's AGENTS.md (append, don't replace) and your memory so every future session knows this expert exists, which ad account it covers, and to use it for any work on that account. * Verify every file against the zip, then tell me what you installed and where. Codex ends with a link to the new agent. Click it, or start a **New chat** and ask for the expert by name. **4. Put context in the folder** Add your business docs, exemplars, P\&L summary, marketing docs, and past-test log to the folder. With **Computer use** on, Codex can also read a budget sheet in Excel or check something in Ads Manager that the API doesn't expose; leave Chrome on ask-each-time for ad platform sites. **5. Schedule the routines** Ask Codex to run the dashboard weekly and it sets up a scheduled task (Codex calls them automations) that runs in the cloud. For heavier autonomous setups, the [Codex terminal guide](/docs/ai-clients/codex) covers agent configuration; your Adspirer sign-in carries over. > [!NOTE] > > Using Claude chat projects on claude.ai rather than Cowork? The pattern is identical: **Set > project instructions**, upload context under project knowledge, upload the kit `.zip` under > **Customize → Skills**. The [playbook page](/docs/agent-skills/prompt-engineering-playbook#set-up-the-project-then-run-the-prompts) > walks through it. ## What goes in a project A well-built project has five parts. Get all five in place and the agent stops being a clever chatbot and starts behaving like a media buyer who has been on the account for a year. | Part | What it is | What it does for you | | - | - | - | | **1. One project per ad platform** | A separate project for Google Ads, another for Meta, another for TikTok | The agent never mixes accounts, currencies, or platform rules | | **2. Agent instructions** | Who the agent is, what business it serves, what it optimizes for, what it must never do | Safe, on-goal behavior by default, in every chat | | **3. Agent context** | Your business documents, exemplars, P\&L, marketing docs, and what has and hasn't worked | Recommendations and copy grounded in your reality, not generic advice | | **4. Scheduled tasks and routines** | The same agent, run unattended on a cadence | Dashboards, pacing checks, and small approved changes happen without you asking | | **5. Agent skills** | Step-by-step playbooks the agent loads when a task matches | Campaign builds, audits, and optimizations done the right way, every time | > [!TIP] > > **Don't want to write any of this yourself?** The [agent playbook](#skip-the-blank-page-buy-an-agent-playbook) > from Expert Space is generated from your real ad account and ships every one of these parts as a > file you upload into the right place. The rest of this page explains what each part is for, so > you know where the files go and why. ## 1. One project per ad platform Create **one project for each ad platform you run**. Google Ads gets a project. Meta gets a project. TikTok, LinkedIn, and Amazon each get a project. Which AI client you use doesn't change this; it is the same rule in Claude Cowork, ChatGPT, Claude Code, and Codex. Why the boundary matters: * **Each platform has its own rules.** Google budgets are in dollars, Meta's are in the ad account's currency, TikTok rejects invalid objective and pixel combinations instead of correcting them. An agent scoped to one platform learns one rulebook and applies it correctly. * **Account IDs never cross.** The single worst ad-ops mistake is a change landing in the wrong account. A project pinned to one platform, with its account IDs written into the instructions, makes that structurally impossible. * **Context stays relevant.** Your Meta exemplars are noise in a Google Search project. Splitting by platform keeps every file in the project useful to every task. * **Automation stays safe.** Scheduled tasks inherit the project. One project per platform means one writer per portfolio, so two routines can never fight over the same campaigns. Name projects so the platform is obvious from the sidebar: *"Acme — Google Ads"*, *"Acme — Meta Ads"*. Agencies add the client: *"Acme — Google Ads"*, *"Bolt Coffee — Google Ads"*. One project per client per platform is more projects, and that is the point. See [managing multiple clients](/docs/knowledge-base/multi-client) for the agency pattern in full. Inside each project, connect Adspirer and link only the ad accounts that belong there. Add a notification channel (Slack or email) if your client supports one, so scheduled runs have somewhere to report. ## 2. Agent instructions Instructions are the agent's constitution: read on every task, always on. They are the difference between an assistant that asks "which account?" every session and one that already knows. Write them in five short sections: | Section | What to write | Example | | - | - | - | | **The business** | What you sell, to whom, at what price point, and what a customer is worth | *"We sell a $49/mo inventory tool to independent restaurants in the US. A trial is worth ~$180 in LTV."* | | **The agent's role** | What job it holds on the team and how much it decides on its own | *"You are the paid-media agent running Google Ads. You analyze, propose, and build on approval."* | | **The goal** | The one metric it optimizes toward, with the number | *"Target CPA \$45 on trial signups. Scale spend while CPA holds under target."* | | **The scope** | The exact platform and account IDs it may touch | *"Google Ads account 123-456-7890 only. Stop if a tool result mentions any other account."* | | **The golden rules** | What it must never do without you | Create paused, never launch. Money needs an explicit yes. Read before write. Never invent a number. | Then set the agent's **default mode** to how you actually work: * **Builder** — you hand it approved briefs and want campaigns built, verified, and monitored. Copy stays locked; it validates and reports, never rewrites. * **Advisor** — you want the portfolio truth and a recommendation. It analyzes and proposes, builds only when asked, and every budget call stays yours. > **Copy-paste: starter agent instructions** > > ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}} > # Agent instructions — Google Ads paid-media agent (Adspirer) > > ## The business > Seasonality, promotions, and anything a new hire would need to know on day one.> > > ## Your role > You are the paid-media agent for 's Google Ads account, working through the > Adspirer connector. You analyze, propose, and build on approval. Humans decide WHAT > to run; you build it exactly as specified, verify it, and flag anything that isn't right. > > ## What we're optimizing for > - North-star metric: > - A conversion is: > - Secondary signals to report, never to optimize toward: > > ## Scope > - Google Ads account only. If a tool result references any other account, stop > and tell me before continuing. > - Budget units: Google = dollars. Report spend in USD. > > ## Golden rules (never break) > 1. Nothing goes live without a human. Create every campaign PAUSED. Never enable or launch. > 2. Money needs a yes. No budget raise, bid change, or resume without explicit approval. > 3. Read before you write; verify after. Report what exists, not what you asked for. > 4. Validate, don't edit. Copy over a platform limit? Stop and report the field and length. > 5. Never invent a number. If a tool fails or data is missing, say so. > 6. Pause, don't delete. > > ## Context you should read > - `context/` holds our brand guide, exemplars, P&L summary, and past-test log. Read it > before proposing creative or budget changes. Live account data wins over any file. > ``` **The rule that keeps instructions useful: rules go in instructions, data goes in context.** Don't paste your brand guide into the instructions field. Don't put "never launch" in a document the agent might skip. Procedures and non-negotiables live here; everything the agent should *read* lives in the next part. For the full always-on version, with the standard operating loop and the interactive-versus-scheduled monitoring split, see [Cowork for Ad Ops](/docs/guides/claude-cowork-ad-ops). ## 3. Agent context Context is the data that makes the agent sharp. An agent with instructions but no context knows the rules and nothing about you. Give it what you'd give a senior hire in their first week. | Upload this | Why the agent needs it | | - | - | | **Business documents** — positioning, offer sheet, pricing, ICP, sales deck | So ad copy says what you actually sell, to the people who actually buy | | **Exemplars** — your best-performing ads, landing pages, emails, and the ones that flopped | So generated copy sounds like your winners and avoids your losers | | **P\&L or margin data** — contribution margin by product line, CAC targets, payback window | So "scale this" is judged against real economics, not just a CPA | | **Marketing documents** — brand guide, voice, messaging pillars, seasonal calendar, promo schedule | So copy passes brand review and campaigns line up with launches | | **What has and hasn't worked** — a log of past tests, structures you abandoned, audiences that never converted | So the agent doesn't re-propose something you already killed | | **Naming conventions** — campaign, ad group, and UTM structure | So new builds slot into your reporting without cleanup | | **Audience and exclusion lists** — negative keywords, excluded placements, suppression lists | So known waste never comes back | | **A recent performance export** | A baseline the agent can compare against before its first live pull | Keep the files short and current. A two-page brand summary beats a forty-page deck. Date anything that goes stale, and tell the agent in its instructions that live account data wins over any file. > [!TIP] > > **A brand folder is the fastest way to give context.** Claude Cowork, Claude Code, and Codex > all work inside a folder on your computer. Put the documents above in it and the agent reads > them; run `/setup` (Cowork, Claude Code) or ask Codex to set up the workspace, and the Adspirer > plugin scans the folder, pulls live campaign data, and writes a context file for you. **Leave memory on** where your client offers it. Project memory lets the agent carry naming decisions, prior builds, and your preferences across sessions, and it is scoped to the project so one platform's memories never leak into another's. ## 4. Scheduled tasks and routines A project pays for itself when the agent runs without you. The same instructions, context, and skills, on a cadence, reporting to a channel you watch. This is what the agent can do automatically: | Routine | Cadence | What it does | Writes to the account? | | - | - | - | - | | **Performance dashboard** | Daily or weekly | Builds a scorecard: spend, conversions, CPA (Cost per acquisition), ROAS (Return on ad spend) per campaign, plus the three things worth your attention. In Claude it can publish as a live artifact; in ChatGPT as a hosted page. | No | | **Pacing check** | Weekly and mid-month | Month-to-date spend versus budget, projected end-of-month, campaigns about to blow their cap | No | | **CPA / spend alert** | Daily | Stays silent unless a campaign crosses your target, then tells you which one and by how much | No | | **Search-term and placement hygiene** | Weekly | Proposes negatives and exclusions from last week's waste | Proposes only, or applies within a cap you set | | **Small optimizations** | Weekly | Budget shifts of a few percent between campaigns, bid adjustments inside a range, pausing ads with zero conversions after a threshold | Yes, within hard caps, with a report every run | | **Competitor watch** | Weekly | Checks competitor landing pages for offer, price, or hero changes | No | Start every routine **read-only**. Let it propose for a few weeks, check its proposals against what you'd have done, and only then let it apply small, reversible changes with a per-run cap. A routine that changes budgets with nobody watching spends real money; the [safety model for unattended changes](/docs/guides/claude-cowork-ad-ops#the-safety-model-for-unattended-changes) covers shadow mode, change caps, single writer, and the kill switch. What each client calls it: | Client | Feature | Runs when your computer is off? | | - | - | - | | **Claude Cowork** | Scheduled tasks, via the `/schedule` skill | Yes | | **ChatGPT** | Scheduled tasks | Yes | | **Claude Code** | Routines: a *local* task or a *remote* routine | Local: no. Remote: yes | | **Codex** | Scheduled tasks (automations) | Yes | > [!WARNING] > > A Claude Code **local** routine only runs while the desktop app is open and your computer is > awake. For anything that matters, pacing, spend spikes, disapprovals, create a **remote > routine** instead. Cowork and ChatGPT scheduled tasks don't have this problem. A weekly dashboard routine. Paste it as a scheduled task in any client. Every Monday at 8am, build my Google Ads dashboard for last week: spend, conversions, CPA, and ROAS per campaign, week-over-week change, and month-to-date pacing against budget. Lead with the three things worth my attention. Read-only: propose changes, don't make any. If it runs late in the day, summarize what changed instead of starting fresh. A small-changes routine with hard caps. Only after weeks of read-only runs. Every Wednesday at 7am, review last 7 days of search terms across active campaigns. Add negatives for terms with 20+ clicks and zero conversions. Shift up to 10% of daily budget from campaigns above target CPA to campaigns below it, never more than \$50 per campaign per run. Never pause a campaign, never touch bid strategy. Report every change you made and every change you chose not to make. Every scheduled run calls Adspirer tools again, so it draws on your monthly tool-call quota like a live conversation. Weekly is the right default for a review; daily is for accounts spending enough to justify it. The [scheduled tasks guide](/docs/guides/scheduled-tasks) has more example prompts and the late-run guardrails that keep a routine honest. ## 5. Agent skills A skill is a step-by-step playbook for one job, loaded only when a task matches. Instructions say *what the agent may do*; a skill says *exactly how to do it*. That split is what lets you give the agent deep procedures without bloating every chat. Adspirer ships **13 free skills** with every plan: the safety contract, the tool-call contract, one skill per platform, and cross-platform workflows for launching, reviewing, optimizing, and writing creative. They install with the Adspirer plugin in Cowork, Claude Code, and Codex, and ship inside the ChatGPT plugin. You never invoke them by name; describe the task and the agent picks the skill. | You say | Skill that loads | What it enforces | | - | - | - | | "How did we do last week?" | `adspirer-performance-review` | Cross-platform scorecard, tracking audit, read-only | | "Launch a search campaign for the spring promo" | `adspirer-launch` → `adspirer-google-ads` | Keyword research first, platform field rules, created paused, verified after | | "Find wasted spend" | `adspirer-optimize` | Search terms, placements, pacing, reallocation proposals | | "Write three headlines in our voice" | `adspirer-creative` | Reads your brand context, respects character limits | Skills sit in a different place from instructions in every client: the **Skills** panel in Cowork and ChatGPT, a `.claude/skills/` folder in Claude Code, `.agents/skills/` in Codex. Keep them there. Don't paste a skill into the instructions field, and don't drop it into context as a document. Reference skills *by name* from instructions and scheduled-task prompts when you want to force one. The free skills know advertising. They don't know your account. The [agent playbook](#skip-the-blank-page-buy-an-agent-playbook) below adds a skill that does. Full reference: [Agent Skills](/docs/agent-skills/skills). ## Where each part lives, by client | Part | Claude Cowork | ChatGPT | Claude Code (desktop or terminal) | Codex Desktop | | - | - | - | - | - | | **Project per platform** | Projects sidebar, one per platform | Projects sidebar, one per platform | One folder per platform | One folder per platform | | **Agent instructions** | **Instructions** panel | Project **Instructions** | `CLAUDE.md` | `AGENTS.md` | | **Agent context** | **Context** folder + Memory | Project **Files** + Memory | Files in the folder | Files in the folder | | **Scheduled tasks** | **Scheduled** panel, via `/schedule` | Scheduled tasks | Routines (choose remote) | Scheduled tasks (automations) | | **Agent skills** | **Customize → Skills** | **Skills** (Business/Enterprise/Edu) | `.claude/skills/` | `.agents/skills/` | ## Skip the blank page: buy an agent playbook You don't have to write any of this from scratch. Adspirer generates an **agent playbook** for any ad account you've connected, built from that account's real campaigns, spend history, and current state. It ships as a download containing every part of the project above, ready to upload into the right place. **1. Open Expert Space** Go to [adspirer.ai/expert-space](https://adspirer.ai/expert-space). You'll see one card per connected ad account, grouped by platform, which is also why the one-project-per-platform rule fits it: one playbook covers one account. **2. Preview, then buy** **Preview Expert** shows sample prompts before you pay. Buy one account, or tick several and check out together. It's a one-time purchase per account, and annual plans include one free; [pricing and the bundle discount](/docs/agent-skills/prompt-engineering-playbook#price) are on the playbook page. **3. Download the kit** The build takes a few minutes. From the kit page, click **Download kit (.zip)**, or hit **Copy instructions** to put the agent instructions straight on your clipboard. Unzip it and you get one folder, named like `google-ads-expert-/`. **4. Upload each file into its part of the project** The kit is laid out to match this page. Use the table below. What's in the download, and where it goes: | File in the kit | Part of the project | Where to put it | | - | - | - | | `AGENTS.md` | **Agent instructions** — the account-pinned constitution: business scope, role, account ID, currency, golden rules | Paste into the Instructions field (Cowork, ChatGPT). Folder clients keep it inside the skill; Codex installs it for you. | | `references/account-profile.md` | **Agent context** — a written dossier of the account: what state it's in, operating priorities, weekly and monthly cadence | Context folder (Cowork), project Files (ChatGPT), the project folder (Claude Code, Codex) | | `references/working-with-adspirer.md` | **Agent context** — the tool-calling contract and guardrails | Stays inside the skill folder; loads on demand | | `SKILL.md` | **Agent skill** — the operating doctrine for this one account: wasted-spend triage, tracking audit, pacing, bidding, testing discipline | **Customize → Skills** (Cowork, Claude), **Skills** (ChatGPT Business+), `.claude/skills/` (Claude Code), hand the folder to Codex | | `PROMPTBOOK.md` | **Scheduled tasks and routines** — a menu of prompts graded Beginner → Expert, written against your account. Its daily-ops and analysis prompts are your first routines. | Read it; copy a prompt into a scheduled task once it has proven itself in a live chat | | `README.md` | Says where each piece goes, per client | Read once | > [!TIP] > > The playbook follows the rule this page is built on without you thinking about it: `AGENTS.md` > is rules, `account-profile.md` is data, `SKILL.md` is procedure, and they arrive as separate files > so they land in separate places. The dossier is a dated snapshot; the agent is told live account > data always wins, and rebuilding the kit against fresh data is free and unlimited from > **Refresh** on the kit page. The full install steps for every client, what each build stage does, and the FAQ are on the [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) page. ## Checklist Before you call the project done: * One project per ad platform, named so the platform is obvious, with only that platform's accounts linked * Instructions cover the business, the agent's role, the north-star metric, the exact account IDs, and the golden rules * Context holds your brand guide, exemplars, margin data, marketing docs, and what has and hasn't worked * Adspirer connected inside the project, with a notification channel for scheduled runs * Skills installed in the Skills panel or skills folder, not pasted into instructions * At least one read-only routine running: the weekly dashboard * Memory on Then open a chat inside the project and ask: The first prompt in any new project. The agent reads its instructions, context, and the live account, then tells you what it sees. Introduce yourself and give me your read on the account. ## Where to go next > **[Scheduled tasks](/docs/guides/scheduled-tasks)** > > More routine prompts, late-run guardrails, and what a cadence costs in tool calls. > **[Cowork for Ad Ops](/docs/guides/claude-cowork-ad-ops)** > > The full always-on build and the safety model for routines that make changes. > **[Agent Skills](/docs/agent-skills/skills)** > > The 13 free skills, what each enforces, and how to install them per client. > **[Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook)** > > The agent playbook from Expert Space: instructions, dossier, skill, and prompt book generated from your account. > **[Managing multiple clients](/docs/knowledge-base/multi-client)** > > One project per client per platform, without letting automation collide. > **[Connect your AI client](/docs/mcp)** > > Cowork, ChatGPT, Claude Code, Codex Desktop, and every other client Adspirer supports. # TikTok Ads Guide: Complete Advertising Playbook for 2025 Source: https://www.adspirer.com/docs/guides/tiktok-ads-guide The complete TikTok Ads guide for 2025. Learn campaign setup, creative best practices, audience targeting, and AI-powered automation strategies. Reach billions of engaged users with TikTok advertising ## Why Advertise on TikTok? TikTok has over 1 billion monthly active users and is the fastest-growing social platform. Here's why advertisers are flocking to TikTok: **Engagement**: Users spend an average of 95 minutes per day on TikTok **Discovery**: The algorithm surfaces content to interested users regardless of follower count **Demographics**: While Gen Z dominates, 36% of users are now 35+ **Intent**: TikTok search is becoming a product discovery engine **Cost**: CPMs (Cost Per Mille — cost per 1,000 ad impressions) are often lower than Meta and Google for similar audiences TikTok isn't just for dance videos anymore---it's a serious advertising platform that can drive real business results. ## TikTok Ad Formats **In-Feed Ads** Native video ads that appear in the For You feed. The most common format for performance advertisers. **TopView Ads** Premium placement that appears when users first open the app. Great for brand awareness. **Spark Ads** Boost organic TikTok posts (yours or creators') as ads. High authenticity and engagement. **Branded Hashtag Challenges** Encourage user-generated content around your brand. Best for large-scale awareness campaigns. **Branded Effects** Custom filters and effects users can add to their videos. Interactive brand engagement. **Shopping Ads** Product catalog integration for e-commerce. Drive direct purchases from the platform. ## TikTok Creative Best Practices TikTok ads that perform look native to the platform. Here's what works: **Hook in 3 Seconds**: Capture attention immediately---users scroll fast **Vertical Video**: Always 9:16 aspect ratio, full-screen experience **Sound On**: TikTok is a sound-on platform---music and voiceovers matter **Authenticity**: Polished ads often underperform raw, genuine content **Trends**: Incorporate trending sounds, formats, and hashtags **CTAs**: Clear calls to action, but integrated naturally **Creator-Style**: User-generated content often outperforms brand-produced ads The TikTok mantra: "Don't make ads, make TikToks." ## Automating TikTok Ads with AI Managing TikTok Ads alongside Google and Meta can be overwhelming. AI automation helps by: **Unified Management**: Control all platforms from one conversation **Creative Testing**: Quickly launch multiple ad variations **Budget Optimization**: Shift spend to best-performing ads automatically **Reporting**: Get cross-platform performance summaries instantly With Adspirer, you can manage TikTok Ads using natural language: * "Show me my TikTok campaign performance this week" * "Create a new TikTok campaign targeting 25-34 year olds interested in fitness" * "Pause all TikTok ads with CTR below 0.5%" No more switching between dashboards---manage everything through your AI assistant. ## FAQ > **How much does it cost to advertise on TikTok?** > > TikTok Ads start at $50/day campaign minimum. CPMs typically range from $6-15 depending on targeting and competition. Many advertisers find TikTok more cost-effective than Meta for reaching younger audiences. > **What type of businesses should advertise on TikTok?** > > TikTok works well for D2C e-commerce, apps, entertainment, beauty, fashion, food & beverage, and any business targeting consumers under 45. B2B can work but requires more creative adaptation. > **Do TikTok Ads actually convert?** > > Yes. Many e-commerce brands report strong ROAS on TikTok, especially with Spark Ads and Shopping Ads. The key is creating native-feeling content that doesn't look like traditional advertising. > **Can I manage TikTok Ads with AI?** > > Yes. Adspirer connects TikTok Ads to ChatGPT and Claude, allowing you to create, manage, and optimize campaigns through natural language conversations. > **How is TikTok advertising different from Meta?** > > TikTok prioritizes entertainment and authenticity over polished production. Vertical video is mandatory, sound is essential, and creative fatigue happens faster---requiring more frequent creative refreshes. ## Related Documentation * [The Death of the Dashboard: Why 2025 is the Era of Agentic Advertising](https://www.adspirer.com/blog/death-of-the-dashboard) * TikTok Ads for E-commerce: Complete Guide (coming soon) * TikTok vs Meta Ads: Where to Spend Your Budget (coming soon) * TikTok Creative Testing: A Framework for Winning Ads (coming soon) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # How Adspirer Works: Architecture, OAuth & Data Flow Source: https://www.adspirer.com/docs/how-it-works End-to-end Adspirer architecture: how AI assistants connect to ad platforms over MCP, OAuth flow, tool execution, safety model, and data flow. Adspirer sits between your AI assistant and your ad platforms. You talk to your AI in natural language. Adspirer translates that into authenticated API calls to Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads — and returns results back to your conversation. ## The Full Pipeline ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[You] -->|Natural language| B[AI Client] B -->|MCP tool call| C[Adspirer MCP Server] C -->|OAuth 2.1| D{Ad Platform APIs} D --> E[Google Ads API] D --> F[Meta Marketing API] D --> G[Amazon Advertising API] D --> H[OpenAI Ads API] D --> I[LinkedIn Marketing API] D --> J[TikTok Marketing API] E & F & G & H & I & J -->|API response| C C -->|Structured result| B B -->|Formatted answer| A ``` Every interaction follows this path. Whether you're pulling a performance report or creating a campaign, the pipeline is the same. *** ## Layer 1: Your AI Client Your AI assistant — Claude, ChatGPT, Gemini CLI, Perplexity, Cursor, Codex, or any MCP-compatible client — is the interface. You describe what you want in plain English: * *"How are my Google Ads performing this month?"* * *"Create a LinkedIn campaign targeting IT Directors"* * *"Find wasted spend across all platforms"* The AI determines which Adspirer tools to call and in what order. With [skills](/docs/agent-skills/overview) installed, it follows proven workflows. Without skills, it makes its best guess. ### What the AI Client Provides | Capability | Description | | - | - | | Natural language understanding | Translates your request into tool calls | | Multi-step reasoning | Chains multiple tools in sequence | | Context from files | Reads brand context, strategy, and memory files | | User confirmation | Asks before spend-affecting actions | | Result formatting | Presents data as tables, charts, and recommendations | *** ## Layer 2: MCP (Model Context Protocol) MCP (Model Context Protocol — an open standard created by Anthropic for connecting AI assistants to external tools) is the protocol that connects your AI client to Adspirer. It's an open standard — any AI client that supports MCP can use Adspirer. ### What MCP Does * **Tool discovery:** Your AI client discovers Adspirer's 400+ tools with descriptions and parameters * **Tool invocation:** When the AI decides to use a tool, it sends a structured request via MCP * **Response delivery:** Adspirer returns structured results that the AI formats for you * **Authentication:** OAuth flows are triggered transparently through MCP ### One URL, All Platforms Every AI client connects to the same MCP endpoint: ``` https://mcp.adspirer.com/mcp ``` This single URL gives access to all 400+ tools across all 6 ad platforms. Your AI client doesn't need to know about Google Ads APIs, Meta APIs, or LinkedIn APIs — Adspirer handles all of that behind the MCP layer. ### Tool Categories Adspirer exposes tools in two categories: * Read **tools** pull data and analyze performance. Safe to run anytime. No spending impact. Examples: `get_campaign_performance`, `research_keywords`, `analyze_wasted_spend`. * Write **tools** create or modify campaigns. Require user confirmation. Affect spend. Examples: `create_search_campaign`, `update_campaign`, `add_keywords`. *** ## Layer 3: Authentication (OAuth 2.1 with PKCE) When you first connect an ad platform, Adspirer uses **OAuth 2.1 with PKCE** — the same standard used by banking apps. ### The OAuth Flow **1. You trigger a connection** Either through your AI client's MCP settings or by running setup (`/adspirer:setup`). **2. Browser opens** You're redirected to the ad platform's login page (Google, Meta, Amazon, ChatGPT, LinkedIn, or TikTok). You sign in with your existing credentials. **3. You authorize permissions** You see exactly what Adspirer is requesting (read campaigns, create ads, manage budgets). You approve. **4. Tokens are issued** The ad platform issues an access token (1-hour lifetime) and refresh token (30-day lifetime). Adspirer stores these encrypted at rest. **5. Automatic refresh** When the access token expires, Adspirer automatically uses the refresh token to get a new one — no re-login needed until the refresh token expires (30 days). ### What Adspirer Never Sees * Your ad platform password * Your billing/payment information * Data from accounts you haven't connected * Personal data beyond what's in your ad account settings *** ## Layer 4: Ad Platform APIs Adspirer translates MCP tool calls into native API calls for each platform: | Adspirer Tool | Platform API Called | What It Does | | - | - | - | | `get_campaign_performance` | Google Ads API | Pulls campaign metrics (spend, CTR, CPA, ROAS) | | `research_keywords` | Google Keyword Planner API | Returns keyword ideas with real CPC data | | `create_search_campaign` | Google Ads API | Creates a Search campaign (PAUSED) | | `get_meta_campaign_performance` | Meta Marketing API | Pulls Meta campaign metrics | | `create_meta_image_campaign` | Meta Marketing API | Creates an image ad campaign | | `get_amazon_campaign_performance` | Amazon Advertising API | Pulls Amazon metrics (spend, sales, ACOS, ROAS) | | `create_amazon_sp_campaign` | Amazon Advertising API | Creates a Sponsored Products campaign (PAUSED) | | `get_chatgpt_performance` | OpenAI Ads API | Pulls ChatGPT Ads metrics (impressions, clicks, spend, CTR, CPC) | | `launch_chatgpt_ad` | OpenAI Ads API | Builds a pay-per-click chat-card ad campaign (PAUSED) | | `get_linkedin_campaign_performance` | LinkedIn Marketing API | Pulls LinkedIn campaign metrics | | `create_linkedin_image_campaign` | LinkedIn Marketing API | Creates a sponsored content campaign | | `google_analytics` | Google Analytics Data API (via Pipedream Connect) | Pulls GA4 property data — sessions, conversions, traffic sources, landing pages | | `klaviyo` | Klaviyo API (via Pipedream Connect) | Pulls campaigns, flows, segments, profiles, and metrics | Each API call uses the OAuth token from your authenticated session. Adspirer handles rate limiting, pagination, error handling, and response formatting. > [!NOTE] > > **Marketing stack integrations** (Google Analytics, Klaviyo, Google Search Console) are brokered through [Pipedream Connect](https://pipedream.com/connect) — the OAuth token lives in Pipedream scoped to your Adspirer user, and Adspirer proxies tool calls to Pipedream's remote MCP. Adspirer never sees the raw third-party credentials. Available on Plus, Pro, and Max plans. *** ## Layer 5: Skills & Agent (Optional) Without skills, your AI calls tools individually and guesses the workflow. With skills and the agent, you get structured workflows, brand awareness, and strategy persistence. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[Your Request] --> B{Agent Installed?} B -->|No| C[AI guesses tool order] B -->|Yes| D[Agent loads context] D --> E[Reads CLAUDE.md / BRAND.md / AGENTS.md] D --> F[Reads STRATEGY.md] D --> G[Reads MEMORY.md] E & F & G --> H[Picks the right skill] H --> I[Follows proven workflow] I --> J[Calls Adspirer MCP tools in order] C --> J J --> K[Results + Recommendations] ``` ### What the Agent Adds | Without Agent | With Agent | | - | - | | Raw tool access | Brand-aware tool usage | | AI guesses workflow | Proven step-by-step workflows | | No memory between sessions | Past decisions persist in MEMORY.md | | No strategy persistence | Directives saved in STRATEGY.md | | No safety enforcement | Skills enforce read-before-write, confirmation gates | See [Performance Marketing Agent](/docs/agent-skills/agent) for the full architecture. *** ## Safety Model Adspirer's safety model operates at multiple layers: | Layer | Protection | Who Enforces It | | - | - | - | | **OAuth scoping** | You authorize exactly what Adspirer can do | Ad platform (Google, Meta, etc.) | | **Tool types** | Read tools are safe; Write tools require confirmation | Adspirer MCP server | | **PAUSED creation** | All campaigns start paused | Adspirer `create_*` tools | | **Skill workflows** | Research → validate → confirm → create | SKILL.md files | | **Agent rules** | Read-before-write, budget guardrails, no auto-retry | Agent prompt + rules files | | **User confirmation** | AI asks before any spend-affecting action | AI client + skill | | **Post-creation verification** | Agent verifies ads, keywords, extensions exist | Agent prompt | No single layer is sufficient on its own. The safety model works because each layer reinforces the others. *** ## Data Flow Summary | What | Where It Lives | Who Can Access It | | - | - | - | | Your ad platform credentials | Google/Meta/Amazon/ChatGPT/LinkedIn/TikTok servers | Only the ad platform | | OAuth tokens | Adspirer servers (encrypted) | Adspirer (for API calls) | | Campaign performance data | Ad platform APIs (real-time) | Your AI client (via Adspirer) | | Brand context (CLAUDE.md) | Your local machine | Your AI client | | Strategy directives | Your local machine (STRATEGY.md) | Your AI client | | Memory | Your local machine (MEMORY.md) | Your AI client | Adspirer reads your campaign data in real-time and passes it to your AI client. It does not permanently store campaign data, ad copy, or targeting settings. ## Related Documentation * [How MCP Works](/docs/mcp) — Deep dive into the Model Context Protocol * [Security & Data Privacy](/docs/knowledge-base/security) — OAuth, encryption, and data handling * [Agent Skills Overview](/docs/agent-skills/overview) — Skills, workflows, and safety rules * [Performance Marketing Agent](/docs/agent-skills/agent) — Agent architecture * [Tool Catalog](/docs/agent-skills/tools) — All 400+ tools * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Google Analytics 4 Integration | Adspirer Source: https://www.adspirer.com/docs/integrations/google-analytics Connect Google Analytics 4 to Adspirer and let your AI assistant correlate paid ad spend with on-site behavior — sessions, conversions, traffic sources, landing-page performance. Connect **Google Analytics 4** to Adspirer and your AI assistant can correlate paid ad spend with on-site behavior — sessions, conversions, traffic sources, landing pages — alongside the campaign data it already pulls from Google Ads, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok. ## Prerequisites > [!NOTE] > > * A Google Analytics 4 property you have **Viewer** access to (or higher) > * Adspirer account on the **Plus, Pro, or Max** tier — GA4 is gated to paid plans > * Adspirer connected to a [supported AI client](/docs/ai-clients/chatgpt) ## Connecting Google Analytics 1. Open [adspirer.ai/connections](https://adspirer.ai/connections) 2. Scroll to the **Integrations** section and click **Connect** on the Google Analytics card 3. A Pipedream Connect popup opens — sign in to Google and approve read access to your GA4 properties 4. The popup closes and the card flips to **Connected** Verify in your AI client: ``` What can you do with my Google Analytics account? ``` The agent will discover what's available via the `google_analytics` tool and reply with the actions it can run. > [!NOTE] > > Adspirer uses [Pipedream Connect](https://pipedream.com/connect) to broker the OAuth grant. Your tokens stay in Pipedream and are scoped to your Adspirer user — Adspirer never sees the raw GA4 credentials. ## What You Can Do The GA4 integration is exposed through one router tool — **`google_analytics`** — that takes an `action` and a `tool_name`: | action | What it does | | - | - | | `list_tools` | Discover the GA4 actions available (the agent does this automatically before its first call) | | `execute` | Run a specific GA4 action with parameters | The Pipedream GA4 catalog includes (non-exhaustive): * Pull report data — sessions, users, page views, conversions * Break down by source, medium, campaign, landing page, device * Real-time reporting (last 30 minutes) * Custom dimension and metric reads * Property and account discovery The agent picks the right action based on what you ask. You don't need to memorize tool names. ## Which Property It Reports On One Google login usually reaches more than one GA4 property. If yours reaches exactly one, there is nothing to decide — the agent uses it and answers. If it reaches several and you haven't said which, the agent doesn't pick for you. It pulls the labelled list off your connection and asks: ``` You have 28 properties connected for Google Analytics on jane@agency.com. Tell me which one — a single property, a few, or all of them — then call again. ``` Answer with one property, with a few, or with **all**. "All" means every property on that connection, one report call each, so the agent says what that will cost you in tool calls and waits for a yes first. The question itself doesn't cost a tool call. You can also name the property up front and skip the question entirely: Report on one named GA4 property Pull GA4 sessions and conversions for the last 7 days for the acmestore.com property. > [!NOTE] > > If you have **more than one Google Analytics account connected**, the agent asks which account first, then which property inside it. Properties are always listed with the account they belong to, so a property is never shown without its login. ## Example Prompts ``` Compare last month's paid search conversions in Google Ads to landing-page conversions in GA4. ``` ``` Which landing pages have the highest conversion rate from my Meta campaigns this quarter? ``` ``` Pull GA4 traffic by source/medium for the last 7 days and tell me which non-paid channels are growing. ``` ``` What's the bounce rate on my Google Search campaign landing pages this week? ``` ## Tier Gating | Plan | Google Analytics | | - | :-: | | Free | — | | Plus | Included | | Pro | Included | | Max | Included | Free users see the integration card in the Connections panel with an **Upgrade** prompt that links directly to the Adspirer plan picker. ## Disconnecting Open [adspirer.ai/connections](https://adspirer.ai/connections), find the Google Analytics card, and click **Disconnect**. The grant is revoked in Pipedream and the agent loses access immediately. > [!NOTE] > > Idle integrations (>90 days with no tool calls) are pruned automatically to keep your integration list tidy. You can always reconnect. ## FAQ > **Does this count against my Adspirer tool-call quota?** > > Yes — each `google_analytics` call counts as one tool call against your monthly (or annual pooled) quota, same as a Google Ads or Meta call. > **Can the agent modify my GA4 property?** > > No. Adspirer's GA4 integration is read-only — the agent can pull report data and discover properties, but it cannot edit GA4 configuration, audiences, or events. > **Which GA4 properties does the agent see?** > > Whichever properties you have access to under the Google account you used for the OAuth grant. With more than one, the agent asks which to report on rather than choosing for you — see [Which Property It Reports On](#which-property-it-reports-on). > **What's the relationship between this and Google Ads?** > > They're separate connections. Connecting Google Ads gives the agent access to campaign data through the Google Ads API. Connecting Google Analytics gives it access to on-site behavior through the GA4 Data API. With both connected, the agent can stitch ad-side performance to site-side outcomes in a single answer. # Klaviyo Integration | Adspirer Source: https://www.adspirer.com/docs/integrations/klaviyo Connect Klaviyo to Adspirer and let your AI assistant pull campaigns, flows, segments, profiles, and metrics alongside paid media performance. Connect **Klaviyo** to Adspirer and your AI assistant can pull email and SMS campaign data, flows, segments, profiles, and lifecycle metrics — alongside the paid media data it already reads from Google Ads, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok. ## Prerequisites > [!NOTE] > > * A Klaviyo account you have at least **Analyst** access to (or higher) > * Adspirer account on the **Plus, Pro, or Max** tier — Klaviyo is gated to paid plans > * Adspirer connected to a [supported AI client](/docs/ai-clients/chatgpt) ## Connecting Klaviyo 1. Open [adspirer.ai/connections](https://adspirer.ai/connections) 2. Scroll to the **Integrations** section and click **Connect** on the Klaviyo card 3. A Pipedream Connect popup opens — sign in to Klaviyo and approve the requested scopes 4. The popup closes and the card flips to **Connected** Verify in your AI client: ``` What can you do with my Klaviyo account? ``` The agent will discover what's available via the `klaviyo` tool and reply with the actions it can run. > [!NOTE] > > Adspirer uses [Pipedream Connect](https://pipedream.com/connect) to broker the OAuth grant. Your tokens stay in Pipedream and are scoped to your Adspirer user — Adspirer never sees the raw Klaviyo credentials. ## What You Can Do The Klaviyo integration is exposed through one router tool — **`klaviyo`** — that takes an `action` and a `tool_name`: | action | What it does | | - | - | | `list_tools` | Discover the Klaviyo actions available (the agent does this automatically before its first call) | | `execute` | Run a specific Klaviyo action with parameters | The Pipedream Klaviyo catalog includes (non-exhaustive): * Read campaigns (email + SMS) — opens, clicks, revenue, recipients * Read flows and flow performance * Pull segments and their membership counts * Read individual profiles and lifecycle stage * Query metrics (events) and metric aggregates * List templates and audiences The agent picks the right action based on what you ask. You don't need to memorize tool names. ## Example Prompts ``` What's my best-performing Klaviyo email this month and which Meta ad audience overlaps most with its openers? ``` ``` Pull last quarter's Klaviyo flow revenue and compare it to my Google Ads conversion value for the same period. ``` ``` Which Klaviyo segments grew the fastest in the last 30 days? ``` ``` List the email campaigns I sent last month, sorted by revenue per recipient. ``` ## Tier Gating | Plan | Klaviyo | | - | :-: | | Free | — | | Plus | Included | | Pro | Included | | Max | Included | Free users see the integration card in the Connections panel with an **Upgrade** prompt that links directly to the Adspirer plan picker. ## Disconnecting Open [adspirer.ai/connections](https://adspirer.ai/connections), find the Klaviyo card, and click **Disconnect**. The grant is revoked in Pipedream and the agent loses access immediately. > [!NOTE] > > Idle integrations (>90 days with no tool calls) are pruned automatically to keep your integration list tidy. You can always reconnect. ## FAQ > **Does this count against my Adspirer tool-call quota?** > > Yes — each `klaviyo` call counts as one tool call against your monthly (or annual pooled) quota, same as a Google Ads or Meta call. > **Can the agent send Klaviyo campaigns?** > > v1 is focused on read access — pulling campaigns, flows, segments, and metrics for analysis alongside paid media. Send and edit actions are on the roadmap. If you have a specific send/edit workflow you want supported, [tell us](/docs/knowledge-base/support). > **What if I have multiple Klaviyo accounts?** > > Connect each one separately — Adspirer treats them as distinct integrations and the agent will ask which one to query when ambiguous. > **Why does this run through Pipedream?** > > Pipedream Connect handles OAuth, token refresh, and scope management for the long tail of SaaS APIs we'd otherwise have to maintain ourselves. The integration tool you see in chat is a thin Adspirer-side proxy to Pipedream's remote MCP — your tokens stay there, scoped to your Adspirer user. # AI Advertising Agent for Google, Meta, Amazon & TikTok Ads Source: https://www.adspirer.com/docs/introduction Adspirer is an AI advertising agent with 400+ MCP tools for Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads, plus Google Analytics and Klaviyo integrations. Connect from ChatGPT, Claude, Cursor, Grok Bot, and more. Adspirer is an MCP (Model Context Protocol — an open standard for connecting AI assistants to external tools) server that connects AI assistants to advertising platforms. Ask ChatGPT, Claude, or any MCP-compatible client to manage your Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads campaigns — no dashboards, no learning curve. > **[Get started in 5 minutes](/docs/quickstart)** > > Sign up, connect your AI client, and start managing ads with natural language. ## Connect Your AI Assistant Choose how you want to manage ads. Chat apps for conversational use, developer tools for terminal workflows. > [!NOTE] > > **Claude, ChatGPT, Cursor, and Grok Bot:** Adspirer is an official, reviewed listing in each app's own directory. It's an Anthropic-verified connector in Claude, an OpenAI-reviewed plugin in ChatGPT, and Verified by Cursor in Cursor and Grok Bot. Search for **Adspirer** and add it. Don't set up a custom connector in Claude, Cursor, or Grok Bot. [All listings and links →](/docs/add-to-your-agent#instructions-for-ai-agents) > **[ChatGPT](/docs/ai-clients/chatgpt)** > > Official plugin in ChatGPT's Plugins directory, for Plus/Pro. > **[Claude](/docs/ai-clients/claude)** > > Anthropic-verified connector for Claude (Pro/Max/Team/Enterprise). Search, connect, done. > **[Claude Cowork](/docs/ai-clients/claude-cowork)** > > Brand-aware workspace mode in the Claude desktop app — the Adspirer plugin from Anthropic's directory. > **[Claude Code](/docs/ai-clients/claude-code)** > > Anthropic's separate terminal/CLI developer tool. One command to connect. > **[Gemini CLI](/docs/ai-clients/gemini-cli)** > > Google's AI CLI with one-command install. > **[Cursor](/docs/ai-clients/cursor)** > > Verified by Cursor. One-click plugin from the Cursor Marketplace. > **[Grok Bot](/docs/ai-clients/grok)** > > Official Adspirer for Grok Bot plugin, running in the cloud with scheduled reports. > **[Codex Terminal](/docs/ai-clients/codex)** > > Autonomous agent setup in the terminal. > **[Codex Desktop](/docs/ai-clients/codex-desktop)** > > Codex inside the ChatGPT desktop app — three messages, no terminal. > **[OpenClaw](/docs/ai-clients/openclaw)** > > Plugin with zero configuration. > **[Windsurf](/docs/ai-clients/windsurf)** > > Codeium's AI-powered editor. > **[Perplexity](/docs/ai-clients/perplexity)** > > Search-powered ad management via Computer. ## Ad Platforms Each platform integration comes with dedicated tools for campaign creation, performance analysis, and optimization. > **[Google Ads](/docs/ad-platforms/google-ads)** > > 156 tools — Search, PMax, Shopping, App, Display, YouTube, Demand Gen, keyword research, budget optimization. > **[Meta Ads](/docs/ad-platforms/meta-ads)** > > 60 tools — Facebook & Instagram campaigns, Advantage+ Catalog (dynamic product ads), creative testing, lead gen. > **[Amazon Ads](/docs/ad-platforms/amazon-ads)** > > 61 tools — Sponsored Products, Brands & Display, ASIN targeting, ACOS/ROAS analytics. > **[ChatGPT Ads](/docs/ad-platforms/chatgpt-ads)** > > 50 tools — pay-per-click chat-card ads inside ChatGPT responses, created paused. > **[LinkedIn Ads](/docs/ad-platforms/linkedin-ads)** > > 55 tools — B2B targeting, image/video/text/carousel, campaign groups, audience forecasting. > **[TikTok Ads](/docs/ad-platforms/tiktok-ads)** > > 37 tools — In-feed video, Spark Ads, Carousel, full campaign analytics. ## Integrations Stitch paid media to the rest of your marketing stack. Available on **Plus, Pro, and Max** plans. > **[Google Analytics 4](/docs/integrations/google-analytics)** > > Correlate ad spend with on-site behavior — sessions, conversions, traffic sources, landing-page performance. > **[Klaviyo](/docs/integrations/klaviyo)** > > Pull email + SMS campaigns, flows, segments, and revenue alongside paid media for full-funnel analysis. ## Beyond one-off commands Adspirer isn't just a tool surface — it runs work for you and shares results with your team. > **[Autonomous Ad Ops Agents](/docs/agent-skills/ad-ops-agents)** > > Give an agent a plain-English goal and a cadence. It analyzes your accounts and **proposes every change to an approval queue** — nothing spends or changes without your OK. Works across platforms. > **[Shareable Dashboards](/docs/knowledge-base/capabilities)** > > Generate a performance dashboard from chat and share a **live, no-login link** — white-label it with your own logo for clients. > **[Community Plugins](/docs/agent-skills/community-plugins)** > > Extend Adspirer with open-source, community-contributed analysis tools — read-only and sandboxed. > **[Available in 100+ languages](/docs/knowledge-base/localization)** > > The Adspirer dashboard and onboarding are localized into **116 languages** with full right-to-left support. ## See It in Action [Adspirer: Manage Ad Campaigns with AI](https://www.youtube.com/embed/dYU-6sudjZM) Adspirer: Manage Ad Campaigns with AI ## Go Deeper > **[Agent Skills](/docs/agent-skills/overview)** > > Teach your AI assistant proven ad management workflows. > **[Tool Catalog](/docs/agent-skills/tools)** > > Complete reference of all 400+ tools by platform. > **[Core Workflows](/docs/agent-skills/workflows)** > > Step-by-step sequences for campaign creation and optimization. > **[Guides](/docs/guides/chatgpt-google-ads-keywords)** > > In-depth tutorials for Google Ads, Meta Ads, TikTok, and more. > **[Diagnostic & Helper Tools](/docs/agent-skills/diagnostic-helper-tools)** > > Free, quota-free tools to get started, pre-flight a launch, and diagnose errors. ## Prefer HTTP? Use the REST API Every Adspirer tool is also available over plain HTTP — same 400+ endpoints, same auth, same quota. Built for n8n, Zapier, Make, cron jobs, and any backend that can't speak MCP. > **[REST API Reference](/docs/api-reference/introduction)** > > 400+ endpoints, interactive try-it playground, copy-paste examples for curl, Python, Node, and n8n. # What Adspirer Can & Can't Do Source: https://www.adspirer.com/docs/knowledge-base/capabilities Adspirer capabilities and limitations: what the AI advertising agent handles (campaigns, analytics, optimization) and what it doesn't (creative, billing). A clear breakdown of what Adspirer does and what's outside its scope. ## What Adspirer Does ### Campaign Management * Create Search, PMax, [Shopping](/docs/ad-platforms/google-ads), App/UAC, [Display](/docs/ad-platforms/google-display-ads), [YouTube](/docs/ad-platforms/youtube-ads), Demand Gen, Image, Video, Carousel, [Meta Advantage+ Catalog (dynamic product ads)](/docs/ad-platforms/meta-ads), Sponsored Content (image/video/text/carousel), [Amazon Sponsored Products / Brands / Display](/docs/ad-platforms/amazon-ads), and [pay-per-click ChatGPT Ads](/docs/ad-platforms/chatgpt-ads) campaigns * Run **Shopping** campaigns from a Google Merchant Center feed with a full product-partition tree * Manage **Meta catalog / dynamic product ads** — prospecting and retargeting from your product catalog * Pause, resume, and update live campaigns * Set and adjust budgets, bids, targeting, frequency caps, and schedules * All campaigns created **PAUSED** for your review * **Microsoft Advertising (Bing Ads)** — read, create, and edit: campaigns of every type (Search, Shopping, Audience, Performance Max, Hotel, App), ad groups, ads, keywords, shared budgets, portfolio bid strategies, extensions, Performance Max asset groups, audiences, and deep targeting down to a device or dayparting bid adjustment. Performance reporting is not live yet * **[ChatGPT Ads](/docs/ad-platforms/chatgpt-ads) custom audiences** — build an audience from your own customer list (emails, phone numbers, pre-hashed identifiers, or Google Advertising IDs), include or exclude it in campaign targeting, and bid from 0.1× to 10× for it at ad-group level. Including an audience or bidding on it needs roughly 25,000 matched users; excluding one has no minimum * **No daily cap on Google Ads operations** — Adspirer holds agency-level Standard Access for the Google Ads API, so bulk builds, large restructures, and account-wide optimization run at full speed ### Research & Analysis * Keyword research with real CPC data from Google Keyword Planner * Audience targeting research (interests, demographics, job titles) * Performance analysis (spend, conversions, CPA (Cost Per Acquisition), ROAS (Return on Ad Spend), CTR (Click-Through Rate)) * Wasted spend detection (keywords with clicks but zero conversions) * Creative fatigue detection (declining CTR over time) * Performance anomaly diagnosis (sudden CPA spikes) * Conversion reporting that reconciles with each platform's own dashboard — on Meta, every conversion action is broken out with the purchase event that matches Ads Manager highlighted * **Competitor ad research** — pull a competitor's live ads from public ad-transparency sources (creatives, headlines, offers, calls to action, formats, and how long each has been running), read with vision analysis and placed beside your own connected accounts and the competitor brand terms you already pay for. Covers their **Google, Facebook/Instagram, TikTok, and LinkedIn** ads; ask for the platforms you care about. Video ads are included — their poster frame is read the same way, and the ad opens on the platform it runs on. You supply the competitor domains; nothing is auto-discovered. It reads public ad libraries, so it works whichever platform you advertise on — a Meta-only advertiser can run it without a Google Ads account, and only the side-by-side with your own ads needs a connected account on the platform being compared. It reports what competitors **run**, never how it performs — no source publishes competitor spend, ROAS, or conversions, so Adspirer doesn't estimate them. (Pro/Max) ### Optimization * Budget reallocation based on ROAS/CPA performance * Placement optimization (Meta: Feed vs Stories vs Reels) * Audience segment analysis (which demographics convert best) * Cross-platform performance comparison ### Automation & Proactive Monitoring * **[Autonomous Ad Ops agents](/docs/agent-skills/ad-ops-agents)** — give an agent a plain-English goal and a cadence; it monitors your accounts and **proposes every change to an approval queue**. Nothing spends or changes without your sign-off. One agent can act across Google, Meta, TikTok, LinkedIn, and Amazon, measure its own impact, and learn from your rejections. **Community playbooks** let you share and fork agent strategies. (Plus/Pro/Max) * **Watch Agent** — background AI agent that scans all connected ad accounts every 15 minutes, finds issues, and emails you a ready-to-paste action prompt. Trigger on demand with `run_watch_now`. * **Monitors & Alerts** — set metric thresholds (CPA, ROAS, CTR, spend, etc.) via MCP tools or the [Monitors web UI](https://adspirer.ai/monitors). Alerts fire when thresholds are crossed and can be scoped to specific platforms or campaigns. * Scheduled daily/weekly performance briefs with PDF attachment * Cross-platform ad-hoc report generation ### Get Started, Pre-flight & Diagnostics * **[Diagnostic & Helper tools](/docs/agent-skills/diagnostic-helper-tools)** — a group of free, read-only tools that suggest your best next step, dry-run a campaign draft against the platform's rules before you create it, translate cryptic platform errors into plain-language fixes, and confirm a campaign is actually serving (a real live check across all six platforms). Quota-free on **every plan, including Free**. * **Find what actually broke** — `why_did_this_fail` lists your recent failed actions with the platform's real error behind each, so you fix the right thing instead of reconnecting at random. * **Interactive cards & dashboards** — in ChatGPT and Claude, results render as branded, interactive UI instead of plain text: setup checklists, usage meters, and an account switcher, plus a tabbed performance dashboard (KPI tiles, charts, and 7 / 14 / 30 / 60 / 90-day or custom date-range switching) and a graded conversion-audit scorecard. They render on desktop, web, and mobile, and fall back to clean text where widgets aren't supported. ### Shareable Dashboards * Generate a performance dashboard from chat or the `/dashboards` UI and share it as a **live, no-login link** — recipients always see fresh data. Links are revocable and expire per plan tier. * **White-label** dashboards with your own logo, custom title/footer, and an option to hide Adspirer branding — ideal for client reporting. * Dashboards adapt to your data with \~20 analysis blocks (Pareto, anomaly detection, efficiency frontier, funnel, treemap, waterfall) and platform-specific signatures across Google, Meta, TikTok, and LinkedIn. ### Extend & Localize * **[Community Plugins](/docs/agent-skills/community-plugins)** — open-source, read-only community analysis tools that show up alongside the built-in ones (sandboxed, credential-free). * **[Available in 116 languages](/docs/knowledge-base/localization)** — the dashboard and onboarding are localized with full right-to-left support, and you can instruct the AI assistant in your own language. ### Account-Specific Agent Training (one-time add-on) * **[Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook)** — Adspirer reads one of your ad accounts and generates a custom agent skill, a written account dossier, a prompt book against your real campaigns, and paste-ready agent instructions. You download the files and install them in Claude, ChatGPT, Claude Code, Cowork, Cursor, or Codex. * **\$39 one-time, per ad account** — not a subscription, nothing recurs. One included free on annual plans. Rebuilding against fresh account data is free and unlimited. ### Marketing Stack Integrations (Plus and above) * **[Google Analytics 4](/docs/integrations/google-analytics)** — correlate paid ad spend with on-site behavior (sessions, conversions, traffic sources, landing-page performance). * **[Klaviyo](/docs/integrations/klaviyo)** — pull email + SMS campaigns, flows, segments, profiles, and revenue alongside paid media for full-funnel analysis. * **Google Search Console** — read organic-search performance for your verified sites (clicks, impressions, CTR, average position, by query or page) and compare it against what you pay for in Google Ads. Also submits URLs to Google for re-crawling. * **Google Tag Manager** — read the tags and variables in your containers to answer "is my Meta pixel installed?" or "why isn't this conversion firing?", and create or edit a tag or variable when you need to. Writes hit a live container, so the agent confirms the exact change first. Each of these can hold **more than one connected account** — a second GA4 login, a second Search Console user, a client's container alongside your own — up to your plan's account limit. When you have more than one, tell the agent which account to use and it will list them if you don't. The same holds one level down. A single Google login usually reaches several GA4 properties, several verified sites, or several Tag Manager containers, and the agent won't choose between them for you: ask for a report without naming a property and it comes back with the labelled list and asks which. Reads run straight through when there's only one to pick; writes name their target back to you before they run, every time. ## What Adspirer Does NOT Do ### Creative Generation Adspirer does **not** generate images, videos, or design assets. It generates **ad copy** (headlines and descriptions) but not visual creatives. **Workaround:** Use AI creative tools (Midjourney, DALL-E, Runway, CapCut), then provide the URL to Adspirer for campaign creation. ### Conversion Tracking Setup Adspirer cannot put code on your website. It can't add a pixel to your pages or install the Google Tag Manager container snippet — that part is yours or your developer's. Once the container is on your site, [Google Tag Manager](#marketing-stack-integrations-plus-and-above) is connectable: Adspirer reads the tags and variables in it, which is how you answer "is my Meta pixel actually installed?" and "why isn't this conversion firing?", and it can create or edit a tag or variable when you ask. **Workaround:** Install the container or pixel on your site once, then let Adspirer read and adjust what fires inside it. ### Billing & Payment Adspirer cannot access or modify your ad platform billing information (credit cards, invoices, payment methods). ### Landing Page Creation Adspirer manages ads, not websites. It cannot create or modify landing pages. ### Organic Social Media Adspirer manages **paid** advertising only. It cannot post organic content, manage social media accounts, or boost existing organic posts. ### Platform-Specific Limitations | Platform | Not Yet Supported | | - | - | | **Google Ads** | Discovery (legacy) campaigns; hotel/local campaigns. Search, PMax, Shopping, App/UAC, Display, YouTube, and Demand Gen are supported | | **Meta Ads** | Instagram-only campaigns (Meta treats FB/IG as placements), Messenger ads. Image, video, carousel, and Advantage+ Catalog (dynamic product ads) are supported | | **Amazon Ads** | Amazon DSP (programmatic display); Sponsored Products / Brands / Display are fully supported | | **ChatGPT Ads** | Multi-card / non-`chat_card` creatives; ads pass OpenAI review (some categories disallowed) | | **LinkedIn Ads** | Matched Audiences (retargeting), InMail campaigns. Image, video, text, and carousel campaigns are supported | | **TikTok Ads** | TopView, Branded Effects | | **Microsoft Advertising** | Performance reporting — spend, clicks, and conversions aren't readable yet. Reading, creating, and editing campaigns, ad groups, ads, keywords, budgets, bid strategies, extensions, Performance Max asset groups, and targeting are supported | These limitations reflect the current API integrations. New capabilities are added regularly — see the [Changelog](/docs/changelog) for updates. Plus, Pro, and Max plans include [Google Analytics 4](/docs/integrations/google-analytics) and [Klaviyo](/docs/integrations/klaviyo). Need a broader custom integration (Slack, another CRM, a warehouse)? [Talk to us](https://www.adspirer.com/book-demo). ## FAQ > **Can Adspirer spend money without my approval?** > > No. All campaigns are created PAUSED. Budget changes require explicit confirmation. Even [autonomous Ad Ops agents](/docs/agent-skills/ad-ops-agents) follow this rule — they propose every change to an approval queue and nothing executes until you approve it. > **Does Adspirer work with Google Analytics?** > > Yes — on **Plus, Pro, and Max** plans you can connect a Google Analytics 4 property in the [Connections](https://adspirer.ai/connections) panel and the agent can pull sessions, conversions, traffic sources, and landing-page performance alongside the ad-platform data. See the [Google Analytics integration page](/docs/integrations/google-analytics) for what's available and example prompts. > **Does Adspirer work with Klaviyo?** > > Yes — on **Plus, Pro, and Max** plans you can connect a Klaviyo account in the [Connections](https://adspirer.ai/connections) panel and the agent can pull campaigns, flows, segments, profiles, and revenue alongside paid media. See the [Klaviyo integration page](/docs/integrations/klaviyo) for what's available and example prompts. > **Can Adspirer manage existing campaigns I created manually?** > > Yes. Adspirer can read, analyze, pause, resume, and update campaigns regardless of how they were created. You don't need to create campaigns through Adspirer to manage them with it. # Computer Use Agents & Adspirer Source: https://www.adspirer.com/docs/knowledge-base/computer-use-agents What are computer use agents? How Perplexity Computer, Manus, Codex, and other autonomous AI agents connect to Adspirer for hands-free ad campaign management. Computer use agents are the next evolution of AI assistants — from tools you prompt to agents that **execute**. Instead of asking an AI to help you write an ad, you tell it to research your market, create a campaign, and monitor performance. The agent handles the rest. Adspirer connects to multiple computer use agents, giving them direct access to 400+ advertising tools across Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads. ## What Are Computer Use Agents? Traditional AI assistants answer questions. Computer use agents **take action**. They can: * Break complex goals into subtasks and execute them sequentially * Call external tools (like Adspirer's MCP server) to interact with real platforms * Run for extended periods — minutes, hours, or on a schedule * Chain web research, data analysis, and platform actions in a single workflow * Operate autonomously with minimal human intervention The key difference: you describe the **outcome** you want, not the steps to get there. ## How They Work with Adspirer Computer use agents connect to Adspirer via MCP (Model Context Protocol — an open standard for connecting AI assistants to external tools) — the same protocol used by all Adspirer-compatible AI clients. The agent discovers Adspirer's 400+ tools and uses them as part of its autonomous workflows. ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[You] -->|"Launch a Google Ads campaign for my SaaS"| B[Computer Use Agent] B --> C[Research competitors on the web] B --> D[Research keywords via Adspirer] B --> E[Create campaign via Adspirer] B --> F[Generate performance report] C & D & E & F --> G[Deliver results to you] ``` The agent decides **which tools to call, in what order, and how to combine results**. With Adspirer connected, it has direct access to your ad accounts — no dashboards, no manual steps. ## Supported Computer Use Agents Adspirer works with multiple autonomous agents. Each connects via MCP and gets access to the same 400+ tools. | Agent | Auth | Autonomous | Web Research | Best For | Setup Guide | | - | - | :-: | :-: | - | :-: | | **Perplexity Computer** | OAuth | Yes | Yes (native) | Research + campaign creation | [Guide](/docs/ai-clients/perplexity) | | **Manus** | API Key | Yes | Yes | Dashboards, scheduled briefs, deep research | [Guide](/docs/ai-clients/manus) | | **Codex** | OAuth | Yes | No | Scheduled monitoring, daily checks | [Guide](/docs/ai-clients/codex) | | **OpenClaw** | OAuth / API Key | Semi | No | Pre-configured ad agent, CLI workflows | [Guide](/docs/ai-clients/openclaw) | ### Perplexity Computer Perplexity Computer orchestrates 19+ AI models to execute complex tasks. Its unique advantage is **native web search** — it can research competitors, market trends, and industry benchmarks in real-time, then immediately act on that research using Adspirer tools. * **Plan required:** Perplexity Max ($200/mo) for Computer; Pro ($20/mo) for connectors only * **How it connects:** Custom connector in Perplexity Computer → Connectors → OAuth * **Skills:** Upload `SKILL.md` via Computer → Skills → + Create skill. Perplexity applies skills automatically when relevant. * **Unique capability:** Combines real-time search with ad platform actions in a single workflow **Example workflow:** *"Research the top 5 competitors for project management SaaS, analyze their Google Ads strategy, then create a campaign targeting keywords they're missing. Budget \$50/day."* — Perplexity Computer searches the web, pulls keyword data via Adspirer, creates the campaign, and delivers a summary. ### Manus Manus is a general-purpose autonomous agent that can browse the web, write code, and generate interactive dashboards. It connects to Adspirer via API key authentication. * **Plan required:** Manus account (any tier) * **How it connects:** Custom MCP server with API key in Authorization header * **Unique capability:** Interactive dashboard generation, scheduled email briefs, 24/7 monitoring **Example workflow:** *"Set up a daily performance brief across all my ad platforms and email it to me every morning at 9 AM."* — Manus configures monitoring, fetches data daily, and delivers formatted reports. ### Codex OpenAI's Codex operates as a background agent that can run tasks autonomously, including on a schedule. * **Plan required:** Codex subscription * **How it connects:** One-command installer + OAuth * **Unique capability:** Scheduled autonomous tasks (e.g., daily performance checks at 8 AM) **Example workflow:** *"Every Monday at 9 AM, pull my Google Ads performance for the past week and flag any keywords with spend > \$50 and zero conversions."* ### OpenClaw OpenClaw is a CLI-based agent with Adspirer's skill file pre-bundled. It runs locally on your machine with direct terminal access. * **Plan required:** OpenClaw (open source) * **How it connects:** Plugin install with bundled 14KB skill file * **Unique capability:** Pre-configured advertising agent with safety rules built in ## Computer Use Agents vs Chat Apps | | Chat Apps (ChatGPT, Claude, Perplexity Search) | Computer Use Agents (Perplexity Computer, Manus, Codex) | | - | - | - | | **Interaction** | You ask, AI responds | You define a goal, agent executes | | **Duration** | Single conversation | Can run for hours or on a schedule | | **Multi-step** | You guide each step | Agent plans and executes autonomously | | **Web research** | Limited or manual | Built-in (Perplexity, Manus) | | **Dashboards** | Text/table output | Interactive charts and reports (Manus) | | **Monitoring** | Manual checks | Automated alerts and scheduled briefs | | **Best for** | Quick queries, ad-hoc tasks | Complex workflows, ongoing management | > [!TIP] > > You don't have to choose one or the other. Many users use **chat apps for quick queries** (e.g., "How's my Google Ads CTR this week?") and **computer use agents for complex workflows** (e.g., "Audit all platforms, find wasted spend, and create an optimization plan"). ## What Computer Use Agents Can Do with Adspirer | Workflow | What the Agent Does | Which Agents | | - | - | :-: | | **Full campaign launch** | Research market → find keywords → validate assets → create campaign (PAUSED) | All | | **Cross-platform audit** | Pull performance from all platforms → identify waste → recommend optimizations | All | | **Competitor research + action** | Search the web for competitor ads → analyze strategy → create campaigns to compete | Perplexity, Manus | | **Daily performance brief** | Fetch metrics → format summary → deliver via email or dashboard | Manus, Codex | | **Automated monitoring** | Watch for CPA spikes, budget overruns, or ROAS drops → alert you | Manus, Codex | | **Interactive dashboard** | Generate charts, KPI cards, and data tables from ad performance data | Manus, Perplexity | | **Budget optimization** | Analyze ROAS across campaigns → recommend reallocation → execute after approval | All | ## Safety with Autonomous Agents Autonomous agents acting on your ad accounts sounds risky. Adspirer has multiple safety layers: 1. **All campaigns created PAUSED** — No live spend without your review 2. **OAuth scoping** — Agents only get the permissions you authorize 3. **Read-before-write** — Skills enforce research and validation before any creation 4. **Confirmation gates** — Spend-affecting actions require your approval 5. **No auto-retry** — Failed actions stop and report, never retry automatically 6. **Sandboxed execution** — Agents like Perplexity Computer run in secure sandboxes, isolated from your local machine See [Security & Data Privacy](/docs/knowledge-base/security) for the full security model. ## Getting Started > **[Perplexity Setup](/docs/ai-clients/perplexity)** > > Connect via OAuth in Perplexity Computer. Search + ads in one agent. > **[Manus Setup](/docs/ai-clients/manus)** > > Connect via API key. Dashboards, briefs, and monitoring. > **[Codex Setup](/docs/ai-clients/codex)** > > One-command install. Scheduled autonomous tasks. > **[OpenClaw Setup](/docs/ai-clients/openclaw)** > > Pre-configured ad agent with bundled skills. ## FAQ > **Are computer use agents safe for managing ad spend?** > > Yes. Adspirer enforces multiple safety layers regardless of which agent connects. All campaigns start PAUSED, spend-affecting actions require confirmation, and OAuth scoping limits what the agent can access. The agent never has direct access to your ad platform credentials. > **Which computer use agent is best for advertising?** > > It depends on your needs. **Perplexity Computer** is best for research-heavy workflows (competitor analysis + campaign creation). **Manus** is best for ongoing management (dashboards, scheduled briefs, monitoring). **Codex** is best for scheduled automation (daily checks, weekly reports). You can use multiple agents with the same Adspirer account. > **Do tool calls from computer use agents count against my Adspirer limit?** > > Yes. All tool calls count against your monthly limit regardless of which agent makes them. A Perplexity Computer workflow that calls 10 Adspirer tools uses 10 calls from your plan. > **Can a computer use agent accidentally spend my ad budget?** > > No. Every campaign Adspirer creates starts in PAUSED status — you must manually enable it. The agent cannot unpause campaigns or increase budgets on existing campaigns. See [Capabilities & Limitations](/docs/knowledge-base/capabilities) for the full list. # Adspirer FAQ: Pricing, Security & Supported Platforms Source: https://www.adspirer.com/docs/knowledge-base/faq Common questions about Adspirer — what it is, how it works, pricing, security, supported ad platforms, and troubleshooting for new users. ## What Is Adspirer? > **What is Adspirer?** > > Adspirer is an MCP (Model Context Protocol — an open standard for connecting AI assistants to external tools) server that connects AI assistants to advertising platforms. It gives your AI (Claude, ChatGPT, Perplexity, Cursor, Codex) access to 400+ tools for managing Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and TikTok Ads through natural language. > > Instead of logging into 6 different ad platforms, you describe what you want — "find wasted spend across all platforms" or "create a Google Search campaign for my SaaS" — and your AI handles it. > **Is Adspirer an AI agent or a tool?** > > Both. At the core, Adspirer is an **MCP server** that provides 400+ advertising tools. On top of that, it ships a **performance marketing agent** — a specialized AI agent with brand awareness, strategy persistence, and proven workflows. > > * **Tools only:** Connect the MCP server and use raw tools. Good for quick queries. > * **Agent + tools:** Install the full plugin (agent, skills, slash commands). The agent follows proven workflows, remembers your brand, and persists strategic decisions. > > See [Agent Skills Overview](/docs/agent-skills/overview) for details. > **How is Adspirer different from other ad management tools?** > > Traditional tools have dashboards you click through. Adspirer is different in two ways: > > 1. **Natural language interface.** You describe what you want. No dashboards, no button hunting, no learning a new UI. > 2. **AI-native workflows.** The agent researches your competitors, pulls real keyword data, writes brand-voice ad copy, and creates campaigns — all in one conversation. > > It's not a dashboard replacement. It's an AI-powered advertising manager that connects directly to your ad platforms. > **Which AI clients work with Adspirer?** > > Any MCP-compatible AI client. Currently supported with setup guides: > > | Client | Agent Support | Setup Guide | > | - | :-: | :-: | > | [Claude Code](/docs/ai-clients/claude-code) | Full (subagent + skills) | [Guide](/docs/ai-clients/claude-code) | > | [Claude](/docs/ai-clients/claude) | Full (Anthropic-verified connector; plugin adds 15 skills + agent) | [Guide](/docs/ai-clients/claude) | > | [Cursor](/docs/ai-clients/cursor) | Full (Verified by Cursor plugin: subagent + 14 skills + rules) | [Guide](/docs/ai-clients/cursor) | > | [Grok Bot](/docs/ai-clients/grok) | Full (official plugin + cloud routines) | [Guide](/docs/ai-clients/grok) | > | [Codex Terminal](/docs/ai-clients/codex) | Full (agent config + skills) | [Guide](/docs/ai-clients/codex) | > | [Codex Desktop](/docs/ai-clients/codex-desktop) | Full (plugin + skills) | [Guide](/docs/ai-clients/codex-desktop) | > | [ChatGPT](/docs/ai-clients/chatgpt) | Tools (official plugin, reviewed by OpenAI) | [Guide](/docs/ai-clients/chatgpt) | > | [Windsurf](/docs/ai-clients/windsurf) | Coming soon | [Guide](/docs/ai-clients/windsurf) | > | [OpenClaw](/docs/ai-clients/openclaw) | Bundled skill | [Guide](/docs/ai-clients/openclaw) | > | [Perplexity](/docs/ai-clients/perplexity) | Skill upload | [Guide](/docs/ai-clients/perplexity) | > | [Manus](/docs/ai-clients/manus) | Skills (GitHub import) | [Guide](/docs/ai-clients/manus) | > **Is Adspirer a verified connector? Do I need a custom connector?** > > Adspirer is an official, reviewed listing in Claude, ChatGPT, Cursor, and Grok Bot. In Claude, Cursor, and Grok Bot, search for **Adspirer** in the app's own directory and add it. There's no server URL, config file, or API key. In ChatGPT, the plugin is having issues right now, so add Adspirer as a custom MCP server instead. The apps call it a *connector*, *plugin*, *app*, or *marketplace listing*, but it's the same install. > > | App | Official listing | Reviewed by | How to add | > | - | - | - | - | > | **Claude** | [Adspirer Ads & Performance Marketing Agent](https://claude.ai/customize/connectors/id/adspirer-ads-performance-marketing-agent) | Anthropic (verified) | **Customize → Connectors** → search "Adspirer" → **Connect to Claude** | > | **Claude** (Cowork, or chat with skills) | [Adspirer plugin](https://claude.ai/customize/plugins/id/7bb5ea42-d7d7-4256-89d7-5798f5dc9c83%40anthropic-plugin-directory) | Anthropic Directory | **Customize → Plugins** → search "Adspirer" → **Add** | > | **ChatGPT** | Custom MCP server (the [plugin](https://chatgpt.com/plugins/plugin_asdk_app_69461dc91ee48191ae4a14eb9bde1c21) is having issues) | — | **Plugins → Add → Add custom MCP server** → `https://mcp.adspirer.com/mcp`, OAuth ([steps](/docs/ai-clients/chatgpt)) | > | **Cursor** | [Adspirer](https://cursor.com/marketplace/adspirer) | Cursor (Verified by Cursor) | **Customize** → search "adspirer" → **Install**, or `/add-plugin adspirer` | > | **Grok Bot** | [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) | Cursor (same listing) | **Marketplace** → search "adspirer", or **Add to Grok Bot** on the listing | > > **Don't set up a custom connector in Claude, Cursor, or Grok Bot.** The listing already includes the connector, the skills, and the agent. A manual server URL only applies in two cases: ChatGPT users who need the newest tools before OpenAI publishes the plugin update ([ChatGPT setup](/docs/ai-clients/chatgpt)), and Codex or other MCP clients that have no listing. ## How It Works > **How does Adspirer connect to my ad accounts?** > > Through **OAuth 2.1 with PKCE** — the same standard used by banking apps. When you connect a platform: > > 1. Your browser opens to Google/Meta/LinkedIn/TikTok's login page > 2. You sign in with your existing credentials (Adspirer never sees your password) > 3. You authorize specific permissions (read campaigns, create ads, etc.) > 4. Adspirer receives a scoped access token — not your password > > You can revoke access anytime from your ad platform's security settings. See [Security](/docs/knowledge-base/security). > **Can Adspirer spend my money without permission?** > > No. Multiple safety layers prevent unauthorized spending: > > * All campaigns are created in **PAUSED** status — you review before anything goes live > * The agent **always asks** before any action that affects spend > * Skills enforce a **read-before-write** pattern — research and validation happen before creation > * Adspirer **never retries** a failed campaign creation automatically > * Budget guardrails from your brand context file are checked before spend-affecting actions > **What is MCP?** > > MCP (Model Context Protocol) (Model Context Protocol) is an open standard created by Anthropic that allows AI assistants to connect to external tools and services. Think of it as a universal adapter between AI and the tools it needs. > > Adspirer implements MCP so that any AI client — Claude, ChatGPT, Perplexity, Cursor, Codex — can access the same 400+ advertising tools through one connection. See [How MCP Works](/docs/mcp). > **What are skills and why do they matter?** > > Skills are instruction files (`SKILL.md`) that teach AI assistants the *right* workflow for advertising tasks. Without skills, the AI guesses which tools to call. With skills: > > * It follows proven workflows (research → validate → create → verify) > * Safety rules are enforced automatically > * Campaign creation works on the first try instead of failing mid-workflow > > Skills are optional but highly recommended. See [Agent Skills Overview](/docs/agent-skills/overview). > **Not sure where to start — or why something failed?** > > Adspirer ships a group of free, read-only **[Diagnostic & Helper tools](/docs/agent-skills/diagnostic-helper-tools)** for exactly these moments. Ask your assistant things like: > > * *"What should I do first?"* → suggests your best next step from your real connected accounts > * *"Is my account ready to launch?"* → checks billing, connection, and (for Meta) pixel/Page before you create anything > * *"Why did that fail?"* → turns a cryptic platform error into a plain-language fix > * *"Diagnose my setup"* → tells apart an AI-client connection problem from an ad-platform sign-in problem > * *"What changed since last week?"* → spend/conversion movement plus the top opportunities to act on > > They're **quota-free** (never count against your tool-call limit) and work on every plan, including Free. In ChatGPT and Claude, their results render as interactive cards. > **Can I use Adspirer on a remote server or in Docker?** > > Yes. Generate a **Personal Access Token** (API key) from [adspirer.ai/keys](https://adspirer.ai/keys), then authenticate using either: > > * **CLI flag:** `openclaw adspirer login --token sk_live_your_key` > * **Environment variable:** `export ADSPIRER_API_KEY=sk_live_your_key` > > You still need to connect your ad platforms via OAuth from a browser at [adspirer.ai/connections](https://adspirer.ai/connections). The API key on your remote server will then access those connected accounts. > > See the [OpenClaw Remote Server Setup](/docs/ai-clients/openclaw#remote-server-setup) guide. > **Do I need to install anything?** > > It depends on your AI client: > > * **Claude (web/desktop):** No URL. Adspirer is an Anthropic-verified connector. Search for it in **Customize → Connectors** and click **Connect to Claude**. [Guide →](/docs/ai-clients/claude) > * **ChatGPT:** Add Adspirer as a custom MCP server: **Plugins → Add → Add custom MCP server**, paste `https://mcp.adspirer.com/mcp`, OAuth. Works on every plan, including Free. [Guide →](/docs/ai-clients/chatgpt) > * **Claude Code:** One command (`/plugin install adspirer-ads-agent@claude-community`) — available on Anthropic's community plugin marketplace (enabled by default). [Guide →](/docs/ai-clients/claude-code) > * **Cursor:** Install the Verified by Cursor plugin from **Customize**, or run `/add-plugin adspirer` in chat. [Guide →](/docs/ai-clients/cursor) > * **Grok Bot:** Click **Add to Grok Bot** on the [official listing](https://x.ai/bot/plugin/66672239), or add it from **Marketplace** at the bottom of the sidebar. [Guide →](/docs/ai-clients/grok) > * **Codex Terminal:** One command (bash installer). [Guide →](/docs/ai-clients/codex) > * **Codex Desktop:** Three chat messages inside the ChatGPT desktop app. [Guide →](/docs/ai-clients/codex-desktop) ## Ad Platforms > **Which ad platforms does Adspirer support?** > > Six platforms with 400+ tools: > > | Platform | Tools | What You Can Do | > | - | :-: | - | > | **Google Ads** | 156 | Keyword research, Search & PMax campaigns, wasted spend, budget optimization, ad extensions | > | **Amazon Ads** | 61 | Sponsored Products/Brands/Display, keyword & product targeting, bid optimization | > | **LinkedIn Ads** | 55 | Sponsored content, lead gen, B2B targeting, creative management | > | **Meta Ads** | 60 | Image/video/carousel campaigns, audience targeting, creative fatigue | > | **TikTok Ads** | 37 | In-feed campaigns, video asset validation | > | **ChatGPT Ads** | 36 | Conversational campaign launch and management | > > See [Platform Comparison](/docs/knowledge-base/platform-comparison) for a detailed breakdown. > **Can I use Adspirer with multiple ad accounts?** > > Yes. You can connect multiple accounts per platform. Use `switch_primary_account` to change which account you're managing, or specify the account ID in your prompts. See [Multi-Account Management](/docs/knowledge-base/multi-account). > **Does Adspirer work with agency accounts?** > > Yes. Adspirer supports MCC (My Client Center) accounts for Google Ads and Business Manager accounts for Meta. You can manage multiple client accounts from one Adspirer connection. See [Multi-Client Management](/docs/knowledge-base/multi-client). Agencies and teams managing many client accounts at scale should [book a demo](https://www.adspirer.com/book-demo) — we'll size a plan with multi-seat access and pooled tool calls. > **Are campaigns created live or paused?** > > **Always paused.** Every campaign Adspirer creates starts in PAUSED status. You review the campaign — targeting, keywords, ad copy, budget — and manually enable it when you're ready. This is enforced at both the skill level and the tool level. ## Pricing & Billing > **I see a \$39 charge alongside my plan — did my subscription change?** > > No. That's the [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook), a **one-time** add-on covering **one ad account**. If you added it during plan checkout it lands on the same invoice as your subscription, as a separate line reading **"One-time Agent Setup — 1 Ad Account"** — which is why that month's total was higher. Your recurring plan price is unchanged and the \$39 will not appear again. Annual plans include one playbook free. > **What's a tool call? Is it the same as a task?** > > Yes — a tool call is a **task** your AI assistant performs for you, on a complexity spectrum: > > * **Simple task (1 call):** "What's my Google Ads ROAS this month?" · keyword research · pull last week's performance > * **Medium task (8–12 calls):** Launch a single campaign — research keywords, write ad copy, validate assets, create paused, summarize for review > * **Complex task (25–40+ calls):** "Take my Q2 media plan and launch paused campaigns across Google, Meta, and LinkedIn" — multi-platform research, asset validation, and creation in one prompt > > The same plan covers tasks at every level — you just use more calls when the task is bigger. See [full breakdown](/docs/knowledge-base/pricing#how-tool-calls-work). > **How much does Adspirer cost?** > > Pricing is based on **tool calls**, not ad spend: > > | Plan | Price | Tool Calls | Best For | > | - | - | :-: | - | > | **Free** | \$0/mo | 15/month | Setup verification + 1 trial campaign | > | **Plus** | \$49/mo | 150/month + overage | Solo advertisers, single platform | > | **Pro** | \$99/mo | 600/month | Active multi-platform campaign managers | > | **Max** | \$199/mo | 3,000/month | Agencies, sequential sub-agents, power users | > > Plus subscribers get pay-as-you-go overage after 150 calls at $0.50/call, capped at $50/month. A typical single-campaign launch uses **8–12 tool calls**; a multi-platform launch from one media plan uses **25–40+**. The Pro plan ($99/mo) delivers ~120 hours of equivalent specialist work — about **76× cheaper than an in-house specialist** ($7,500/mo) and **15× cheaper than an Upwork contractor** (\$1,500/mo). See [full pricing](/docs/knowledge-base/pricing). > **Is there a free tier?** > > Yes — 15 tool calls/month, no credit card required. The free tier is sized to **verify Adspirer connects to your AI client and ad accounts** and to run **one** end-to-end campaign as a taste test. It's an evaluation tier — not enough for ongoing production work. For active campaign management, plan on Plus (\$49/mo) or above. [Sign up free →](https://adspirer.ai/sign-up?utm_source=docs\&utm_medium=faq\&utm_content=signup) > **Do I need a paid ChatGPT or Claude subscription to use Adspirer?** > > **It depends on your AI client.** Custom MCP connectors require: > > * **Claude:** Pro, Max, Team, or Enterprise (connectors aren't available on the Claude free tier) > * **ChatGPT:** Plus or Pro (connectors aren't available on the ChatGPT free tier) > > These are *AI platform* requirements set by Anthropic and OpenAI, not Adspirer's. **Free alternatives** that connect to Adspirer without a paid Claude or ChatGPT subscription: [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), [Codex](/docs/ai-clients/codex), [Windsurf](/docs/ai-clients/windsurf), [OpenClaw](/docs/ai-clients/openclaw), and [Gemini CLI](/docs/ai-clients/gemini-cli). > **Do I pay separately for each AI client?** > > No. Your Adspirer plan works across all AI clients. The same account and tool call quota applies whether you use Claude, ChatGPT, Perplexity, Cursor, Codex, Claude Code, Windsurf, or any other MCP-compatible client. ## Security & Privacy > **Is my data safe?** > > Yes. Key protections: > > * **OAuth 2.1 with PKCE** — Adspirer never sees your passwords > * **Scoped permissions** — you authorize exactly what Adspirer can do > * **Encrypted tokens** — access tokens encrypted at rest, auto-refreshed > * **Revocable access** — revoke anytime from your ad platform's security settings > * **No billing data** — Adspirer never accesses credit cards or payment information > > See [Security & Data Privacy](/docs/knowledge-base/security) for full details. > **Can I revoke Adspirer's access?** > > Yes, anytime. Go to your ad platform's security or connected apps settings: > > * **Google Ads:** [myaccount.google.com/permissions](https://myaccount.google.com/permissions) > * **Meta:** Settings & Privacy → Settings → Business Integrations > * **LinkedIn:** Settings → Data Privacy → Permitted Services > * **TikTok:** Settings → Security → Authorized Apps > **How are API keys secured?** > > API keys are hashed with SHA-256 before storage — the raw token is never stored server-side. Keys can be revoked instantly from the dashboard, set to expire after a specified period, and are tier-limited (Free: 2 keys, Plus: 5, Pro: 10, Max: 20). See [Security — API Key Authentication](/docs/knowledge-base/security#api-key-authentication). > **Does Adspirer store my ad data?** > > Adspirer reads your campaign data in real-time from ad platform APIs and returns it to your AI client. It does not permanently store campaign performance data, ad copy, or targeting settings. OAuth tokens are stored encrypted for session management. ## Troubleshooting > **Nothing is working — tools fail or I can't reach Adspirer** > > If **no tools work at all** (even `get_connections_status` or `echo_test` fails), this is a connection issue between your AI client and the Adspirer MCP server. Follow these steps in order: > > **Step 1: Check tool permissions** > > Your AI client needs the right tool permission settings: > > * **Read tools** (performance analysis, keyword research, connection status): Set to **Always allow** > * **Write tools** (campaign creation, budget changes): Set to **Custom** (ask each time) > > If tools are set to "Block" or "Never allow," Adspirer can't execute anything. Check your connector settings and toggle permissions. > > **Step 2: Disconnect and reconnect the Adspirer connector** > > * **Claude (web/desktop):** Go to **Customize → Connectors**, find **Adspirer Ads & Performance Marketing Agent**, click **Disconnect**, then **Connect** again and complete the OAuth flow. If you also have an older custom connector pointing at `mcp.adspirer.com`, remove it and keep only the verified listing > * **ChatGPT:** Go to **Settings → Plugins**, remove the plugin you created, then **Plugins → Add → Add custom MCP server** again with `https://mcp.adspirer.com/mcp` and sign in. On the Adspirer plugin from the directory? It's having issues right now; disconnect it and add the custom MCP server instead > * **Claude Code:** Type `/plugin` → **Installed** tab → select **adspirer** → **Authenticate** (or use `/mcp` → **plugin:adspirer-ads-agent:adspirer MCP Server** → **Authenticate**) > * **Cursor:** Open **Customize → MCP**, toggle `adspirer` off and back on to re-run OAuth > * **Grok Bot:** Open Adspirer from **Marketplace** and click **Authorize** again > > **Step 3: Refresh your Adspirer session** > > If reconnecting the connector doesn't fix it, your Adspirer login session may have expired: > > 1. Go to [adspirer.ai](https://adspirer.ai) > > 2. Log out (click your avatar → Sign out) > > 3. Log back in > > 4. Return to your AI client and try again > > > [!NOTE] > > > > **When does this apply?** Only when *nothing* works — not even basic tools like `get_connections_status`. If some ad accounts work but one doesn't (e.g., Google works but LinkedIn fails), that's a platform-specific connection issue, not a general connection problem. In that case, reconnect just that platform at [adspirer.ai/connections](https://adspirer.ai/connections). > **I clicked Authorize and the page didn't change** > > It did work. The **Authorize** screen hands off to your AI client, and that hand-off takes a second or two — so for a moment the page looks like it ignored you. > > What you should see on the first click: the button becomes a spinner reading **Connecting…**, with a line underneath naming the app you're connecting. Clicks after that are deliberately ignored, so you can't send a second approval by clicking twice. Desktop apps open over this page rather than replacing it, so those end on **Sent ✓** — close the window once the app comes up. > > If it's slower than that, the screen tells you. Around eight seconds it says it's still connecting and asks you to keep the window open. Around twenty it tells you to press **Authorize** again if your client never opened — do that rather than reloading the page or going back to your client. > > **If you left the screen open for a while,** your Adspirer sign-in may have expired behind it. Clicking **Authorize** sends you back through sign-in and returns you to the same screen with your request intact: finish signing in, click **Authorize** again, and you're connected. You don't need to start over from your AI client. > > If the retry still doesn't land you back in your client, disconnect and reconnect Adspirer using the steps in **Nothing is working** above. > **I connected an ad account during setup and never got back to Authorize** > > Connecting an ad account during setup opens that platform's own sign-in in a pop-up. On mobile Chrome and desktop Safari that pop-up often comes back without a link to the tab it opened from, and Adspirer used to hold the pending authorization in that one tab — so setup finished, you landed on your account page, and your AI client was left unconnected. > > It now follows the return. The authorization rides on the return address Adspirer hands the ad platform, so an opener-less return still finishes the hand-off, and the plan step in the middle of setup keeps it too. > > **If you finished setup in a different tab,** go back to the tab you started in — the one whose address still carries the authorization — and it forwards you to the **Authorize** screen on its own. > > If no such tab is left, start the connection again from your AI client: open Adspirer in its connector or plugin settings and click **Connect**. You'll be sent back to **Authorize** with a fresh request. Your ad accounts stay connected either way — you're only redoing the hand-off to the client. > **Why does my connector keep disconnecting? (Claude / ChatGPT web)** > > Claude (web/desktop) and ChatGPT periodically disconnect MCP connectors — typically every **1–2 weeks**. This is normal behavior for web-based AI clients, not an Adspirer issue. > > **When it happens:** > > 1. Go to your AI client's connector settings > > 2. Find Adspirer (in Claude it is **Adspirer Ads & Performance Marketing Agent**) > > 3. Click **Connect** (or re-enable it) > > 4. Complete the OAuth flow if prompted > > 5. Verify tool permissions are set correctly (read tools → Always allow, write tools → Custom) > > > [!TIP] > > > > If you find yourself reconnecting frequently, make sure you're logged into [adspirer.ai](https://adspirer.ai) in the same browser. An active Adspirer session makes re-authentication faster (often just a single click). > **Why isn't Adspirer connecting to my ad account?** > > Common causes: > > 1. **Ad platform not connected:** Visit [adspirer.ai](https://adspirer.ai) and connect your Google/Meta/LinkedIn/TikTok account > 2. **OAuth expired:** Re-authenticate by clicking the MCP server connection in your AI client > 3. **Browser extension interference:** Disable ad blockers temporarily during OAuth > 4. **Wrong account:** Use `switch_primary_account` to select the correct ad account > **Why do I see 'token expired' errors?** > > Access tokens expire after 1 hour. Adspirer auto-refreshes them, but if the refresh token (30-day lifetime) has also expired, you'll need to re-authenticate: > > * **Claude Code:** Run `/mcp`, select the Adspirer server, and re-authenticate > * **Claude:** Reconnect the connector in Customize → Connectors > * **ChatGPT:** Reconnect in Settings → Plugins > * **Cursor:** Open **Customize → MCP**, toggle `adspirer` off and back on to re-run OAuth > * **Grok Bot:** Open Adspirer from **Marketplace** and click **Authorize** again > > If re-authenticating doesn't work, log out of [adspirer.ai](https://adspirer.ai) and log back in to refresh your session, then reconnect the connector. > **I hit my tool call limit. What now?** > > You have three options: > > 1. **Upgrade to a higher tier** — takes effect immediately and resets your counter. > 2. **Wait for your monthly reset** — your quota resets on your billing date. > 3. **Switch to an annual plan** — annual subscribers get one large yearly pool instead of a monthly cap. No monthly resets, no mid-month walls. Use calls heavily during launch periods and lightly when campaigns are running steady. > > Plan-specific behavior: > > * **Free (15 calls):** Upgrade to Plus or wait for the monthly reset. > * **Plus (150 calls):** Overage billing is on by default — you keep going at $0.50/call, capped at $50/month. If you've hit the cap, upgrade to Pro or switch to annual. > * **Pro / Max:** Upgrade to the next tier, switch to annual, or wait for reset. > > Check your current usage by asking your AI assistant: `Check my Adspirer usage status` > > [View pricing & annual plans →](/docs/knowledge-base/pricing) > **My API key isn't working. What should I check?** > > Common causes: > > 1. **Key revoked or expired:** Check your key status at [adspirer.ai/keys](https://adspirer.ai/keys) > 2. **Wrong format:** API keys start with `sk_live_` — check for extra whitespace or line breaks > 3. **No ad platforms connected:** API keys authenticate you, but you still need to connect platforms at [adspirer.ai/connections](https://adspirer.ai/connections) > 4. **Environment variable issue:** Verify with `echo $ADSPIRER_API_KEY` > > Generate a new key if the existing one is compromised or expired. > **Campaign creation failed. What should I do?** > > Don't retry automatically. Common causes: > > * **Missing keyword research:** Run `research_keywords` before creating Search campaigns > * **Invalid assets:** Run `validate_and_prepare_assets` to check image dimensions, headline lengths > * **Platform not connected:** Run `get_connections_status` to verify > * **Budget below minimum:** Google/LinkedIn require $10/day minimum, Meta $5/day > > If using skills, the workflow handles all of these automatically. ## Related Documentation * [Security & Data Privacy](/docs/knowledge-base/security) — OAuth, token lifecycle, data access * [Pricing](/docs/knowledge-base/pricing) — Plans and tool call limits * [Platform Comparison](/docs/knowledge-base/platform-comparison) — Google vs Meta vs LinkedIn vs TikTok * [Agent Skills Overview](/docs/agent-skills/overview) — Skills, workflows, and safety rules * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Adspirer Glossary: MCP, ROAS, PMax & Ad Terms Source: https://www.adspirer.com/docs/knowledge-base/glossary Definitions of advertising, marketing, and technology terms used across Adspirer. CPC, ROAS, MCP, PMax, OAuth, and 30+ more terms explained. Quick reference for terms used across Adspirer documentation and the advertising industry. ## A **A/B Test** Running two ad variations simultaneously to determine which performs better. Change one variable at a time (headline, image, audience) for clean results. **Ad Extensions** Additional information added to Google Ads (sitelinks, callouts, structured snippets, price extensions). Extensions increase ad real estate and improve Quality Score. Adspirer adds these automatically with `add_sitelinks`, `add_callout_extensions`, and `add_structured_snippets`. **Ad Group** A container within a campaign that holds a set of related ads and keywords. Each ad group targets a specific theme or product. **AGENTS.md** The brand context file used by [Codex CLI](/docs/ai-clients/codex). Equivalent to `CLAUDE.md` (Claude Code) and `BRAND.md` (Cursor). Contains brand overview, audiences, budgets, and KPI targets. **Attribution Model** The rule that determines how credit for conversions is assigned to touchpoints. Common models: last-click, first-click, linear, data-driven. ## B **Bid Strategy** The method used to set bids for your ads. Options include Manual CPC, Target CPA, Target ROAS, Maximize Clicks, and Maximize Conversions. Adspirer recommends a strategy based on your campaign data using `update_bid_strategy`. **BRAND.md** The brand context file used by [Cursor](/docs/ai-clients/cursor). Equivalent to `CLAUDE.md` (Claude Code) and `AGENTS.md` (Codex). **Broad Match** A keyword match type in Google Ads that shows your ad for searches related to your keyword, including synonyms and related topics. Broadest reach but least precise. ## C **Callout Extension** Short text snippets (max 25 characters) that highlight value propositions in Google Ads. Examples: "Free Shipping", "24/7 Support", "No Setup Fee". **CLAUDE.md** The brand context file used by [Claude Code](/docs/ai-clients/claude-code). Created by `/adspirer:setup`. Contains brand overview, voice, audiences, connected platforms, budgets, and KPI targets. **Conversion** A completed action that you've defined as valuable — a purchase, form submission, phone call, or sign-up. **Conversion Window** The period after an ad interaction during which a conversion is attributed to that ad. Typically 7-30 days. **CPA (Cost Per Acquisition)** Total ad spend divided by number of conversions. Lower is better. Formula: `Spend ÷ Conversions`. **CPC (Cost Per Click)** The amount you pay each time someone clicks your ad. Formula: `Spend ÷ Clicks`. **CPM (Cost Per Mille)** Cost per 1,000 impressions. Used primarily for awareness campaigns on Meta and LinkedIn. **Creative Fatigue** When ad performance declines because the audience has seen the same creative too many times. Symptoms: rising frequency, declining CTR. Adspirer detects this with `detect_meta_creative_fatigue`. **CTR (Click-Through Rate)** Percentage of impressions that result in clicks. Formula: `Clicks ÷ Impressions × 100`. Higher is generally better. ## D **DSA (Dynamic Search Ads)** Google Ads campaign type that automatically generates headlines from your website content and matches to relevant searches. ## E **Exact Match** A keyword match type in Google Ads that shows your ad only for searches that match the exact meaning of your keyword. Most precise but narrowest reach. ## I **Impression** A single instance of your ad being displayed to a user. **Impression Share** The percentage of eligible impressions your ad actually received. Low impression share may indicate budget constraints or low Ad Rank. ## K **KPI (Key Performance Indicator)** The primary metric you use to measure campaign success. Common KPIs: CPA, ROAS, CTR, conversion rate, cost per lead. ## L **Lookalike Audience** An audience on Meta Ads that mirrors the characteristics of your existing customers. Created from a source audience (customer list, website visitors, or app users). **LTV (Lifetime Value)** The total revenue a customer generates over their entire relationship with your business. Used to determine acceptable CPA. ## M **Match Type** Controls which searches trigger your Google Ads keywords. Three types: Broad Match, Phrase Match, Exact Match. Adspirer manages match types with `add_keywords` and `update_keyword`. **MCP (Model Context Protocol)** An open standard created by Anthropic that allows AI assistants to connect to external tools and services. Adspirer uses MCP to give AI clients access to 400+ advertising tools. See [How MCP Works](/docs/mcp). **MEMORY.md** A persistent file used by Claude Code and Cursor agents to remember past decisions, optimization results, preferences, and learnings across sessions. Not available in Codex. ## N **Negative Keywords** Keywords you add to prevent your ads from showing for irrelevant searches. Example: adding "free" as a negative keyword prevents your premium product ads from showing on "free software" searches. Managed with `add_negative_keywords`. ## O **OAuth 2.1 with PKCE** The authentication standard Adspirer uses to connect to ad platforms. Your passwords stay with Google/Meta/LinkedIn/TikTok — Adspirer only receives scoped access tokens. See [Security](/docs/knowledge-base/security). ## P **Phrase Match** A keyword match type in Google Ads that shows your ad for searches that include the meaning of your keyword. Narrower than broad match, broader than exact match. **Prompt Engineering Playbook** A [one-time \$39 add-on](/docs/agent-skills/prompt-engineering-playbook) covering one ad account. Adspirer reads that account and generates a custom agent skill, a written account dossier, a prompt book against your real campaigns, and paste-ready agent instructions — delivered as a download you install in Claude, ChatGPT, Claude Code, Cowork, Cursor, or Codex. Not a subscription; nothing recurs. One is included free with annual plans. **PKCE (Proof Key for Code Exchange)** A security extension to OAuth that prevents authorization code interception attacks. Every authentication generates a cryptographic proof that only your specific session can complete. **PMax (Performance Max)** A Google Ads campaign type that uses AI to optimize across all Google channels (Search, Display, YouTube, Gmail, Maps, Discover) from a single campaign. ## Q **Quality Score** Google Ads' rating (1-10) of your ad relevance, expected CTR, and landing page experience. Higher Quality Score = lower CPC and better ad positions. Ad extensions improve Quality Score. ## R **Remarketing / Retargeting** Showing ads to people who previously visited your website or interacted with your brand. Available on Google Ads, Meta, and LinkedIn. **ROAS (Return On Ad Spend)** Revenue generated per dollar spent on ads. Formula: `Revenue ÷ Ad Spend`. A ROAS of 4.0 means $4 revenue for every $1 spent. **RSA (Responsive Search Ad)** Google Ads format where you provide multiple headlines (up to 15) and descriptions (up to 4), and Google tests combinations to find the best performers. ## S **Search Terms** The actual words people type into Google that trigger your ads. Different from keywords (which you set). Analyzing search terms with `analyze_search_terms` reveals opportunities and waste. **Sitelink Extension** Links to specific pages on your website that appear below your main ad. Each sitelink has text (max 25 chars), two description lines (max 35 chars each), and a destination URL. **SKILL.md** The instruction file that teaches AI assistants proven advertising workflows. Skills contain step-by-step tool sequences, safety rules, and platform guidance. See [Agent Skills Overview](/docs/agent-skills/overview). **STRATEGY.md** A persistent file where strategic decisions are saved as directives (AVOID, PREFER, CONSTRAINT, REQUIRE). All Adspirer skills read this before executing. Directives are only saved after user confirmation. **Structured Snippets** A Google Ads extension that shows predefined categories of offerings. Available headers: Brands, Courses, Destinations, Models, Service Catalog, Styles, Types. ## T **Target CPA** A Google Ads bid strategy that automatically sets bids to get as many conversions as possible at your target cost per acquisition. **Target ROAS** A Google Ads bid strategy that automatically sets bids to maximize conversion value at your target return on ad spend. **Task** What a tool call accomplishes for you. Tasks span a complexity spectrum: **simple** (1 call — e.g., "what's my ROAS?"), **medium** (8–12 calls — e.g., launch a single campaign with research + ad copy + validation), or **complex** (25–40+ calls — e.g., multi-platform launch from one media plan). The same Adspirer plan covers tasks at every level. See [Pricing — What counts as a tool call](/docs/knowledge-base/pricing#what-counts-as-a-tool-call). **Tool Call** The unit of Adspirer pricing. Each tool call is one task — anything from a one-line question to a multi-step campaign launch. A simple task is 1 call; a single campaign launch is 8–12 calls; a multi-platform launch from a media plan is 25–40+ calls. Tool call limits are shared across all AI clients (Claude, ChatGPT, Cursor, Codex, etc.) on a single Adspirer account. See [Pricing](/docs/knowledge-base/pricing). ## W **Wasted Spend** Ad spend on clicks that don't lead to conversions. Common causes: irrelevant keywords, broad match without negatives, poor landing pages, wrong audiences. Adspirer identifies waste with `analyze_wasted_spend`. # Google Asks for a Passkey When Connecting Google Ads Source: https://www.adspirer.com/docs/knowledge-base/google-passkey Google requires a passkey to authorize new Google Ads API access. What the passkey screen means, why a new passkey takes up to 7 days, and how to get connected. # Google asks for a passkey when I connect Google Ads When you connect Google Ads to Adspirer, Google may ask you for a **passkey** before it returns you to the account picker. That screen comes from Google, not from Adspirer. Since **5 August 2026**, Google requires a passkey to authorize new Google Ads API access. Every tool that works with the Google Ads API is covered by this — Google Ads Editor, Google Ads scripts, BigQuery Data Transfer Service, and Adspirer. A password, an SMS code, or an authenticator app is no longer enough on its own. > [!NOTE] > > **Already connected? Nothing changes for you.** Google only applies this when > new API access is authorized. An existing Adspirer connection keeps working and > will not ask you for anything — unless you disconnect and reconnect. ## Find your screen below > **"Try again in 6 days" or a security delay** > > You created a passkey, and Google holds a **brand-new passkey for up to 7 days** > before it will accept it. This is a Google security measure. Nothing shortens > it — not Adspirer, and not Google's own support. > > Your options: > > * **Use an older passkey.** If the same Google account already had a passkey > before this one, it works today. > * **Use a device that already signs you in.** A phone or laptop that Google > already trusts for this account will usually get you through. > * **Wait it out.** The connection works normally once the delay passes. Come > back to [Connections](https://adspirer.ai/connections) and connect Google Ads > again. > > In the meantime, Meta, TikTok and LinkedIn connect with no passkey step, and > the rest of Adspirer works as usual. > **"We couldn't find a passkey" or "your existing passkeys aren't compatible with this device"** > > Your Google account has a passkey, but not one this device can use. Try these > in order — most people are connected by the second one. > > **1. Open an incognito or private window** > > Sign in there and connect again. Google stops offering a stored passkey it > cannot use, and falls back to a method that works. This is the fix that > resolves it most often. > > **2. Choose "Try another way"** > > On Google's passkey screen, this lets you pick a different method or > another device — for example approving on your phone instead. > > **3. Add a passkey on the device you're actually using** > > Go to [Google's passkey settings](https://myaccount.google.com/signinoptions/passkeys) > and create one there. Note that a brand-new passkey carries the up-to-7-day > delay described above. > **I don't have a passkey, or I don't want to create one** > > To authorize new Google Ads API access you now need one. There is no > password-only path any more, for any tool. > > It is a smaller change than it sounds: > > * Setting one up takes about a minute, at [g.co/passkeys](https://g.co/passkeys). > * It does **not** change your Google password, and it does **not** change > anything in your Google Ads account or settings. > * A passkey can be your phone's screen lock, your laptop's fingerprint reader > or Windows Hello, or a hardware security key. You do not need a working > fingerprint sensor specifically — a PIN or screen lock is enough. > > Google's own guide: [Use a passkey with Google Ads](https://support.google.com/google-ads/answer/16968810). > **My work or school account won't allow passkeys** > > Some Google Workspace organizations block passkey sign-in. If that is your > account, the passkey screen is a dead end until your administrator changes it. > > Two ways forward: > > * **Ask your Google Workspace admin** to allow passkeys or security keys for > your account. > * **Connect with a different Google login.** Add a personal Google account as a > user on the Google Ads account in Google Ads, then connect that login to > Adspirer instead. This usually gets you running the same day. > **The passkey worked, but Adspirer still didn't connect** > > If Google accepted your passkey and told you that you were all set, but > Adspirer never showed the account picker, try once more in an **incognito > window with browser extensions turned off**. > > If it still doesn't complete, that one is worth reporting — contact us from the > in-app chat and say that the passkey succeeded but the connection did not land, > and we'll look at it. ## What Adspirer cannot do We are asked this often, so to be direct: Adspirer cannot turn the passkey requirement off, skip it, or get you an exception. The check happens inside your Google account, before Google hands anything to us — we never see the attempt. It is identical on every Adspirer plan, so upgrading does not change it either. ## Related * [Google Ads integration](/docs/ad-platforms/google-ads) * [Support](/docs/knowledge-base/support) # Adspirer in Your Language — 116 Languages Supported Source: https://www.adspirer.com/docs/knowledge-base/localization The Adspirer dashboard and onboarding are localized into 116 languages with full right-to-left support. Manage Google, Meta, Amazon, and TikTok Ads with an AI assistant in your own language. Adspirer is built for advertisers everywhere. The dashboard, onboarding, and setup guides are localized into **116 languages**, and because you manage campaigns by talking to an AI assistant, you can give instructions in whatever language you think in. > [!NOTE] > > The interface localization covers **116 languages**, including full **right-to-left (RTL)** rendering for Arabic, Hebrew, Persian, Urdu, and more. ## What's localized * **The Adspirer dashboard** — navigation, settings, connections, usage & billing, monitors, and shared dashboards. * **Onboarding** — account setup, plan selection, connecting your AI client, and connecting ad platforms. * **The setup guides** for every supported AI client. ## Language features > **Automatic detection** > > Adspirer detects your browser's preferred language on first visit and shows the interface in it automatically. > **One-click switcher** > > Prefer a different language? Switch any time from the language switcher — the full interface updates instantly. > **Right-to-left support** > > RTL languages render with correct layout direction throughout, not just translated text. > **Remembered across devices** > > Your language preference follows your account, so the dashboard opens in your language on every device you sign in from. ## Manage ads in your language The real power is conversational. You manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads by chatting with an AI assistant — so you can ask for what you want in your own language, and the agent understands and acts. Ask for a campaign in Spanish; the agent understands and acts. Analiza el rendimiento de mis campañas de Google Ads de los últimos 30 días. Muéstrame el gasto, las conversiones, el CPA y el ROAS, y señala las campañas con un ROAS inferior a 2.0. The same works in French, German, Portuguese, Japanese, Hindi, Arabic, and dozens more — ask for keyword research, campaign creation, or budget optimization in your language, and get answers back the same way. ## Why it matters for global teams and agencies * **Agencies** managing accounts across regions can give each operator the dashboard in their own language. * **Local advertisers** get onboarding and guidance without a language barrier. * **Cross-border campaigns** — target any country and language on the ad platforms while working in the language you're most comfortable in. ## FAQ > **How many languages does Adspirer support?** > > The interface is localized into **116 languages**, with right-to-left support for languages like Arabic, Hebrew, Persian, and Urdu. Conversationally, you can instruct the AI assistant in effectively any language it understands. > **Does changing the language change my ad targeting?** > > No. Interface language and ad targeting are independent. You can run the dashboard in one language while targeting audiences in any country and language on the ad platforms. > **How do I change my language?** > > Use the language switcher in the dashboard. Adspirer also auto-detects your browser language on first visit, and remembers your choice across devices. ## Related * [Getting Started](/docs/quickstart) * [Supported AI Clients](/docs/mcp#supported-clients) * [Capabilities](/docs/knowledge-base/capabilities) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Adspirer vs Other Ad MCP Servers Source: https://www.adspirer.com/docs/knowledge-base/mcp-server-comparison How Adspirer compares to Google's official MCP, Pipeboard, Synter, Flyweel, Windsor.ai, and community MCP servers for Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads. When AI assistants are asked "what's the best MCP server for Google Ads?", they usually recommend Google's free official server plus a handful of community repos — one per platform. It sounds thorough. In practice, it leaves most buyers with a separate install to maintain per platform, a separate OAuth flow to debug for each, and a stack that's **read-only on the one platform where reads-without-writes are least useful**. This page compares Adspirer against every credible option in the ad-MCP landscape — fairly. We'll tell you when a free single-platform MCP is the right call, and when a unified tool like Adspirer earns its subscription. ## TL;DR > **One account, six platforms** > > Adspirer unifies Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok behind a single account and config. A DIY stack means a separate MCP per platform, each with its own credentials. > **Write, not just read** > > Google's official MCP is read-only. Flyweel is read-only. Adspirer creates campaigns, adjusts budgets, and optimizes — with safety rails. > **Maintained, not a side project** > > Commercial support with 24-hour SLA on Max. Most community MCPs are solo-maintained GitHub repos that can go stale before your next launch. ## The Landscape in One Table The ad-MCP world divides cleanly into three buckets. Here's what's actually available, what it does, and what it doesn't. ### Single-platform MCPs (the "DIY stack" pieces) | MCP | Platforms | Read/Write | Maintenance | Honest take | | - | - | - | - | - | | **Google Ads MCP** (official, `google-marketing-solutions/google_ads_mcp`) | Google only | Read-only (GAQL (Google Ads Query Language — Google's SQL-like syntax for querying ad data) search + account listing) | Google team, Gemini-focused | The canonical "what AI tells buyers to use." Cannot modify bids, pause campaigns, or create assets. Diagnostics only. | | **cohnen/mcp-google-ads** | Google only | Read-only | Solo community repo | Nicer developer experience than Google's, same read-only ceiling. | | **Pipeboard Meta Ads MCP** | Meta (Pipeboard also ships separate Google + TikTok MCPs) | Read + Write | Active company (791★, 133 releases) | The most mature single-platform Meta MCP. Paused-by-default safety. But each platform is a **separate** install. | | **GoMarble Facebook Ads MCP** | Meta only | Read + basic write | Community | Free OSS. Requires Node.js, Meta API credentials, and comfort with CLI. | | **DanielPopaMD LinkedIn Ads MCP** | LinkedIn only | Read + Write (25+ tools) | Solo community | Most complete LinkedIn option in the community ecosystem. | | **AdsMCP TikTok MCP** | TikTok only | Read + Write | Community | The credible TikTok-only option. | | **Flyweel MCP** | Google + Meta | **Read-only** | Flyweel (company) | Marketed as free/unified — but it's a dashboard in chat, not a campaign tool. | | **Facebook Ads Library MCP** (trypeggy) | Meta public Ads Library | Read public data | Solo | Competitor research, not account management. Complementary, not a replacement. | ### Unified / multi-platform MCPs | MCP | Platforms | Read/Write | Pricing | Honest take | | - | - | - | - | - | | **Adspirer** | Google + Meta + Amazon + ChatGPT Ads + LinkedIn + TikTok | Full read + write, 400+ tools | Free → \$199/mo ([pricing](/docs/knowledge-base/pricing)) | Campaign-depth on the six platforms most buyers actually run. Published [safety rails](/docs/knowledge-base/capabilities). First-class across 12+ AI clients. | | **Synter** | 14 platforms (adds Reddit, Pinterest, Snapchat, X, Microsoft, Taboola) | Full read + write | From \~\$199/mo | Broader platform list, newer product. A real option if you run on channels beyond the six Adspirer covers. | | **Ryze / irinabuht12-oss/google-meta-ads-ga4-mcp** | Google + Meta + GA4 | Full read + write | OSS + commercial Ryze platform | Legitimate (273★) but only 3 commits on main and tied to Ryze AI. No LinkedIn or TikTok. | | **Windsor.ai MCP** | 325+ data sources | **Read-focused** (analytics over a warehouse) | Windsor.ai subscription | Different category. Cross-channel reporting — not campaign execution. Complementary to Adspirer. | ### Agent-skill marketplaces A related data point: the [Clawhub marketplace](https://www.adspirer.com/docs/ai-clients/openclaw) (the skill directory for the OpenClaw client) shows 25 "Ads" skills. Top community skills have high install counts but **single-digit version numbers** — many have shipped exactly one release since launch. Adspirer's skill has shipped **10 versions** and counting. When a Graph API change lands, version velocity is the difference between a working agent and a broken one. ## The Six Axes That Actually Matter We compare every MCP against the same six criteria. These are the dimensions that determine whether your stack still works six months from now. ### 1. Platform coverage **Why it matters:** Most advertisers run two or more platforms within their first year. Every siloed MCP is another install, another credential, another thing to keep current. **Adspirer position:** Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok from one server. See [supported platforms](/docs/ad-platforms/google-ads). ### 2. Read vs. write depth **Why it matters:** A read-only MCP can answer "what's my CTR this month?" but it cannot launch a campaign, pause a waster, or rebalance a budget. That's the difference between a dashboard and an ad-ops tool. **Adspirer position:** Full lifecycle write — create Search / Performance Max / Image / Video / Carousel / Sponsored Content campaigns, adjust targeting, bulk operations. See the [full capability list](/docs/knowledge-base/capabilities). ### 3. Provisioning and operations **Why it matters:** A separate OAuth flow, token refresh cycle, and config schema per platform — and a separate failure mode every Monday morning. **Adspirer position:** One connection per ad platform (OAuth, or a pasted API key for ChatGPT Ads), routed through one Adspirer account, configured once in your AI client. See the [multi-account guide](/docs/knowledge-base/multi-account). ### 4. Maintenance and longevity **Why it matters:** Meta ships breaking Graph API changes every few months. Google deprecates Ads API versions on a schedule. A solo-maintained community repo that goes quiet for 90 days is a liability on an account spending real money. **Adspirer position:** Commercial product with active engineering. API shims are maintained server-side — your AI client config doesn't have to change when Google ships v20 of the Ads API. ### 5. Safety rails **Why it matters:** Large language models will confidently execute "delete all campaigns that didn't convert last month" if the tool layer lets them. Prompt-based safeguards are not enough; the server itself must refuse destructive actions. **Adspirer position:** The tool layer has hard, structural constraints: * Cannot delete existing campaigns * Cannot pause running campaigns * Cannot modify existing budgets * All new campaigns created **PAUSED** for human review An LLM cannot call tools that don't exist. See [capabilities](/docs/knowledge-base/capabilities#what-adspirer-does) for the full scope. ### 6. Support and SLA **Why it matters:** "Open a GitHub issue" is not a support plan when a product launch depends on ads going live tonight. **Adspirer position:** Commercial support on all paid tiers. 24-hour SLA on [Max](/docs/knowledge-base/pricing). Teams that need priority response or custom integrations can [book a demo](https://www.adspirer.com/book-demo). ## Secondary But Significant These matter once the primary axes are addressed. **Security posture.** Adspirer uses OAuth 2.1 with PKCE (Proof Key for Code Exchange — prevents authorization code interception attacks), HTTPS/TLS encryption, and no conversation logging. Recent research from Astrix Security found that **53%** of public MCP servers rely on long-lived static API keys or Personal Access Tokens, and only **8.5%** use OAuth. Many community ad MCPs ask you to paste a write-scoped access token into a config file. Read our [security page](/docs/knowledge-base/security) for details. **AI client coverage.** Adspirer works with ChatGPT, Claude (Desktop/Web/Code), Claude Cowork, Cursor, Grok Bot, Codex, Windsurf, OpenClaw, Gemini CLI, Manus, Perplexity, and Custom GPTs. Many community MCPs only document Claude Desktop. **Multi-account and multi-client routing.** Agency workflows require switching between a dozen client accounts across three platforms inside a single conversation — without reconfiguring. See [multi-account](/docs/knowledge-base/multi-account) and [multi-client](/docs/knowledge-base/multi-client). ## The Three Claims We Hear Most ### "I'll just use Google's free official MCP." Google's MCP is a real, well-built tool — for read-only diagnostics. From Google's own documentation: *"the initial version of the MCP Server is read-only, designed for diagnostics and analytics."* It cannot modify bids, pause campaigns, or create new assets. If your use case is *"ask questions about performance in chat,"* it's the right call. If it's *"manage Google Ads from chat,"* you need a write layer — and that's a different product. See [Why not use Google's free MCP?](/docs/knowledge-base/why-not-official-google-ads-mcp) for the full breakdown. ### "Pipeboard is basically the same thing for less." Pipeboard is a legitimate company with an actively-maintained product. Their Meta MCP supports campaign creation with paused-by-default safety. They also ship separate MCPs for Google Ads and TikTok Ads. What's different: * **No LinkedIn.** Hard stop for B2B advertisers. * **Still three separate remote services.** Same operational shape as any DIY stack — one vendor, three installs. * **No unified reasoning surface.** "What's my blended CPA across Meta and Google this week?" requires the LLM to reconcile two tool namespaces across two MCPs. On Meta-only workloads, Pipeboard vs. Adspirer is a close single-platform fight. At the multi-platform stack level, the question is whether you want one product or three. ### "Community MCPs are free and work fine." For a solo advertiser running one platform on one account, a maintained community MCP is often the right starting point. The math changes when: * You run two or more platforms (maintenance surface doubles or triples). * You have a team that needs shared access. * You're responsible for uptime — an API break that sits unpatched for a week is a real cost. * You're handling credentials with write scope on production ad accounts. ## When Not to Choose Adspirer We don't win every comparison, and pretending otherwise would waste your time. > **One platform, one account, read-only needs** > > Google's free official MCP or Pipeboard's free tier is the right starting point. Come back to Adspirer when you add a second platform or need write access. > **You need a platform we don't cover** > > If your stack includes Reddit, Pinterest, X, Snapchat, or Microsoft Ads, Synter's wider platform list is the relevant comparison. (Adspirer covers Amazon Sponsored Products/Brands/Display, but not Amazon DSP.) [Request a platform →](mailto:abhi@adspirer.com) > **Cross-warehouse analytics, not campaign execution** > > Windsor.ai and similar data-warehouse MCPs are purpose-built for BI questions over 100+ synced sources. That's a different job — complementary, not a substitute. > **A one-off engineer doing local analysis** > > If you're a developer comfortable self-hosting and the MCP will live on your laptop for a specific project, community repos are a fine choice. ## Where Adspirer Wins > **Multi-platform, campaign-depth work** > > When you're running Google + Meta + Amazon + LinkedIn or TikTok and you need to launch, optimize, and pace from chat — not just query. > **Agencies with many clients** > > Multi-account routing across multiple platforms in one conversation. See [multi-client](/docs/knowledge-base/multi-client). > **Teams that care about safety rails** > > Destructive operations are structurally unavailable. No "oops, deleted the wrong campaign" class of failure. > **AI-first stacks beyond Claude Desktop** > > First-class across ChatGPT, Claude Code, Cursor, Grok Bot, Codex, Windsurf, OpenClaw, Manus, and more. ## Frequently Asked Questions > **Isn't Google's MCP server free? Why pay Adspirer?** > > Google's official MCP is free and read-only. It can query your Google Ads account via GAQL and answer questions about historical performance. It cannot launch a campaign, change a budget, pause a campaign, or create assets. Adspirer is the write layer — a different product category. If you only need to ask questions in chat, Google's free MCP is fine. If you need to run Google Ads from chat, you need a tool that supports writes. See the [full breakdown](/docs/knowledge-base/why-not-official-google-ads-mcp). > **I already use Pipeboard for Meta. Should I switch?** > > If Meta is your only platform and it'll stay that way, Pipeboard is a real option and a reasonable one. Most Adspirer customers run two or more platforms. At that point the comparison isn't "Pipeboard vs. Adspirer Meta tools" — it's "one unified MCP vs. two-to-four separate installs across platforms." That's where the math changes. > **How does Adspirer compare to Synter?** > > Synter covers 14 platforms (including Reddit, Pinterest, Snapchat, X, Microsoft, Taboola). Adspirer covers six — the ones most of our buyers actually run (Google, Meta, Amazon, ChatGPT Ads, LinkedIn, TikTok). If your stack needs one of Synter's additional platforms, they're the better fit. If you're on the platforms Adspirer supports, we focus on depth: published safety rails, first-class agent integration across Claude Code / Cursor / Codex / OpenClaw / Manus / Gemini CLI (not just Claude Desktop), and documented multi-account workflows. > **Can Adspirer delete or pause my existing campaigns if the AI makes a mistake?** > > No. The tool layer has structural constraints: Adspirer cannot delete existing campaigns, cannot pause running campaigns, and cannot modify existing budgets. These aren't prompt-based safeguards — those destructive tools don't exist in the server. An LLM cannot call what isn't there. All **new** campaigns are also created PAUSED by default, so a human reviews before anything spends. See [capabilities](/docs/knowledge-base/capabilities). > **Why not build our own internal MCP against the Marketing APIs?** > > You can. The build is a week; the maintenance is forever. Meta and Google ship breaking Marketing/Graph API changes on a schedule. A campaign-depth surface with 400+ tools is meaningful software to own, test, and secure. Most ad teams would rather spend that engineering time on product, not on API plumbing. [Talk to us](https://www.adspirer.com/book-demo) about private-deployment options. > **What AI clients does Adspirer work with?** > > ChatGPT, Claude Desktop, Claude Web, Claude Code, Claude Cowork, Cursor, Grok Bot, Codex, Windsurf, OpenClaw, Gemini CLI, Manus, Perplexity, and Custom GPTs. See the [AI Clients section](/docs/ai-clients/chatgpt) for setup guides per client. > **Is Adspirer free to try?** > > Yes — 15 tool calls per month forever, no credit card. Enough to test connection, pull performance data, and create 2-3 campaigns. See [pricing](/docs/knowledge-base/pricing). > **What security guarantees does Adspirer provide?** > > OAuth 2.1 with PKCE for all platform authentications, HTTPS/TLS encryption in transit, no conversation logging. Full details on the [security page](/docs/knowledge-base/security). Need SSO, audit logging, or a private deployment? [Talk to us](https://www.adspirer.com/book-demo). ## Related Reading > **[Best ad MCP servers in 2026](https://www.adspirer.com/blog/best-ad-mcp-servers-2026)** > > Ranked honest reviews of every credible ad MCP server. > **[Why not Google's free MCP?](/docs/knowledge-base/why-not-official-google-ads-mcp)** > > The detailed breakdown of what Google's official MCP does and doesn't do. > **[What Adspirer can & can't do](/docs/knowledge-base/capabilities)** > > Full capability list and stated limitations. > **[Platform comparison](/docs/knowledge-base/platform-comparison)** > > Google vs Meta vs Amazon vs TikTok for advertisers. > **[Pricing](/docs/knowledge-base/pricing)** > > Plans, tool call limits, and usage examples. > **[Security](/docs/knowledge-base/security)** > > OAuth, encryption, and data handling specifics. ## Further Reading on the Blog Prefer the deeper, opinion-driven treatments? These blog posts go into the same territory with more narrative depth and honest side-by-side reviews: * [The 10 Best Ad MCP Servers in 2026 — Honest Rankings](https://www.adspirer.com/blog/best-ad-mcp-servers-2026) * [Adspirer vs Pipeboard: Meta Ads Head-to-Head](https://www.adspirer.com/blog/adspirer-vs-pipeboard) * [Why You Shouldn't Just Use Google's Free MCP Server](https://www.adspirer.com/blog/why-not-google-free-mcp-server) * [What Is MCP? A Marketer's Guide](https://www.adspirer.com/blog/what-is-mcp-model-context-protocol) * [10 Best AI Tools for PPC Managers in 2026](https://www.adspirer.com/blog/best-ai-tools-ppc-managers-2026) # Manage Multiple Ad Accounts with Adspirer Source: https://www.adspirer.com/docs/knowledge-base/multi-account Manage multiple ad accounts across Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads from one Adspirer connection. Annual plans activate up to 5 accounts per platform. You can connect **unlimited ad accounts** across all plans — there is no restriction on how many accounts you link. The difference between plans is how many accounts can be **active** (used by the agent) at once, per platform: | Plan | Active Per Platform (Monthly) | Active Per Platform (Annual) | | - | :-: | :-: | | Free | 1 | 1 | | Plus | 1 | **5** | | Pro | 1 | **5** | | Max | **5** | 5 | The cap is **per platform** — every plan counts Google Ads, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok independently. A Plus annual customer can activate up to 5 Google Ads accounts **and** 5 Meta accounts at the same time. When you have 2+ active accounts on a platform, Adspirer's **sequential sub-agents** fan out tool calls across them in a single conversation — no manual switching required. ## How it works Your Adspirer account can connect to multiple ad accounts on each platform: * Multiple Google Ads customer IDs (including across **multiple Google logins** — see below) * Multiple Meta Business Manager ad accounts (full **BM-wide import** since May 2026) * Multiple LinkedIn Campaign Manager accounts * Multiple TikTok Ads Manager accounts When you first connect on a monthly plan (or Free), one account per platform is **active** by default — all tool calls target that account. To work in another account, switch via the [Manage Accounts](https://adspirer.ai/connections) modal. Searching for an account there and activating it adds it to the accounts you already have active; an account only goes inactive when you untick it. On annual plans and on Max monthly, you can activate up to 5 accounts per platform at the same time and let sequential sub-agents fan out tool calls automatically. ### Multiple Google logins on one Adspirer account Agencies and consultants who manage Google Ads across **separate Google identities** can attach multiple Google OAuth grants to a single Adspirer account. Each grant contributes its own non-overlapping set of Google Ads customer IDs; the agent routes tool calls to the right OAuth based on which customer you reference. Add a second login from **Connections → Google Ads → Add another Google login**. Available on Max annual today; rolling to other paid tiers as the `feature_multi_google_oauth` rollout completes. ## Switching Accounts To change which account you're managing: ``` Switch to my Google Ads account 123-456-7890 ``` Or use the tool directly: ``` switch_primary_account(platform="google_ads", account_id="1234567890") ``` The switch persists for your current session. All subsequent tool calls target the new account until you switch again. You can switch **by business name, right from chat** — Adspirer resolves the name to the right account ID for you: ``` Use my Sahaayak Google Ads account instead ``` This works for **Google MCC child accounts** too: `list_connected_accounts` surfaces connected-but-not-yet-activated child accounts under your manager account, so you can name one and the agent switches to it without a trip to the web app. How the switch resolves depends on your cap: * **Single-active tiers** (Free, monthly Plus/Pro): the new account **replaces** the active one. * **Multi-active tiers** (annual Plus/Pro, Max): the new account is **added** to your active set, up to your per-platform cap of 5. A switch that would exceed your cap is rejected rather than silently dropping another account. ## Sequential sub-agents (Max plan) The **Max plan** unlocks sequential sub-agents — a workflow where Adspirer fans out tool calls across multiple ad accounts in a single conversation, without manual switching. Instead of one primary account per platform, Max users mark multiple accounts as **active**, and the agent runs sub-agents per account in sequence. This is the model agencies and portfolio managers use to run cross-account audits, weekly briefs, and bulk optimizations from one prompt. ### Active accounts vs. primary account | Plan | Cap (per platform) | Account model | How tool calls resolve | | - | :-: | - | - | | Free | 1 | Single active account | Tool calls target the active account; switch from Manage Accounts | | Plus monthly / Pro monthly | 1 | Single active account | Tool calls target the active account; switch from Manage Accounts | | Plus annual / Pro annual | **5** | Multiple active accounts | Sequential sub-agents iterate over each active account automatically | | Max (monthly or annual) | **5** | Multiple active accounts | Sequential sub-agents iterate over each active account automatically | ### Discovering active accounts Max users start a session by listing all active accounts: ``` List my connected ad accounts ``` Or call the tool directly: ``` list_connected_accounts() ``` This returns every active account with its platform, account ID, name, and status. Filter by platform when needed: ``` list_connected_accounts(platform="google_ads") ``` > [!TIP] > > `list_connected_accounts` makes zero API calls — it reads from the database, so it doesn't count against your tool call quota or platform rate limits. ### Example: cross-account weekly brief A Max user managing multiple client Google Ads accounts can run: ``` Run last week's performance brief across all my Google Ads accounts. ``` Adspirer's sequential sub-agents call `get_campaign_performance` once per active account, aggregate the results, and return a single consolidated brief — no per-account switching required. ### Targeting one account at a time Even on Max, you can scope a single tool call to one account by passing the platform-specific account ID: | Platform | Parameter | Example | | - | - | - | | Google Ads | `customer_id` | `"123-456-7890"` | | Meta Ads | `ad_account_id` | `"act_123456789"` | | Amazon Ads | `profile_id` | `"1234567890"` | | TikTok Ads | `advertiser_id` | `"7012345678901234"` | | LinkedIn Ads | `account_id` | `"512345678"` | ### Managing your active set You can change which accounts are active from the Adspirer dashboard at [adspirer.ai/connections](https://adspirer.ai/connections). Add or remove accounts from your active set at any time. If you downgrade from a higher tier and end up over the new cap, Adspirer demotes excess accounts to inactive **automatically** — primary-set accounts kept first, then most-recently-synced. You won't lose history; the accounts are still connected and you can re-activate them after upgrading again. Teams that need more than 5 active accounts per platform — or multi-seat access pooled across planners — should [book a demo](https://www.adspirer.com/book-demo) so we can size a plan around your portfolio. ## For Agencies If you manage ads for multiple clients: 1. **Connect all client accounts** through OAuth (each client authorizes separately) 2. **Start each session** by confirming which client you're working with: ``` Show me all my connected ad accounts ``` 3. **Switch to the client** you want to manage: ``` Switch to the Google Ads account for [Client Name] ``` 4. **Run your workflow** — all tool calls target that client's account > [!TIP] > > Always verify the active account before creating campaigns. Running `get_connections_status` at the start of each session prevents accidentally modifying the wrong client's campaigns. > [!NOTE] > > **A playbook per client account.** The [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) is priced **per ad account** (\$39 one-time each) because it's generated from that account's own campaigns and history — which is exactly what you want when the accounts belong to different clients. Managing several is the case it's cheapest for: tick **every** eligible account in one checkout and **20% comes off the whole cart** (minimum two; a partial selection pays full price per kit). Keep one playbook per client project so the agent never carries one client's context into another's work. ## Cross-Account Reports Pull performance data from multiple accounts in one request: ``` Compare performance across all my Google Ads accounts for the last 30 days. Show spend, conversions, and CPA for each account. ``` ## FAQ > **Is there a limit to how many accounts I can connect?** > > No hard limit. Connect as many ad accounts as you manage. Tool call limits apply to your Adspirer plan, not to the number of connected accounts. > **Can different team members manage different accounts?** > > Yes, with Claude Team or Enterprise. Each team member authenticates with their own Adspirer account and connects their own set of ad accounts. See the [Claude setup guide](/docs/ai-clients/claude) for details. > **Does switching accounts cost a tool call?** > > No. Account switching is a session operation and does not count against your tool call limit. > **Do I need the Max plan for multi-account management?** > > Not anymore — **annual plans on Plus and Pro** also activate up to 5 accounts per platform simultaneously, the same as Max. Free and monthly Plus/Pro keep one active account per platform at a time. The Max plan is still the right choice for high-volume tool usage (3,000 calls/month) and stays at 5 active per platform on either billing interval. Use any 5-active tier when you regularly run cross-account audits, briefs, or bulk optimizations. > **What does `list_connected_accounts` return?** > > A list of all your active ad accounts across platforms — with platform name, account ID, account name, and status. It's primarily used by Max-tier sequential sub-agents to fan out work, but it's available on any plan. Costs zero tool calls and makes zero API calls (reads from the database). # Using Adspirer Across Multiple AI Clients Source: https://www.adspirer.com/docs/knowledge-base/multi-client Use the same Adspirer account with ChatGPT, Claude, Cursor, Codex, Windsurf, Perplexity, Manus, and more. One account, one limit, any AI client. Your Adspirer account works with every supported AI client. Connect once, use everywhere. All clients share the same MCP (Model Context Protocol — an open standard for connecting AI assistants to external tools) connection. ## One Account, Any Client | AI Client | Type | Best For | | - | - | - | | [ChatGPT](/docs/ai-clients/chatgpt) | Chat app | Marketers, non-technical users | | [Claude](/docs/ai-clients/claude) | Chat app | Best MCP integration, progress streaming | | [Claude Code](/docs/ai-clients/claude-code) | Terminal | Developers, automation, scripting | | [Gemini CLI](/docs/ai-clients/gemini-cli) | Terminal | Developers using Google's AI CLI | | [Cursor](/docs/ai-clients/cursor) | IDE | Developers who live in their editor | | [Grok Bot](/docs/ai-clients/grok) | Cloud bot | Scheduled reporting that arrives on its own | | [Codex](/docs/ai-clients/codex) | Autonomous agent | Scheduled tasks, daily monitoring | | [OpenClaw](/docs/ai-clients/openclaw) | CLI agent | Pre-configured advertising agent | | [Windsurf](/docs/ai-clients/windsurf) | IDE | Codeium users | | [Perplexity](/docs/ai-clients/perplexity) | Chat app + Agent | Search-powered research + ad management | | [Manus](/docs/ai-clients/manus) | Autonomous agent | Deep research, dashboards, scheduled briefs | All clients connect to the same MCP server (`mcp.adspirer.com/mcp`) and share your tool call quota. ## Key Differences ### ChatGPT vs Claude Both work well. Claude has deeper MCP integration (Anthropic created MCP) with progress streaming during long operations. ChatGPT may need more explicit tool mentions in prompts. ### Chat Apps vs Developer Tools **Chat apps** (ChatGPT, Claude, Perplexity) are conversational — you describe what you want in natural language. No configuration files. **Developer tools** (Claude Code, Cursor, Codex, OpenClaw, Windsurf) support **agent skills** — instruction files that teach the AI optimal advertising workflows. Skills enforce safety rules automatically and improve tool invocation accuracy. ### Interactive vs Autonomous **Interactive** (all except Codex): You ask, the AI responds. Real-time conversation. **Autonomous** (Codex): You define a task and schedule. The agent runs it without you being present — e.g., daily performance checks at 8 AM. ## Shared Tool Call Limit Your monthly tool call limit applies across **all** clients. If your Plus plan has 150 calls/month: * 50 calls from ChatGPT + 50 from Claude + 25 from Perplexity + 25 from Cursor = 150 total * Switching clients doesn't reset your limit Check usage from any client: ``` Check my Adspirer usage status ``` ## FAQ > **Do I need separate Adspirer accounts for each AI client?** > > No. One Adspirer account works across all clients. Your ad platform connections persist across all of them. > **How do shared tool calls work for a whole team?** > > The single-account model above applies to one user. Agencies and teams who need multi-seat access — where every planner has their own login and tool calls are pooled across the team — should [book a demo](https://www.adspirer.com/book-demo) so we can size a team plan. > **Can I use different AI clients for different tasks?** > > Yes, and this is recommended. Use Claude for quick ad-hoc queries, Cursor for deep analysis sessions, and Codex for scheduled daily monitoring. > **What if I switch AI clients mid-workflow?** > > Your ad platform connections persist. But workflow state (like "I was in the middle of creating a campaign") doesn't carry between clients. Start a new workflow in the new client. # Non-profit Discount on Adspirer Yearly Plans Source: https://www.adspirer.com/docs/knowledge-base/nonprofit-discount Registered non-profits, NGOs and charities get the first year of Adspirer Pro yearly for $849.15 or Max yearly for $1,900. Who qualifies, what to send, and how to use your code. If your organisation is a registered non-profit, NGO or charity, you can get a discount on the **first year** of a yearly plan. Ask in the support chat at [adspirer.ai](https://adspirer.ai) and you get a discount code for your account in a few minutes. ## The discount | Plan | First year | From the second year | | - | - | - | | Pro yearly | \*\*$849.15** (15% off $999) | \$999 a year | | Max yearly | \*\*$1,900** (5% off $2,000) | \$2,000 a year | > [!NOTE] > > **The discount is on your first payment only.** Your plan renews at the full yearly price one year later: $999 for Pro, $2,000 for Max. There is no non-profit discount on monthly plans, on Plus, or on the [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook). Everything else about the plan is the same as the regular yearly plan: the same yearly tool-call pool and the same number of active ad accounts. See [Pricing](/docs/knowledge-base/pricing) for what each plan includes. ## Who qualifies * Your organisation is a **registered non-profit, NGO or charity**, in any country. * **One discount per person and one per organisation.** Two people from the same organisation cannot each get one. * Your current subscription does not already have another discount on it. You confirm your organisation's status yourself. We record the details you give us with your discount. > [!NOTE] > > **Already on Pro yearly or Max yearly?** The discount applies to the first payment of a new yearly plan. Ask in the support chat and a teammate will look at your account with you. > [!TIP] > > **An agency, a large team, or many client accounts?** That is a different conversation. See [Enterprise](/docs/knowledge-base/enterprise) for plans sized to your accounts and team. ## What you need to send When you ask for the discount, have these ready: | Detail | Example | | - | - | | Your organisation's name | Save The Dogs Foundation | | Its website | savethedogs.org | | Its registration number | an EIN in the US, a charity number in the UK, a CNPJ in Brazil, or your country's equivalent | | The country it is registered in | United States | | One line, in your own words, confirming it is a registered non-profit | "We are a registered 501(c)(3) non-profit." | ## How to get your code **1. Ask for it** Sign in at [adspirer.ai](https://adspirer.ai), open the support chat at the bottom-right, and say that your organisation is a non-profit. You can also email **[support@adspirer.com](mailto:support@adspirer.com)** from the address on your Adspirer account. **2. Confirm the price** We tell you the exact price for the plan you want: the first year, and what it renews at. Say yes if it works for you. **3. Send your organisation's details** Send the five details above in one message. **4. Get your code** You receive a code that looks like `NONPROFIT-K7Q2ZP`, with the date it expires. **5. Use it at checkout** On the Home page at [adspirer.ai](https://adspirer.ai), choose **Pro yearly** or **Max yearly** (the plan the code is for), and enter the code in the promotion code box on the checkout page. The order summary shows the discounted first-year price before you pay. > [!WARNING] > > **Your code works only on the Adspirer account it was issued to, only once, and only for 14 days.** It does not work on a monthly plan or on the other yearly plan. If you lose it, ask in the support chat and you get the same code again. ## FAQ > **Can I get the non-profit discount on a monthly plan?** > > No. The discount is only on the first year of Pro yearly or Max yearly. > **Does my plan renew at the discounted price?** > > No. The discount covers your first payment. From the second year your plan renews at the full yearly price: $999 for Pro, $2,000 for Max. > **My code expired before I used it. What now?** > > Codes are valid for 14 days and there is one per person. Ask in the support chat or email [support@adspirer.com](mailto:support@adspirer.com), and a teammate will look at it with you. > **Can a colleague use my code?** > > No. The code is locked to the account it was issued to, and the discount is one per organisation. > **Can I combine it with another offer?** > > No. A subscription carries one discount at a time. # Google Ads vs Meta vs Amazon vs TikTok Compared Source: https://www.adspirer.com/docs/knowledge-base/platform-comparison Compare targeting, cost, best use cases, minimum budgets, and Adspirer tool counts across Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok. Which ad platform should you use? It depends on your audience, budget, and goals. ## Quick Comparison | | Google Ads | Meta Ads | Amazon Ads | ChatGPT Ads | LinkedIn Ads | TikTok Ads | | - | - | - | - | - | - | - | | **Best for** | Demand capture | Demand generation | Retail / product sales | Reach inside ChatGPT | B2B lead gen | Brand awareness | | **Targeting** | Keywords (search intent) | Interests, behaviors, demographics | Keywords, ASINs, products | Location + context hints | Job title, industry, seniority | Interests, behaviors | | **Audience intent** | High (actively searching) | Low-medium (browsing) | High (ready to buy) | Medium (in conversation) | Medium (professional context) | Low (entertainment) | | **Avg CPC (Cost Per Click — amount you pay each time someone clicks your ad)** | \$1-5 (varies by industry) | \$0.50-2 | \$0.50-3 (varies by category) | Varies (new format) | \$5-12 | \$0.50-2 | | **Min daily budget** | \$10 | \$5 | \$1 | \$1 | \$10 | \$20 | | **Creative format** | Text ads, responsive, [Display banners + video](/docs/ad-platforms/google-display-ads) | Image, video, carousel | Product ads, brand video, display | Chat card (headline + body + image) | Image, sponsored content | Video (9:16 vertical) | | **Adspirer tools** | 156 (Search, PMax, Shopping, App, Display, YouTube, Demand Gen) | 60 (incl. Advantage+ Catalog / DPA) | 61 (Sponsored Products, Brands, Display) | 31 (campaigns, ad groups, ads, conversions) | 55 (incl. video, campaign groups, forecasting) | 37 | | **Setup guide** | [Google Ads](/docs/ad-platforms/google-ads) | [Meta Ads](/docs/ad-platforms/meta-ads) | [Amazon Ads](/docs/ad-platforms/amazon-ads) | [ChatGPT Ads](/docs/ad-platforms/chatgpt-ads) | [LinkedIn Ads](/docs/ad-platforms/linkedin-ads) | [TikTok Ads](/docs/ad-platforms/tiktok-ads) | ## When to Use Each Platform ### Google Ads — Demand Capture Use Google when people are **actively searching** for what you sell. Someone typing "project management software for remote teams" has high purchase intent. **Best for:** SaaS, professional services, e-commerce with search demand, local businesses **Strengths:** Highest intent traffic, keyword targeting, Performance Max for broad reach, [Display](/docs/ad-platforms/google-display-ads) + [YouTube](/docs/ad-platforms/youtube-ads) for retargeting and visual brand reach **Weakness:** Expensive for competitive keywords (\$5-50+ per click in some industries) ### Meta Ads — Demand Generation Use Meta when you need to **reach people who don't know you exist**. Visual products and impulse purchases perform well. **Best for:** E-commerce, D2C brands, app installs, local businesses, event promotion **Strengths:** Cheapest clicks, best visual targeting, massive reach (3B+ users), retargeting **Weakness:** Lower intent — people are browsing, not buying ### LinkedIn Ads — B2B Lead Generation Use LinkedIn when your buyers are **business decision-makers**. The only platform where you can target by job title, company size, and seniority. **Best for:** B2B SaaS, enterprise sales, recruiting, professional services, events **Strengths:** Unmatched B2B targeting, professional context, lead gen forms **Weakness:** Most expensive CPC (\$5-12+), smaller audience pool ### TikTok Ads — Brand Awareness Use TikTok for **video-first campaigns** targeting younger demographics. Native-feeling content outperforms polished ads. **Best for:** Consumer brands, fashion, food, entertainment, app installs **Strengths:** Lowest CPMs, high engagement, viral potential **Weakness:** Video required, younger skew, limited targeting precision ### Amazon Ads — Retail Purchase Intent Use Amazon when you sell physical products on Amazon and want to reach shoppers **at the moment of purchase**. Ads appear in search results and on product pages, measured by ACOS (Advertising Cost of Sales — ad spend divided by sales generated) and ROAS. **Best for:** Amazon sellers and vendors, e-commerce, product launches on Amazon **Strengths:** Highest purchase intent (shoppers already buying), keyword + ASIN targeting, Sponsored Products / Brands / Display **Weakness:** Requires products listed on Amazon; Sponsored Brands needs Brand Registry ### ChatGPT Ads — Reach People Inside ChatGPT Use ChatGPT Ads to place pay-per-click "chat card" ads **inside ChatGPT responses** — a new surface for reaching people while they're in a conversation. **Best for:** Brands experimenting with conversational placements, simple single-card creative **Strengths:** A brand-new, fast-growing surface; simple creative (headline + body + image); launched conversationally and paused by default **Weakness:** New format with evolving targeting; ads pass OpenAI review (some categories, e.g. third-party AI services, are disallowed) ## Multi-Platform Strategy Most advertisers run 2-3 platforms. Common combinations: | Strategy | Platforms | Why | | - | - | - | | **B2B SaaS** | Google + LinkedIn | Capture search demand + reach decision-makers | | **E-commerce** | Google + Meta | Capture search demand + generate new demand | | **Retail / Amazon seller** | Google + Meta + Amazon | Search capture + discovery + purchase intent on Amazon | | **Consumer app** | Meta + TikTok | Visual discovery + viral reach | | **Full funnel** | Google + Meta + LinkedIn | Search capture + visual discovery + B2B targeting | Adspirer manages all platforms from a single conversation. Ask your AI assistant: ``` Pull my ad performance for the last 30 days across all platforms. Show spend, conversions, CPA, and ROAS for each. ``` ## FAQ > **Can I manage all platforms from one conversation?** > > Yes. Adspirer supports multi-platform management. Pull Google data, create a Meta campaign, and audit LinkedIn — all in the same chat session. > **Should I start with one platform or multiple?** > > Start with one. Pick the platform that matches your audience (Google for search intent, Meta for visual discovery, LinkedIn for B2B). Once you've optimized one, expand to a second for full-funnel coverage. > **Does Adspirer charge per platform?** > > No. Pricing is based on total tool calls, not platforms. A Google Ads query and a Meta Ads query each count as 1 call. See [pricing details](/docs/knowledge-base/pricing). Agencies running all six platforms across many client accounts can [book a demo](https://www.adspirer.com/book-demo) to size a plan with pooled tool calls. # Adspirer Pricing & Tool Call Quotas Explained Source: https://www.adspirer.com/docs/knowledge-base/pricing How Adspirer pricing works. Tool call limits by plan, typical usage per platform, cost examples for campaign creation, and upgrade guidance. Adspirer pricing is based on **tool calls**, not ad spend. A tool call is a **task** your AI assistant performs for you — anything from a one-line question to a full multi-platform campaign launch. ## What's a Tool Call? Think of a tool call as a **task**, on a complexity spectrum. The same plan covers tasks at every level — you just use more calls when the task is bigger. | Task Type | Tool Calls | What It Looks Like | | - | :-: | - | | **Simple** | 1 | "What's my Google Ads ROAS this month?" · "Pull last week's Meta performance" · "Research keywords for 'project management software'" | | **Medium** | 8–12 | Launch a single Google Search or Meta campaign — research keywords, write ad copy, validate assets, create paused, summarize for review | | **Complex** | 25–40+ | "Take my Q2 media plan and launch paused campaigns across Google, Meta, and LinkedIn" — one prompt, multi-platform research + asset validation + creation per platform + cross-platform reconciliation | > [!TIP] > > **Why tasks vary so much:** A single sentence to your AI can trigger anywhere from one tool call to forty, depending on what you ask for. The Pro plan (600 calls/month) is sized to handle real production work — typically 50–60 medium tasks or a smaller number of complex multi-platform launches. ## Plans | Plan | Tool Calls/Month | Monthly | Annual | Best For | | - | - | - | - | - | | Free Forever | 15 | \$0 | — | Testing and evaluation | | Plus | 150 + overage | \$49/mo | \$485/yr | Individual advertisers, small accounts | | Pro | 600 | \$99/mo | \$999/yr | Individual marketers, 1 ad account | | Max | 3,000 | \$199/mo | \$2,000/yr | Multi-platform, multi-account, sequential sub-agents | > [!NOTE] > > **Plus plan includes pay-as-you-go overage.** After your 150 included calls, you can keep using tools at $0.50 per additional call, capped at $50/month in overage charges. Overage billing is auto-enabled for Plus subscribers — you can disable it anytime from your billing page. ## Add-ons (One-Time Purchases) These are **one-time charges**, not subscriptions. Nothing about them recurs, and they don't change your plan price. | Add-on | Price | Billing | Covers | Included with | | - | - | - | - | - | | [**Prompt Engineering Playbook**](/docs/agent-skills/prompt-engineering-playbook) | **\$39** | **One time — nothing recurs** | **One ad account** | One free on annual plans | The [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) generates a custom agent skill, an account dossier, a prompt book, and paste-ready agent instructions from **your** ad account's real campaigns and history. You download the files and install them in Claude, ChatGPT, Claude Code, Cowork, Cursor, or Codex. They're yours to keep, and rebuilding them against fresh data later is free and unlimited. It's priced **per ad account** because it's generated from that account's own data — two accounts means two playbooks. Buying several is one checkout and one charge, and **selecting every eligible account takes 20% off the whole cart** (minimum two accounts; a partial selection pays full price per kit). > [!WARNING] > > \*\*A $39 line on your invoice is not a plan increase.** The playbook can be added during plan checkout, in which case it lands on the **same invoice** as your subscription as a separate one-time line reading **"One-time Agent Setup — 1 Ad Account"**. That month's total is higher; your recurring plan price is unchanged, and the $39 will not appear again next month. Because each playbook is generated on demand from your account, it's non-refundable once the build has completed and the files are available to download. Failed builds and accounts you can't access are a different matter — [contact support](/docs/knowledge-base/support). ## Active Accounts Per Platform The number of ad accounts you can have **active** (used by the agent) on each platform depends on your plan and billing interval. You can connect unlimited accounts on any plan — this is about how many can be active simultaneously. | Plan | Monthly | Annual | | - | :-: | :-: | | Free | 1 | 1 | | Plus | 1 | **5** | | Pro | 1 | **5** | | Max | **5** | 5 | The cap is **per platform** — a Plus annual customer can activate up to 5 Google Ads accounts **and** 5 Meta accounts **and** 5 LinkedIn accounts **and** 5 TikTok accounts at the same time. See [Multi-Account](/docs/knowledge-base/multi-account) for how the agent fans out tool calls across active accounts. > [!TIP] > > If you downgrade and end up over the cap, Adspirer demotes excess accounts to inactive automatically (most-recently-synced kept; primary-set accounts kept first). Reconnecting or activating different accounts is a one-click operation in the [Manage Accounts](https://adspirer.ai/connections) modal. See [full pricing details](https://www.adspirer.com/pricing). > [!NOTE] > > **Managing a team or multiple clients?** [Book a demo](https://www.adspirer.com/book-demo) and we'll size a plan around your account count and team. ## Annual Plans — Pooled Tool Call Quota Annual subscribers get a single yearly pool instead of per-month caps. There are no monthly resets — use your calls whenever you need them. > [!TIP] > > **The annual perk:** Monthly plans reset every 30 days — if you hit your cap mid-month, tools stop. Annual plans give you one large pool for the whole year. Spend calls heavily during a campaign launch, coast during slow periods — no monthly wall to hit. | Plan | Annual Price | Annual Pool | Monthly Equivalent | | - | - | - | - | | Plus | \$485/year | 1,800 calls | \~150/month | | Pro | \$999/year | 7,200 calls | \~600/month | | Max | \$2,000/year | 50,000 calls | \~4,167/month | > [!NOTE] > > **How the annual pool works:** > > * Your pool renews on your subscription anniversary date (not monthly). > * Unused calls do **not** roll over to the next year. > * The quota counter in your account shows calls remaining for the current year. > * Max annual (50,000) is intentionally higher than 12× monthly (36,000) — the annual plan is the upgrade incentive for high-volume periods. > * **Plus and Pro yearly have overage billing**, on by default: when your yearly pool is used up, your plan is billed again at the same yearly price and a new, larger pool starts. See [Overage billing on yearly plans](#overage-billing-on-yearly-plans-plus-and-pro) below. > * **Max yearly has no overage billing.** Its 50,000-call pool is the total for the year. ## Performance Data & Historical Lookback How up-to-date your campaign data is depends on your plan. ### Free Plan — One-Time Data Sync When you first connect an ad account on the **Free plan**, Adspirer pulls a one-time snapshot of your last **90 days** of campaign performance. That snapshot is used for analysis, keyword research, and wasted-spend detection. **The data is not refreshed after signup.** If you return a month later, your performance data will be a month stale. Tools like `get_campaign_performance` and `analyze_wasted_spend` will reflect the state of your account at the time you signed up, not today. To work with current data, you need to upgrade to **Plus or above**. ### Plus, Pro & Max — Ongoing Background Sync Paid plans run regular background metric collection — Adspirer syncs campaign structures, keywords, performance metrics, and budget data from your connected ad accounts automatically. When you ask "what's my ROAS this week?" you get current data, not a stale snapshot. Sync frequency varies by platform: | Platform | Sync Frequency | Notes | | - | - | - | | **Meta Ads** | Daily | | | **LinkedIn Ads** | Daily | | | **TikTok Ads** | Daily | | | **Google Ads** | 3× per week | Google Ads API rate limits and reliability constraints prevent daily syncing | | Plan | Data Sync | Historical Lookback | | - | - | - | | Free | One-time at signup | 90 days (at signup) | | Plus | Regular background sync (see above) | 90 days rolling | | Pro | Regular background sync (see above) | 90 days rolling | | Max | Regular background sync (see above) | 90 days rolling | > [!NOTE] > > If you're on the Free plan and your data feels outdated, upgrading to Plus immediately triggers a fresh sync. You'll have current data within minutes of upgrading. > [!NOTE] > > **Google Ads sync cadence:** Google Ads background collection runs 3 times per week rather than daily. This is due to Google Ads API rate limits and reliability constraints that affect background collection jobs. For on-demand live data, use tools like `get_campaign_performance` directly — those always pull fresh data from the API in real time, regardless of sync schedule. ## Which Plan Do I Need? Use this guide based on your situation: | Your Situation | Recommended Plan | | - | - | | Testing Adspirer, exploring tools | Free 15 calls/mo | | Solo marketer, 1 platform, under \$1K/mo ad spend, 1-5 campaigns | Plus \$49/mo | | 2+ platforms, $1K-$10K/mo spend, small team (2-5), or 6-20 campaigns/mo | Pro \$99/mo | | 3+ platforms with active spend, or $10K-$50K/mo spend with any other factor | Max \$199/mo | | \$50K+/mo ad spend, 10+ team members, or agency with multiple clients | Max \$199/mo — [book a demo](https://www.adspirer.com/book-demo) to size a team plan | > [!TIP] > > The more platforms you manage and the more campaigns you run, the more tool calls you'll use. Multi-platform users burn through calls faster because each platform query is a separate tool call. ## How Tool Calls Work Each tool invocation counts as 1 call, regardless of: * Which platform (Google, Meta, LinkedIn, TikTok) * Which AI client (ChatGPT, Claude, Perplexity, Cursor, etc.) * How much data is returned * How long the operation takes ### Typical Usage by Task | Task | Tool Calls | Complexity | Notes | | - | - | :-: | - | | Check connected platforms | 1 | Simple | `get_connections_status` | | Pull campaign performance | 1 | Simple | Per platform | | Keyword research | 1 | Simple | Returns full keyword list with CPC data | | Audit conversion tracking | 1 | Simple | Checks pixel health, CAPI, attribution across platforms | | Wasted spend analysis | 1–2 | Simple | Analysis + optional optimization | | Budget optimization | 2–3 | Simple | Performance pull + ROAS (Return on Ad Spend)/CPA (Cost Per Acquisition) recommendation | | Cross-platform performance report | 4–5 | Simple | 1 call per connected platform + analysis | | Create Google Search campaign | 8–12 | Medium | Research + ad copy + assets + validate + create + summary | | Create Meta image/video campaign | 8–12 | Medium | Targeting + type + assets + validate + create + summary | | Create LinkedIn campaign | 8–12 | Medium | Org + targeting + ad copy + validate + create + summary | | Create TikTok campaign | 6–10 | Medium | Targeting + assets + validate + create + summary | | Multi-platform launch from a media plan | 25–40+ | Complex | One prompt builds paused campaigns across 2–4 platforms in a single run | ### Full Workflow Cost Examples Most users don't run individual tools — they run workflows. Here's what typical end-to-end workflows cost: | Workflow | Total Calls | What Happens | | - | - | - | | Create & launch a Google Search campaign | 8–12 | Business profile + keyword research + ad copy + validate + create + summary | | Create & launch a Meta image campaign | 8–12 | Select type + targeting + validate assets + create + summary | | Multi-platform launch from a single media plan | 25–40+ | One prompt → research + assets + paused campaigns across Google, Meta, and LinkedIn | | Create campaign + monitor it for a month | 14–18 | Creation (8–12) + 4 weekly performance checks (4) + 1 optimization review (2) | | Weekly cross-platform health check | 4–6 | 1 call per connected platform + optional wasted spend analysis | | Full account audit + optimization plan | 3–5 | Audit (1) + wasted spend (1) + budget optimization (2–3) | | Research + create + optimize a campaign over 30 days | 20–30 | Research (2) + create (8–12) + 4 weekly checks (4) + 2 optimizations (4–6) | > [!NOTE] > > **Can I create campaigns on the free plan?** Yes — **one campaign**, if you know exactly what you want. A medium campaign launch uses 8–12 tool calls, so the free tier (15 calls) is sized to verify Adspirer connects to your AI client and ad accounts and to run **one** end-to-end campaign as a taste test. For ongoing production work, plan on Plus or above. ### Monthly Usage Examples | Scenario | Estimated Calls | Recommended Plan | | - | - | - | | Setup verification + 1 trial campaign | 12–15/mo | Free | | Weekly check (1 platform) + 1 campaign/month | 12–18/mo | Free or Plus | | Daily monitoring (2 platforms) + 2 campaigns/mo | 40–80/mo | Plus | | Active multi-platform: 4–6 campaigns + weekly audits | 100–200/mo | Plus or Pro | | Heavy usage: daily monitoring, frequent launches, audits | 200–600/mo | Pro | | Agency, multi-client, high-volume | 600+/mo | Max | ## How Adspirer Pro Compares to Hiring The Pro plan (600 tool calls/month for \$99) delivers roughly **120 hours of equivalent specialist work** per month — the same workload an in-house paid media specialist or contracted PPC freelancer would cover. | Option | Monthly Cost | Hourly Equivalent | Coverage | | - | :-: | :-: | - | | **In-house Paid Media Specialist** | \$7,500/mo | \~\$62/hr | Full ownership, full cost | | **Contracted Specialist (Upwork, \~25 hrs)** | \$1,500/mo | \$60/hr | \~20% of the work needed | | **Adspirer Pro** | **\$99/mo** | **\$0.83/hr equivalent** | Full workload via your AI assistant | **The math:** * Adspirer Pro is **\~76× cheaper than building it in-house** * And **\~15× cheaper than even a part-time Upwork contractor** (who only covers \~20% of the workload) * **Annual savings vs in-house:** \$88,812 * **Annual savings vs Upwork contractor:** \$16,812 * **Total Adspirer Pro spend per year:** \$1,188 Reference scenario: a benchmark account spending \~\$10K/month on Google Ads with 2–3 active campaigns. See the [full breakdown in our research](https://www.adspirer.com/blog/research/cost-of-paid-media.html). > [!TIP] > > **Why this comparison matters:** Pricing pages typically frame "$99/mo" as a cost. The real frame is what $99/mo *replaces* — the difference between Adspirer Pro and the cheapest alternative that does the same workload is over \$1,400/month. ## What Counts as a Tool Call **Counts:** Any tool invocation through MCP — `get_campaign_performance`, `research_keywords`, `create_search_campaign`, etc. **Does NOT count:** * Connecting your AI client to Adspirer * OAuth authentication / login * Viewing your account status * AI assistant thinking / reasoning between tool calls * Failed tool calls due to authentication errors ## Checking Your Usage Ask your AI assistant: ``` Check my Adspirer usage status ``` This returns your current plan, calls used this month, and calls remaining. The **Usage & Billing** page at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=usage) shows the same numbers, plus a **Connection Health** card: whether your AI assistant is connected via MCP and, per ad account, whether the OAuth link is healthy or needs reconnecting — with a **Test now** button that re-checks live. ## Overage billing (Plus plan) Plus subscribers get **pay-as-you-go overage** after their 150 included tool calls: | | Details | | - | - | | **Rate** | \$0.50 per additional tool call | | **Monthly cap** | \$50 (100 extra calls max) | | **Auto-enabled** | Yes — active by default for all Plus subscribers | | **Disable anytime** | Toggle off from your billing page at [adspirer.ai](https://adspirer.ai) | ### How it works 1. Your first 150 tool calls each month are included in your \$49 Plus subscription 2. After 150 calls, each additional call costs \$0.50 — billed through Stripe at the end of your billing cycle 3. Overage charges are capped at $50/month (100 extra calls), so your maximum monthly bill is $99 4. If you hit the \$50 cap, tools are paused until your next billing cycle — or you can upgrade to Pro ### Disabling overage If you prefer the previous behavior (tools stop at 150 calls), toggle overage off from your billing page. When disabled, you'll see an upgrade prompt at 150 calls instead of being billed per call. > [!TIP] > > Per-call overage applies **only to Plus monthly subscribers** ($0.50/call after 150, capped at an additional $50/month). Pro and Max monthly subscribers hit a hard cap — no overage charges. **Plus and Pro yearly** have a different kind of overage billing, described next. **Max yearly** has none. ## Overage billing on yearly plans (Plus and Pro) Plus yearly and Pro yearly have **overage billing**, switched on by default. There is no per-call rate and nothing to upgrade. | | Plus yearly | Pro yearly | | - | - | - | | **Yearly pool** | 1,800 calls | 7,200 calls | | **When the pool is used up** | Your plan is billed again at **\$485** | Your plan is billed again at **\$999** | | **Your new pool** | 7,200 calls | 50,000 calls | ### How it works 1. You get an email when you have used **75%** of your yearly pool, another at **90%**, and one when you **reach your limit**. 2. The charge happens **48 hours after the "you've reached your limit" email**, so you have time to switch overage billing off first. 3. Your plan is billed again at the same yearly price, a new year starts from that day, and your new pool is the larger one in the table above. ### Switching it off, or lifting your limit early * The **Overage billing** switch on the billing card at [adspirer.ai](https://adspirer.ai) turns it off and on. Each change asks you to confirm first, and switching it on never charges you by itself. * With overage billing off, nothing extra is charged: your tool calls stop at your yearly limit until your plan renews. * From 75% of your pool used, **Lift my limit now** on the same card starts the new pool right away. It shows the amount and asks you to confirm before your card is charged, and any calls you had left move into the new pool. * Scheduling a cancellation switches overage billing off, so a plan you are cancelling is never charged for overage. > [!NOTE] > > **Max yearly is not included.** Its 50,000-call pool is the total for the year. ## Upgrading If you hit your limit mid-month, upgrade takes effect immediately and resets your counter. Visit [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account) to manage your plan. The **Manage Subscription** link on the Current Plan card opens the Stripe billing portal, where you can update payment details, switch between annual and monthly billing, or cancel. ## FAQ > **I was charged \$39 on top of my plan — is that a new subscription?** > > No. That's the [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook), a **one-time** add-on for one ad account. It appears on the same invoice as your plan as a separate line called **"One-time Agent Setup — 1 Ad Account"**, which is why that month's total was higher. Your recurring plan price didn't change and the \$39 won't appear again. > **Do unused calls roll over?** > > **Monthly plans:** No. Tool call limits reset on your monthly billing date. Unused calls do not carry over. > > **Annual plans:** No. Your yearly pool renews on your subscription anniversary date. Unused calls at year-end do not roll over to the next year. > **Can I pay per call instead of monthly?** > > Plus monthly subscribers get per-call overage billing after their 150 included calls — $0.50 per additional call, capped at $50/month. Pro and Max plans have no per-call billing. Plus and Pro yearly have [overage billing](#overage-billing-on-yearly-plans-plus-and-pro) instead: when the yearly pool is used up, the plan is billed again at the same yearly price with a larger pool. > **What happens when my yearly pool runs out?** > > **Plus and Pro yearly:** overage billing is on by default. You get emails at 75%, 90% and when you reach your limit, and 48 hours after that last email your plan is billed again at the same yearly price ($485 or $999) with a new pool of 7,200 or 50,000 calls. You can switch it off from the billing card at [adspirer.ai](https://adspirer.ai). [Details](#overage-billing-on-yearly-plans-plus-and-pro). > > **Max yearly:** no overage billing. Tools stop at 50,000 calls until your plan renews. > **Do you offer a discount for non-profits?** > > Yes: registered non-profits, NGOs and charities get a discount on the first year of Pro yearly or Max yearly. See [Non-profit discount](/docs/knowledge-base/nonprofit-discount). > **Does the same Adspirer account work across all AI clients?** > > Yes. Your tool call limit is shared across ChatGPT, Claude, Perplexity, Cursor, and all other clients. One account, one limit. > **Can I create campaigns on the free plan?** > > Yes — **one campaign**, if you know exactly what you want. A typical campaign launch (Google Search, Meta image/video, or LinkedIn) uses 8–12 tool calls when you include keyword research, ad copy, asset validation, and creation. The free tier (15 calls/month) is sized to **verify Adspirer connects to your AI client and ad accounts** and to run one end-to-end campaign as a taste test — not for ongoing production work. For active campaign management, plan on Plus or above. > **Do I need a paid ChatGPT or Claude subscription to use Adspirer?** > > **It depends on your AI client.** Custom MCP connectors require: > > * **Claude:** Pro, Max, Team, or Enterprise (connectors aren't available on the Claude free tier) > * **ChatGPT:** Plus or Pro (connectors aren't available on the ChatGPT free tier) > > These are *AI platform* requirements, not Adspirer's. **Free alternatives:** [Claude Code](/docs/ai-clients/claude-code), [Cursor](/docs/ai-clients/cursor), [Codex](/docs/ai-clients/codex), [Windsurf](/docs/ai-clients/windsurf), [OpenClaw](/docs/ai-clients/openclaw), and [Gemini CLI](/docs/ai-clients/gemini-cli) connect to Adspirer through their own MCP support — no paid subscription to Claude or ChatGPT required. > **What happens if I run out of tool calls mid-month?** > > You have three options: > > 1. **Upgrade to a higher tier** — takes effect immediately and resets your counter. Go to [adspirer.ai](https://adspirer.ai) to upgrade. > 2. **Wait for your monthly reset** — your quota resets on your billing date. Tools are paused until then. > 3. **Switch to an annual plan** — instead of a monthly cap that resets every 30 days, annual subscribers get a single large pool for the whole year. No monthly walls. Use calls when campaigns are active, coast when they're not. > > | Annual Plan | Yearly Pool | vs. Monthly | > | - | :-: | :-: | > | Plus | 1,800 calls | same price, \~25% more calls | > | Pro | 7,200 calls | same price, same calls | > | Max | 50,000 calls | same price, **38% more calls** | > > Plan-specific behavior when you hit a monthly cap: > > * **Free (15 calls):** Upgrade prompt — no automatic continuation. > * **Plus (150 calls):** Overage billing enabled by default — you keep going at $0.50/call, capped at $50/month. If you've hit the cap or disabled overage, you'll see an upgrade prompt. > * **Pro / Max:** Tools pause until next billing cycle — or upgrade to continue. > > For urgent needs, email [abhi@adspirer.com](mailto:abhi@adspirer.com). > **How do I know which plan I need?** > > It depends on how many platforms you use, how many campaigns you create, and how often you check performance. See the "Which Plan Do I Need?" section above. You can also try our [pricing calculator](https://www.adspirer.com/pricing). # Referral Program: Give 25 Tool Calls, Get 50 Source: https://www.adspirer.com/docs/knowledge-base/referrals How the Adspirer referral program works. Your referral link, what each side receives and when, how to tell a referral is on track, limits, and the exact situations where a referral does not earn anything. Invite someone to Adspirer. **They get 25 bonus tool calls the moment they sign up. You get 50 once they actually start using Adspirer.** Both rewards are ordinary tool calls added on top of your plan's monthly allowance. They are not credits, discounts or cash. > [!NOTE] > > **The single most important thing on this page:** the two rewards unlock at *different* moments. Your friend's 25 calls arrive **instantly at signup**. Your 50 calls arrive **only once they actually use Adspirer for a real marketing task**. Seeing your friend receive their 25 does **not** mean your 50 is due yet. ## The two rewards | | Who | How many | When it arrives | | - | - | - | - | | **The gift** | The person you invite | **25 tool calls** | Immediately when they create their account through your link | | **The reward** | You, the referrer | **50 tool calls** | After they run their **first real marketing task** in Adspirer | A new user on the Free plan starts with 15 tool calls. With your link they start with **15 + 25 = 40**, with no card required. Reward amounts are set centrally and can change. The numbers above are current. Your referral card in the app always shows the live figures. ## How it works, step by step **1. Find your referral link** Open [adspirer.ai](https://adspirer.ai) and look for the **"Give 25 tool calls, get 50"** card. Click it to open the share window. Your link looks like `https://adspirer.ai/r/R5XX8HJ`, where `R5XX8HJ` is your personal referral code. You can also ask your AI assistant. Say **"show me my referral link"** in Claude or ChatGPT and Adspirer will return it. **2. Share it** Use **Copy message** to copy a ready-to-paste invite (the pitch *and* your link together), or send email invites directly from the share window. See the examples below. **3. They sign up through your link** Your code applies automatically. Their 25 bonus calls are added right away, so their meter reads 40 on their very first visit. At this point your referral card shows **"1 signed up · your 50 calls land once they start using Adspirer."** **4. They use Adspirer for something real** Any genuine marketing task counts: *"show me last week's spend"*, *"audit my Google Ads account"*, *"build a campaign for my new product"*. **5. You get your 50 calls** Usually within about 15 minutes. **You get an email titled "You just earned 50 bonus tool calls"** with a link straight to your balance. Nothing to claim, nothing to check. ## Ways to share, with examples ### Email a colleague directly The share window has an email field. Type their address and send. We send the invite from Adspirer on your behalf, with your name in it and your code already applied. > **Subject:** Abhi gave you 25 free tool calls on Adspirer > > **Abhi** is running their performance marketing with AI agents, and wants you to try it — here's **25 free tool calls** on them. > > \[Claim 25 free tool calls] > > Sign up, connect an ad account, and start asking for real work. Your 25 bonus calls are added the moment you sign up — that's 40 to start with, no card needed. **This one has a bonus:** if they later sign up with that same email address without ever clicking the link, we still match them back to you. Email invites are the only share method that works even when the link is never clicked. You can send **5 invites per day**, up to **50 in total**, and up to **5 addresses at once**. ### Paste it into Slack, WhatsApp or a DM Click **Copy message**. You get the pitch and your link together, ready to paste: > I'm using AI agents to run my performance marketing 🤖 Adspirer builds and optimises my campaigns across Google, Meta, TikTok and LinkedIn, inside Claude/ChatGPT. Here's 25 free tool calls to try it 👉 [https://adspirer.ai/r/R5XX8HJ](https://adspirer.ai/r/R5XX8HJ) ### Post it publicly on LinkedIn or X This works exactly the same way, and there is no limit on how many people can use one link. The daily cap applies only to **emails we send for you**, never to your link. A LinkedIn post might read: > I've started running my performance marketing with AI agents. > > Adspirer works inside Claude and ChatGPT and handles what I used to do by hand across four ad platforms — building campaigns, catching overspend, doubling down on what's working. > > If you run ads, here's 25 free tool calls to try it 👇 > [https://adspirer.ai/r/R5XX8HJ](https://adspirer.ai/r/R5XX8HJ) **Strangers count.** If ten people you have never met click that post, sign up and each start using Adspirer, you earn 50 calls for each of them, up to the monthly and lifetime caps below. You do not need to know the person. > [!TIP] > > Posting publicly is usually the highest-volume channel, but email invites convert best because they are personal and they survive the recipient never clicking. Most people do both. ## How to tell your reward is on track Your referral card is the single source of truth. It moves through these states: | What the card says | What it means | What to do | | - | - | - | | **"No one yet"** | Nobody has signed up through your link | Share it | | **"1 signed up · your 50 calls land once they start using Adspirer"** | They created an account but have not used Adspirer yet | Nothing. We email you when it lands | | **"1 signed up · 1 activated"** | They started using Adspirer and you were paid | Nothing, the calls are in your balance | | **"50 bonus calls ready"** | You have bonus calls available to spend | Use them | | **"50 calls unlock when you run your first campaign task"** | You earned a reward but have not used Adspirer yourself yet | Run any real task and they unlock | **You never need to monitor anyone.** The email is automatic and it is the signal to trust. If it has not arrived and the card still shows someone yet to start, the referral is working correctly and is simply not finished. ### How the person you invited knows They do not need to do anything or claim anything. Their bonus is already in their account. Their usage meter reads **40** instead of 15 from their first visit, and the calls are spent automatically before their normal allowance runs out. ## Limits | Limit | Value | | - | - | | Rewarded referrals per month | 5 | | Rewarded referrals lifetime | 20 | | Bonus calls earned per month | 500 | | Email invites per day | 5 | | Email invites lifetime | 50 | | Bonus calls expire after | 180 days | There is **no cap on link clicks or signups** — the caps apply to how many referrals we pay out on. Before the referral card appears at all, you need to have used Adspirer at least once yourself. To send **email** invites you need to have run a few tasks. Your link works from the moment the card appears. ## When a referral does not earn anything This is the honest list. Most "my referral did not work" reports are one of the first three. > **They signed up but have not used Adspirer yet** > > **By far the most common.** Their 25 calls arrive at signup, which makes it look like they are up and running. They are not. Your 50 needs them to actually *use* the product for a real marketing task. > > There is nothing for you to do and nobody to chase. If and when they get started, your reward follows automatically within about 15 minutes and we email you. > **They signed up without using your link** > > If someone types adspirer.ai directly, or arrives from a search, there is nothing connecting them to you. We cannot attach a referral after the fact. > > The exception is email: if you sent them an invite from the share window, we match on their email address even if they never clicked. > **They already had an Adspirer account** > > The program rewards **new** users only. An existing account cannot be referred, no matter which link they click. If you try to email an invite to an address that already has an account, the share window tells you immediately. > **You have not used Adspirer yourself yet** > > If you earn a reward before you have used Adspirer, the calls are **waiting, not lost**. The card shows "50 calls unlock when you run your first campaign task." Run any real task and they become spendable straight away. > **Both accounts look like the same person** > > Referring yourself does not work. A second account of your own is not a new customer, and the program does not pay for it. > > Where a referral clearly looks like the same person or business on both sides, the **referrer's** reward is not issued. That decision is automatic and immediate, so there is nothing to wait for. > > Two things this never does: > > * **It never affects the person who signed up.** Their account works normally and they keep their 25 bonus calls. They did not choose who invited them. > * **It never triggers on one weak similarity.** Sharing an office network with someone you refer, or a surname with a family member, is not enough on its own. It takes clear, combined evidence. > > If you believe a genuine referral of yours was not credited, ask us through the chat assistant at [adspirer.ai](https://adspirer.ai) or email [support@adspirer.com](mailto:support@adspirer.com). We can see exactly why and put it right if we got it wrong. > **You have hit a cap** > > Once you reach 5 rewarded referrals in a month, 20 in total, or 500 bonus calls in a month, further referrals stop earning until the window resets. Signups still get their 25 calls. > **Your bonus calls are paused after cancelling a paid plan** > > Bonus calls are yours, but they are not spendable while a former paying customer is not on a paid plan. They are **dormant, not deleted** — resubscribe and they come back, subject to the usual 180-day expiry. > > This does not affect free users who never subscribed. If you have always been on the Free plan, your bonus calls are spendable normally. ## Frequently asked questions > **Does my link expire?** > > No. Your link and code are permanent and never change. > **How many people can use my link?** > > Unlimited. The link itself has no cap. Only the *rewards* are capped: 5 paid referrals per month and 20 in total. > **Do they need a credit card?** > > No. They sign up on the Free plan and their 25 bonus calls are added immediately. No card, no trial. > **Do I have to be on a paid plan to refer people?** > > No. Free users can refer and earn. You only need to have used Adspirer yourself before the card appears, and to have run a few tasks before you can send email invites. > **Do I earn more if they upgrade to a paid plan?** > > Not today. The reward is tied to them *using* the product, not to them paying. That may change. > **How long do bonus calls last?** > > 180 days from the day they are granted. They are spent automatically alongside your normal monthly allowance. > **Do bonus calls stack with my plan?** > > Yes. They are added on top of your plan's limit, not instead of it. On Free with 50 bonus calls, your effective limit is 15 + 50 = 65 for that period. > **Can I refer someone at my own company?** > > Yes, colleagues count. Be aware that people on the same office network sometimes get paused for review — that is a delay, not a rejection. > **I referred someone weeks ago and nothing happened.** > > Check your referral card. If it says they are yet to start, they signed up but never used Adspirer. If it shows nothing at all, they did not sign up through your link. Both are covered above. > **Where do I see how many calls I have earned?** > > The referral card shows a running total against your ceiling, for example "150 of 1,000 tool calls earned", plus your current spendable bonus balance. ## Still stuck? Use the chat assistant at [adspirer.ai](https://adspirer.ai), or email [support@adspirer.com](mailto:support@adspirer.com). Include the email address of the person you referred and roughly when they signed up, and we can tell you exactly which step it is sitting at. # Adspirer Security: OAuth, Encryption & Data Privacy Source: https://www.adspirer.com/docs/knowledge-base/security How Adspirer protects your ad accounts: OAuth 2.1 with PKCE, API key auth, no password storage, encrypted tokens, and revocable access. > [!NOTE] > > Adspirer never sees your ad platform passwords. All authentication uses OAuth 2.1 with PKCE (Proof Key for Code Exchange — prevents authorization code interception attacks) — the same standard used by banking apps. ## Authentication: OAuth 2.1 with PKCE When you connect an ad platform (Google Ads, Meta, LinkedIn, TikTok), Adspirer uses **OAuth 2.1 with PKCE** — the same standard used by banking apps and enterprise software. ### What This Means * **Your passwords stay with Google/Meta/Amazon/LinkedIn/TikTok.** Adspirer never receives, stores, or transmits your login credentials. (ChatGPT Ads has no login — you paste an OpenAI Advertiser API key, which Adspirer stores encrypted and never exposes to the AI client.) * **PKCE prevents interception.** Every authentication generates a cryptographic proof that only your specific session can complete. Even if someone intercepts the authorization code, they can't use it. * **Scoped permissions.** You authorize exactly what Adspirer can do — read campaign data, create ads, manage budgets. Nothing more. * **Meta approved access.** Adspirer has Meta approved Ads Management Standard Access, meaning Meta has verified the app's use of their Marketing API. Meta's account enforcement systems (security reviews, restrictions, account disabling) operate independently from Adspirer and are governed by Meta's own Community Standards and policies. * **Google agency-level approval.** Google reviewed and classified Adspirer as an agency, full-service ad platform for the Google Ads API and granted Standard Access — verifying how Adspirer uses the API and lifting the daily operations cap. (This is the Google Ads API "external full-service" classification — not the separate Google Partners program.) * **Reviewed by the AI platforms.** Adspirer's Claude connector is **Anthropic verified**, meaning Anthropic has reviewed it for quality and security. Its Cursor plugin is **Verified by Cursor**, and the same listing powers Grok Bot. Its ChatGPT plugin is reviewed and published by OpenAI. Install from those listings rather than adding a custom connector by URL. ### Token Lifecycle | Token | Lifetime | Purpose | | - | - | - | | Authorization code | 10 minutes | One-time code exchanged for tokens at sign-in | | Access token | 7 days | Authorizes tool calls | | Refresh token | 30 days | Generates new access tokens without re-login | AI client tokens are stored only as hashes and are refreshed automatically. If a token expires or is revoked, your AI client prompts you to re-authenticate. ## API Key Authentication For remote servers, Docker containers, and CI/CD pipelines where browser-based OAuth isn't possible, Adspirer supports **Personal Access Tokens** (API keys). ### How API Keys Work 1. You generate a key from the Adspirer dashboard at [adspirer.ai/keys](https://adspirer.ai/keys) 2. The key starts with `sk_live_` and is shown **once** — copy it immediately 3. Adspirer stores a **SHA-256 hash** of the key — the raw token is never stored 4. On each request, the server hashes the provided token and looks up the hash in the database ### API Key Security Properties | Property | Detail | | - | - | | **Format** | `sk_live_` prefix + 32 URL-safe random characters | | **Storage** | SHA-256 hash only — raw token never stored server-side | | **Lookup** | O(1) indexed hash lookup (no bcrypt iteration) | | **Expiration** | Optional — set at creation (30 days, 90 days, 1 year, or never) | | **Revocation** | Instant — revoked keys are rejected immediately | | **Scope** | Full account access (same as OAuth) — cannot manage other API keys | | **Tier limits** | Free: 2 keys, Plus: 5, Pro: 10, Max: 20 | ### Revoking API Keys Revoke a key instantly from [adspirer.ai/keys](https://adspirer.ai/keys). Revoked keys return a `401` error on the next request. The key record is preserved for audit trail (revocation timestamp visible in admin). ### API Keys vs OAuth | | OAuth 2.1 (PKCE) | API Key | | - | - | - | | **Best for** | Browser-based AI clients | Remote servers, Docker, CI/CD | | **Auth flow** | Browser redirect | `--token` flag or env var | | **Token rotation** | Automatic (1hr access, 30d refresh) | Manual (generate new key) | | **Security** | PKCE-protected code exchange | SHA-256 hashed token | ## What Data Adspirer Accesses **Reads:** * Campaign names, statuses, budgets * Performance metrics (spend, conversions, CPA, ROAS, CTR) * Keywords, ad copy, targeting settings * Asset metadata (image/video dimensions, file sizes) **Writes (with your confirmation):** * Create campaigns (always created PAUSED) * Update budgets and bids * Pause or resume campaigns * Add keywords, ad copy, or extensions **Never accesses:** * Your ad platform login credentials * Billing/payment information (credit cards, bank accounts) * Personal data beyond what's shown in ad account settings * Data from other ad accounts you haven't explicitly connected ## Campaign Safety Every write operation has built-in safety: * **Campaigns created PAUSED** — You review before any money is spent * **User confirmation required** — Your AI assistant asks before budget-affecting actions * **No automatic retries** — If a campaign creation fails, it reports the error instead of retrying * **Read-before-write** — Research and validation always happen before creation ## Revoking Access You can disconnect Adspirer at any time: 1. **From Adspirer:** Visit [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account) and disconnect the platform 2. **From the ad platform:** Revoke access in your platform's security settings: * Google: [Security Settings](https://myaccount.google.com/permissions) * Meta: [Business Integrations](https://www.facebook.com/settings?tab=business_tools) * LinkedIn: [Permitted Services](https://www.linkedin.com/psettings/permitted-services) * TikTok: Business Center > Settings > Authorized Partners Revoking from either side immediately stops all tool access. 3. **API Keys:** Visit [adspirer.ai/keys](https://adspirer.ai/keys) and click **Revoke** on any active key. The key is invalidated immediately. ## Infrastructure Security | Layer | Protection | | - | - | | **Transport** | HTTPS/TLS encryption for all API calls | | **Hosting** | Google Cloud Run with auto-scaling and DDoS protection | | **Sessions** | Redis with auto-expiring keys (1hr TTL) | | **Tokens** | Encrypted at rest, hashed in database | | **Logging** | Structured logs exclude sensitive data (tokens, credentials) | ## Data Handling & Compliance Adspirer is operated by **BETSONAGI LLC, d/b/a Adspirer**, a United States company. This section summarizes how customer data is stored, protected, shared, retained, and deleted. The [Privacy Policy](https://www.adspirer.com/privacy) is the governing document. ### Data Location All customer data is stored and processed in the **United States**, on Google Cloud Platform (us-central1). Every subprocessor listed below processes data in the United States. Where international transfer safeguards are required, we use appropriate mechanisms such as Standard Contractual Clauses. ### Security Controls | Control | How it works | | - | - | | **Encryption in transit** | TLS 1.2+ on every endpoint (TLS 1.3 where supported). No unencrypted connections are accepted. | | **Encryption at rest** | AES-256 across databases, caches, storage, and backups. Ad platform OAuth tokens get an additional layer of application-level encryption. | | **Credential storage** | AI client tokens and API keys are stored only as hashes. Secrets live in Google Secret Manager, never in code or logs. | | **Network isolation** | Databases run on a private network with no public IP addresses. | | **Least privilege** | Each production service runs under its own identity with the minimum permissions it needs. Staff access to production is restricted. | | **Data isolation** | Each user's data is scoped to their own account. No data is shared between users. | | **Audit logging** | Every tool call is logged with its timestamp and outcome, without tokens or credentials. | | **Security testing** | Weekly penetration testing. Adspirer's MCP server has been certified by BlueRock IO, an independent MCP security firm; attestation is available on request. | ### Subprocessors | Subprocessor | Purpose | Location | | - | - | - | | Google LLC (Google Cloud Platform) | Hosting, databases, storage, logging | United States | | Clerk, Inc. | User sign-in and identity | United States | | Stripe, Inc. | Payments and subscription billing | United States | | Twilio Inc. (SendGrid) | Transactional and notification email | United States | | PostHog, Inc. | Product analytics, using pseudonymous identifiers only | United States | | OpenAI, L.L.C. | Tool-search embeddings and speech transcription | United States | | Anthropic PBC | Support replies and features that run on Adspirer's side, such as automated agents and workflows | United States | The advertising platforms you connect (Google, Meta, LinkedIn, TikTok, Amazon, Microsoft) and the AI client you use are connected at your direction with your own authorization. They are not Adspirer subprocessors. ### AI and Data Use * Adspirer does **not** use your data to train AI models, and AI model providers we use are not permitted to train on it. * Adspirer does **not** sell your data or use it for advertising. * Adspirer does not receive your full conversations with your AI client, only the tool requests it sends. ### Retention and Deletion | Data | Retention | | - | - | | Account, campaign, and performance data | While your account is active | | AI client tokens | Authorization codes 10 minutes; access tokens 7 days; refresh tokens 30 days | | Ad platform OAuth tokens | Until you disconnect the account or revoke access | | Temporary asset uploads | 1 hour | | Database backups | Rolling 7 days | **After you leave:** when you delete your account or ask us to delete your data, everything is deleted within **90 days**, including tool call logs and backups. The only exception is billing and legal records we are required to keep. To request deletion, email [support@adspirer.com](mailto:support@adspirer.com). See [Privacy Policy, Section 4](https://www.adspirer.com/privacy#after-you-leave). ### Incident Response If we learn of a security incident that affects your personal data, we notify affected users without undue delay and as required by law. When an incident involves data received through a partner AI platform, we also notify that platform within the time its terms require. For Meta's Muse connector platform, that is within 48 hours. See [Privacy Policy, Section 6](https://www.adspirer.com/privacy#security-incidents). ### Government and Third-Party Requests We disclose user data only in response to a valid, legally binding request, such as a subpoena, court order, or warrant. We review each request for legal validity and scope, challenge requests that are overbroad or unlawful, and disclose only the minimum data needed. Where the law allows, we notify the affected user first. No government has direct or bulk access to Adspirer data. To submit a request, email [support@adspirer.com](mailto:support@adspirer.com) with the subject line "Legal Process Request". Include the signed legal process, the requesting authority and an official contact, the account the request concerns, and the specific data and date range sought. We verify every requester and do not respond to informal or incomplete requests. The full requirements are in [Privacy Policy, Section 3](https://www.adspirer.com/privacy#government-requests). ### Data Processing Addendum Business, agency, and enterprise customers can request a Data Processing Addendum (DPA) at [support@adspirer.com](mailto:support@adspirer.com). ## FAQ > **Is my ad data shared with other users?** > > No. Your data is isolated to your Adspirer account. No data is shared between users, used for training, or sold to third parties. > **Can Adspirer spend money without my approval?** > > No. All campaigns are created PAUSED, and budget changes require explicit user confirmation. Even autonomous agents (like Codex) follow this rule. > **What happens if Adspirer goes down?** > > Your ad campaigns continue running normally — they're managed by Google/Meta/LinkedIn/TikTok, not by Adspirer. You just can't make changes via AI until the service recovers. Downtime does not affect live campaigns. # Adspirer Support: Discord, GitHub & Email Help Source: https://www.adspirer.com/docs/knowledge-base/support Get help with Adspirer — join our Discord community, report bugs on GitHub, or email support. Team onboarding and priority response available. Need help? Here's how to reach us. ## Quick Fix: Connection Issues If Adspirer tools aren't responding or you see connection errors, try these steps in order: **1. Check Tool Permissions** In your AI client's connector settings, make sure: * **Read tools** (performance, research, status) → **Always allow** * **Write tools** (campaign creation, budget changes) → **Custom** (ask each time) If tools are blocked or set to "Never allow," nothing will work. **2. Disconnect and Reconnect the Connector** * **Claude:** Customize → Connectors → **Adspirer Ads & Performance Marketing Agent** → Disconnect → Connect again → Complete OAuth * **ChatGPT:** Settings → Plugins → remove the plugin you created → Plugins → Add → Add custom MCP server with `https://mcp.adspirer.com/mcp` → Create as a plugin → Complete OAuth. (The Adspirer plugin from the directory is having issues; switch to the custom MCP server.) * **Cursor:** Customize → MCP → toggle `adspirer` off and on → Complete OAuth * **Grok Bot:** Marketplace → Adspirer → **Authorize** * **Claude Code:** `/plugin` → **Installed** tab → **adspirer** → **Authenticate** (or `/mcp` → **plugin:adspirer-ads-agent:adspirer MCP Server** → **Authenticate**) Claude connectors and ChatGPT plugins may disconnect every 1–2 weeks. This is normal — just re-enable and re-authenticate. **3. Refresh Your Adspirer Session** If reconnecting didn't help, your login session may have expired: 1. Go to [adspirer.ai](https://adspirer.ai) 2. Log out (avatar → Sign out) 3. Log back in 4. Return to your AI client and retry > [!NOTE] > > These steps apply when **nothing works** — not even `get_connections_status` or basic tools. If some platforms work but one doesn't, that's a platform-specific issue. Reconnect just that platform at [adspirer.ai/connections](https://adspirer.ai/connections). > [!TIP] > > **Check the right connection first.** Adspirer has two sign-ins that are easy to confuse: your **AI-client connection** (the ChatGPT/Claude link to Adspirer) and your **ad-platform sign-in**. When every platform fails at once it's the AI-client connection; when one fails and the others work it's that platform. To see the real error rather than guessing, ask your assistant *"why did my recent calls fail?"* — the free [`why_did_this_fail`](/docs/agent-skills/diagnostic-helper-tools) tool lists your recent failed actions with the platform's actual message behind each. Still stuck? Reach out through the channels below. > [!NOTE] > > You can also use the **in-app support chat** at the bottom-right of [adspirer.ai](https://adspirer.ai). It now accepts **screenshot attachments** (PNG/JPEG — paperclip, paste, or drag-and-drop), so you can show a visual issue instead of describing it, and your conversation resumes where you left off for up to 7 days. ## Community > **[Join our Discord](https://discord.gg/ddZr3xTR)** > > Ask questions, share workflows, get help from the team and other Adspirer users. The fastest way to get answers. ## Report an Issue Found a bug or something not working? Open a GitHub issue with the details. > **[Open a GitHub Issue](https://github.com/amekala/ads-mcp/issues/new)** > > Bug reports, unexpected errors, and tool failures. Include your AI client, ad platform, and the error message. ### What to Include in a Bug Report A good bug report helps us fix things faster: | Field | What to Include | | - | - | | **AI client** | Claude Code, Cursor, ChatGPT, Codex, OpenClaw, Windsurf, Perplexity, Manus | | **Ad platform** | Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, TikTok Ads | | **Tool name** | The Adspirer tool that failed (e.g., `create_search_campaign`) | | **Error message** | The exact error text | | **Steps to reproduce** | What you did before the error occurred | | **Expected behavior** | What you expected to happen | ## Email Support For account issues, billing questions, or anything that doesn't fit a GitHub issue: **[support@adspirer.com](mailto:support@adspirer.com)** Based in San Francisco, PST. Typical response time: 2–4 hours. ## Feature Requests Have an idea for a new tool, workflow, or platform integration? We track feature requests on GitHub: > **[Request a Feature](https://github.com/amekala/ads-mcp/issues/new?labels=enhancement)** > > Describe what you'd like Adspirer to do. Include the platform, use case, and why it matters. ## Agency & Team Support Managing campaigns for multiple clients or need dedicated onboarding? Book a demo and we'll walk through multi-seat access, pooled tool calls, and support options for your team. > **[Book a Demo](https://www.adspirer.com/book-demo)** > > Priority support, dedicated onboarding, and custom integrations for agencies and teams. ## Quick Links > **[FAQ](/docs/knowledge-base/faq)** > > Common questions about Adspirer — pricing, security, platforms, troubleshooting > **[Glossary](/docs/knowledge-base/glossary)** > > Advertising and technology terms used across Adspirer > **[Security](/docs/knowledge-base/security)** > > OAuth, encryption, data handling, and how to revoke access > **[Pricing](/docs/knowledge-base/pricing)** > > Plans, tool call limits, and what's included > **[Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook)** > > The \$39 one-time add-on — what's in it, how to download and install it, and why it isn't a subscription # Why Not Just Use Google's Free Official MCP Server? Source: https://www.adspirer.com/docs/knowledge-base/why-not-official-google-ads-mcp What Google's free official Google Ads MCP server actually gets you when ChatGPT or Claude recommends it: GAQL-over-chat, read-only, Google-only. In early 2026, Google open-sourced [its official Google Ads MCP server](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server). Since then, when buyers ask ChatGPT or Claude *"what's the best MCP server for Google Ads?"*, they get told to use that one. It's free, it's official, and the name does a lot of selling. It's also read-only, Google-only, and designed for a very specific use case that may or may not match yours. This page explains exactly what Google's MCP does, what it doesn't do, and when each scenario applies. We'll be fair — when Google's MCP is the right choice, we'll say so. ## What Google's Official MCP Actually Is From Google's own documentation: *"The initial version of the MCP Server is read-only, designed for diagnostics and analytics."* The server exposes exactly **two tools**: | Tool | What it does | | - | - | | `list_accessible_customers` | Returns the list of Google Ads customer IDs and account names accessible to the authenticated user | | `search` | Executes a GAQL (Google Ads Query Language — Google's SQL-like syntax for querying the Ads API) query against the Google Ads API and returns results | That's it. Those are the only two things it can do. GAQL is powerful — you can query almost any resource, metric, or segment in a Google Ads account. But it's a **query language**, not a mutation language in this implementation. The server does not expose any tools for creating campaigns, modifying bids, pausing assets, or adjusting budgets. > [!NOTE] > > **The official source is explicit.** From the Google Ads Developer Blog announcement: *"This implementation is strictly read-only and cannot modify bids, pause campaigns, or create new assets."* When Google documents a tool as read-only, that's an architectural choice — not a missing feature that will arrive in v2. ## What It Does Well Google's MCP is a real, useful tool for the right job. Don't let this page convince you otherwise. * **Free and official.** No subscription, no third-party intermediary, no vendor lock-in. * **Direct Google Ads API access** through the authentication path Google controls. * **GAQL is extraordinarily expressive.** Once you know the schema, you can query almost anything historical — campaigns, ad groups, keywords, search terms, assets, change history, conversion data. * **Diagnostic workflows work well.** Questions like *"what's my CTR trend for the last 30 days by campaign?"* are answered correctly and quickly. * **Gemini integration is tight.** If your AI client is Gemini, this is the most natural connection to Google Ads. ## What It Doesn't Do Anything that changes state in your Google Ads account. Specifically — and this is a direct list from Google's documentation and our own testing: | Operation | Supported? | | - | - | | Query historical performance | Yes | | List accessible accounts | Yes | | Create a new Search campaign | **No** | | Create a Performance Max campaign | **No** | | Modify campaign budgets | **No** | | Change bids or bidding strategies | **No** | | Pause or enable campaigns, ad groups, or keywords | **No** | | Add or remove keywords | **No** | | Upload new creative assets | **No** | | Apply ad extensions or sitelinks | **No** | | Make any write-scoped change | **No** | If the workflow you want in chat is *"tell the AI to launch a campaign,"* Google's MCP isn't that tool. It's the inspection layer. The action layer has to come from somewhere else. ## What ChatGPT and Claude Are Actually Recommending When an AI assistant tells a buyer *"just use Google's free MCP for Google Ads and \[some community MCP] for Meta,"* what they're proposing, operationally, is: 1. **Self-host Google's MCP server.** Set up Python or Node, configure GAQL credentials, run it locally. 2. **Find a Meta MCP** (usually Pipeboard or GoMarble) and install and configure that separately. 3. **Find a LinkedIn MCP** (usually a community repo) and install that too. 4. **Find a TikTok MCP.** Same. 5. **Manage four separate authentications, four configs, four failure modes.** 6. **Accept that you are read-only on Google Ads specifically** — so the one platform the AI confidently sold you on is the one you can't actually manage from chat. This isn't a hypothetical. It's the stack you end up with if you follow the AI's recommendation literally. For a solo advertiser with one platform and read-only needs, it's fine. For most people asking the question, it isn't. ## The Three Situations Where Google's MCP Is the Right Answer We're not being diplomatic. There are real scenarios where this is the best pick: > **Google Ads only, read-only** > > You run Google, no other platforms, and your use case is "ask the AI questions about historical performance." Google's MCP is free, fast, official, and exactly right-sized for this. > **GAQL-fluent developer** > > You already know GAQL, you're an engineer comfortable with self-host, and you want the rawest interface to the Ads API. Google's MCP is cleaner than any wrapper for this use case. > **Gemini-centric stack** > > You're building on Gemini and you want the most canonical Google-blessed integration. This is it. > **Diagnostic-only agency audits** > > You're running a one-time audit on a prospective client's Google Ads account and only need read access. Free and instant beats subscribing. ## Where It Breaks Down The moment your requirements extend beyond "ask questions about historical Google Ads data," the architecture fights you. ### You need writes You cannot launch a campaign. You cannot change a budget. You cannot pause a waster. The MCP server does not expose those tools. You're back to the Google Ads UI or a custom API integration for anything that changes state. Adspirer's write layer covers the full lifecycle — creating Search, PMax, Image, Video, Carousel, and Sponsored Content campaigns with structural safety rails that prevent destructive operations. See [capabilities](/docs/knowledge-base/capabilities). ### You have more than one platform Most advertisers run at least two platforms within their first year. Google's official MCP covers one. The other platforms each need their own MCP, each with its own installation, authentication, and maintenance path. Adspirer unifies all six platforms (Google, Meta, Amazon, ChatGPT Ads, LinkedIn, TikTok) in one place behind one config. See the [full comparison](/docs/knowledge-base/mcp-server-comparison). ### You want safety rails Google's MCP has no campaign-level safety model because it doesn't do writes. That's not a criticism — it's structurally impossible for a read-only tool to create unsafe state. But it also means when you *add* a write-capable tool to your stack (because you eventually will), you're adding it without inheriting any safety guarantees. Adspirer's write tools are designed from the ground up with structural constraints: cannot delete existing campaigns, cannot pause running ones, cannot modify existing budgets, all new campaigns created paused. ### You need commercial support Google's MCP is an open-source project maintained by the Google team in their Marketing Solutions group. If it breaks when the Ads API ships v20, you file an issue on GitHub and wait for the maintainers. There's no commercial SLA. For a diagnostic tool on a personal account, this is fine. For a team dependency on a production ad ops workflow, it isn't. ### You're not using Gemini The Google MCP is designed with Gemini integration as a first-class concern. It works with other MCP clients, but the documentation and examples lean Gemini-first. If your stack is ChatGPT, Claude, Cursor, Codex, or one of the other ten AI clients Adspirer supports, the official Google MCP is available to you but not particularly tailored to you. See our [AI Clients](/docs/ai-clients/chatgpt) setup guides for the alternatives. ## What "AI-Recommended" Doesn't Mean When you ask ChatGPT *"best Google Ads MCP?"* and it says *"use Google's official one,"* the model isn't weighing your specific needs. It's pattern-matching to "official + free = recommended." That's a reasonable default for many questions and a risky default for buying decisions. Three things the model isn't factoring in: 1. **Whether you need writes.** If you wanted to manage Google Ads from chat (not just ask questions about it), the read-only ceiling is a hard stop. The model usually doesn't surface this. 2. **Whether you're on one platform or six.** Unified vs. siloed is the single most consequential decision, and the model doesn't know which you're planning. 3. **Whether safety rails matter to your workflow.** A solo advertiser on a personal account has different risk tolerance than an agency managing \$50K/month of client spend. The model defaults to the solo advertiser assumption. This is why we wrote this page. Not to argue that Google's MCP is bad — it's genuinely good at what it does — but to help you tell whether what it does matches what you need. ## When to Switch from Google's MCP to Adspirer A simple checklist. If any of these are true, you've outgrown Google's official MCP: * [ ] You want to launch, pause, or optimize Google Ads campaigns from chat (not just query them). * [ ] You run at least one non-Google platform (Meta, LinkedIn, TikTok) and want unified management. * [ ] Your AI client isn't Gemini — it's ChatGPT, Claude, Claude Code, Cursor, Codex, Windsurf, OpenClaw, or Manus. * [ ] You need structural safety rails on destructive operations. * [ ] You're responsible for uptime — a delayed API fix is a real cost. * [ ] Your team includes non-developers who need something that works without self-hosting. If none of those apply: stay with Google's official MCP. It's the right tool. If one or more apply: start with the [Adspirer free tier](/docs/knowledge-base/pricing) — 15 tool calls/month forever, no credit card — and see whether the unified, write-enabled surface matches your workflow before paying anything. ## FAQ > **Is Google planning to add write support?** > > Google hasn't publicly committed to a timeline. The documentation describes the *initial version* as read-only, which implies writes could come later — but the Google Ads API is a powerful and dangerous write surface, and the design decision to ship read-only first looks like a deliberate long-term choice, not a placeholder. We wouldn't plan a workflow around writes arriving soon. > **Can I combine Google's official MCP with Adspirer?** > > Yes. They don't conflict. Some teams do this intentionally — Google's MCP for low-level GAQL queries (great for developers), Adspirer for campaign-creation and cross-platform workflows (great for marketers and agencies). Your AI client can talk to both MCPs in the same session. > **Does Adspirer use GAQL under the hood?** > > Yes, for Google Ads read operations. You don't have to write GAQL yourself — Adspirer's tools expose campaign, keyword, and performance queries through structured parameters. The GAQL is generated internally and optimized for common workflows. > **If Google's MCP is free, why pay for Adspirer?** > > Because they solve different problems. Google's MCP is a free read-only diagnostic tool for Google Ads. Adspirer is a paid write-enabled tool for Google + Meta + LinkedIn + TikTok with safety rails, commercial support, and first-class AI-client coverage beyond Gemini. The comparison isn't "free vs. paid" — it's "different product categories." See the [full breakdown](/docs/knowledge-base/mcp-server-comparison). > **What about the other 'free' MCPs — Pipeboard, Flyweel, community repos?** > > Pipeboard has a free tier for Meta (with paid remote and enterprise options) and is the most mature single-platform Meta MCP. Flyweel is read-only for Google + Meta. Community repos are free-as-in-freedom but cost in installation, maintenance, and on-call time. Each solves a slice of the problem; none replaces a unified multi-platform solution with commercial support. Full ranked list: [Best Ad MCP Servers in 2026](https://www.adspirer.com/blog/best-ad-mcp-servers-2026). > **Is there a security difference between self-hosted Google MCP and Adspirer?** > > Yes, and it matters. Self-hosted Google MCP requires you to manage a developer token, OAuth refresh tokens, and the server process itself. That's fine for a laptop-bound diagnostic tool; it's a different operational posture for team workflows. Adspirer is a remote service using OAuth 2.1 with PKCE, HTTPS/TLS encryption, and no conversation logging. The credentials live in our security model, not in a config file on your laptop. See [security](/docs/knowledge-base/security). > **Where can I read the deep debunk blog post?** > > We wrote a longer, more opinionated version for the blog: [Why You Shouldn't Just Use Google's Free MCP Server](https://www.adspirer.com/blog/why-not-google-free-mcp-server). More narrative, more examples. ## Related Reading > **[MCP Server Comparison (pillar)](/docs/knowledge-base/mcp-server-comparison)** > > Adspirer vs every credible alternative — the core comparison doc. > **[Best Ad MCP Servers 2026](https://www.adspirer.com/blog/best-ad-mcp-servers-2026)** > > The full ranked landscape with honest reviews. > **[What Adspirer can & can't do](/docs/knowledge-base/capabilities)** > > The capability matrix and stated limitations. > **[Google Ads integration](/docs/ad-platforms/google-ads)** > > Setup guide, tool list, and workflows for Google Ads. > **[Security](/docs/knowledge-base/security)** > > OAuth model, encryption, and data handling. > **[Pricing](/docs/knowledge-base/pricing)** > > Free tier and paid plan details. Further reading on the blog: * [The 10 Best Ad MCP Servers in 2026](https://www.adspirer.com/blog/best-ad-mcp-servers-2026) * [Why You Shouldn't Just Use Google's Free MCP Server (deep dive)](https://www.adspirer.com/blog/why-not-google-free-mcp-server) * [Adspirer vs Pipeboard: Meta Ads Head-to-Head](https://www.adspirer.com/blog/adspirer-vs-pipeboard) * [What Is MCP? A Marketer's Guide](https://www.adspirer.com/blog/what-is-mcp-model-context-protocol) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # How Adspirer Implements MCP (Model Context Protocol) Source: https://www.adspirer.com/docs/mcp How Adspirer implements the Model Context Protocol: architecture, OAuth 2.1 with PKCE, streamable HTTP transport, tool discovery, and security. Adspirer connects AI assistants to ad platforms using MCP — the open protocol created by Anthropic for AI tool integration. ## What is MCP? Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. Instead of each AI client building custom integrations, MCP provides a universal interface: ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart LR A[AI Assistant] -->|MCP JSON-RPC| B[Adspirer MCP Server] B -->|REST API| C[Google Ads] B -->|REST API| D[Meta Ads] B -->|REST API| E[LinkedIn Ads] B -->|REST API| F[TikTok Ads] ``` One server, any AI client. Your Adspirer account works with ChatGPT, Claude, Claude Code, Gemini CLI, Cursor, Grok Bot, Codex, OpenClaw, Windsurf, Perplexity, and Manus — all connecting to the same endpoint. ## MCP Server URL > [!NOTE] > > **MCP Server URL:** `https://mcp.adspirer.com/mcp` > > This single URL is used across all AI clients. The server auto-detects the transport type based on the client's request. > [!NOTE] > > **In Claude, Cursor, and Grok Bot you don't paste this URL.** Install Adspirer from each app's official listing: the Anthropic-verified Claude connector, or the Verified by Cursor plugin, which Grok Bot also uses. Those listings point at this server for you. Paste the URL in ChatGPT, as a custom MCP server ([steps](/docs/ai-clients/chatgpt)), since the ChatGPT plugin is having issues right now, and in clients without a listing (Windsurf, Gemini CLI, Perplexity, Manus, custom clients). See [Add to Your Agent](/docs/add-to-your-agent) for every client. ## Transport Adspirer supports two MCP transport mechanisms: | Transport | Used By | How It Works | | - | - | - | | **Streamable HTTP** | ChatGPT, Claude, Cursor, Grok Bot, Windsurf, Perplexity, Manus | HTTP POST for requests, SSE (Server-Sent Events — one-way streaming from server to client over HTTP) for streaming responses. Supports progress updates during long operations. | | **STDIO** | Claude Code (local) | JSON-RPC over stdin/stdout. Used for local terminal-based tools. | ### Streamable HTTP The primary transport for web and IDE clients. Requests are JSON-RPC 2.0 over HTTP: ```json Example MCP Request theme={"theme":{"light":"github-light","dark":"github-dark"}} { "jsonrpc": "2.0", "id": "req-1", "method": "tools/call", "params": { "name": "get_campaign_performance", "arguments": { "lookback_days": 30 } } } ``` Responses stream back via SSE with heartbeats every 30 seconds, allowing real-time progress updates during campaign creation (which can take 5-30 seconds). ### Why Not WebSockets? SSE is HTTP-native — works through firewalls, proxies, and CDNs without special configuration. WebSockets require persistent connections that many enterprise networks block. ## Authentication Adspirer uses **OAuth 2.1 with PKCE (Proof Key for Code Exchange — prevents authorization code interception attacks)** — the most secure standard for AI tool authentication. ### How It Works ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} sequenceDiagram participant User participant AI as AI Client participant MCP as Adspirer MCP participant Auth as Auth Provider AI->>MCP: Initialize connection MCP->>AI: Auth required AI->>User: Open browser for login User->>Auth: Sign in and authorize Auth->>AI: Authorization code AI->>MCP: Exchange code with PKCE verifier MCP->>AI: Access token 1hr and Refresh token 30d AI->>MCP: Tool calls with Bearer token ``` ### Key Security Properties * **PKCE (Proof Key for Code Exchange):** Prevents authorization code interception. Every auth flow generates a unique code verifier — even if someone intercepts the code, they can't use it without the verifier. * **Short-lived tokens:** Access tokens expire in 1 hour. Refresh tokens last 30 days. * **No passwords stored:** Adspirer never sees your Google, Meta, Amazon, LinkedIn, or TikTok passwords. OAuth tokens are scoped to only the permissions you authorize. (ChatGPT Ads connects with a pasted API key, stored encrypted — never a password.) * **Revocable:** Disconnect anytime from your ad platform's security settings or from [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=account). ### API Key Authentication For headless environments (remote servers, Docker, CI/CD) where a browser isn't available, Adspirer also supports **Personal Access Tokens** (API keys): * Generate a key at [adspirer.ai/keys](https://adspirer.ai/keys) — starts with `sk_live_` * Pass it via `--token` flag or `ADSPIRER_API_KEY` environment variable * The server validates API keys using SHA-256 hash lookup (no browser redirect needed) * API keys provide the same access as OAuth tokens — same tools, same quotas See [Security & Data Privacy](/docs/knowledge-base/security#api-key-authentication) for full details. ## Tool Discovery When an AI client connects, it discovers available tools via `tools/list`: ```json Tool Discovery Request theme={"theme":{"light":"github-light","dark":"github-dark"}} { "jsonrpc": "2.0", "id": "req-0", "method": "tools/list" } ``` The server returns the tool surface with names, descriptions, and input schemas. The AI client uses these schemas to understand what parameters each tool accepts and to validate inputs before calling. > [!NOTE] > > **Scalable discovery for a 400+ tool surface.** Rather than flooding the client with every tool at once, Adspirer fronts each platform with a compact **router tool** (`google_ads`, `meta_ads`, `amazon_ads`, …). The AI calls the router with `action: "list_tools"` to discover what's available, then `action: "execute"` to run a specific tool. Two helper tools make this reliable as the surface grows: **`search_tools`** finds the right tool from a natural-language description of the task, and **`get_tool_schema`** returns a tool's exact parameters before it's called. This keeps the AI accurate even across hundreds of tools. ### Tool Categories | Category | Tools | Examples | | - | - | - | | **Read** (`get_*`, `list_*`, `analyze_*`) | \~60 | Pull performance data, list campaigns, analyze trends | | **Write** (`create_*`, `update_*`) | \~25 | Create campaigns, update budgets | | **System** (`get_connections_status`, `switch_primary_account`) | \~8 | Account management, connection checks | | **Automation** (`schedule_*`, `create_monitor`) | \~8 | Recurring tasks, alerts | ### Tool Safety Model * **Read tools** auto-execute — no confirmation needed * **Write tools** require user confirmation before execution * **Destructive tools** (`remove_*`, `delete_*`) carry a `destructiveHint` and are hard-gated: they won't run unless the call explicitly passes `confirm_delete: true`, and a "pause" request will never be routed to a delete tool. This prevents an ambiguous instruction (e.g. "pause these keywords") from permanently deleting anything. * All campaigns are created **PAUSED** — you review before spending ## Tool Execution When the AI calls a tool, the server: 1. **Validates input** — Checks types, ranges, and required fields against the tool's JSON Schema 2. **Authenticates** — Verifies the OAuth token or API key and resolves the user's ad accounts 3. **Checks quota** — Confirms the user has tool calls remaining on their plan 4. **Executes** — Calls the relevant ad platform API (Google, Meta, Amazon, ChatGPT Ads, LinkedIn, or TikTok) 5. **Returns results** — Formatted text response with tables, recommendations, or confirmation ### Error Handling If something goes wrong, the server returns structured errors with recovery steps: ```json Error Response Example theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "code": -32002, "message": "No Google Ads account connected", "data": { "recovery_steps": [ "Visit adspirer.ai/connections", "Click 'Connect Google Ads'" ] } } } ``` ## Quota System Adspirer uses a tool-call-based pricing model: | Plan | Tool Calls/Month | Monthly | Annual | | - | - | - | - | | Free Forever | 15 | \$0 | — | | Plus | 150 | \$49/mo | \$485/yr | | Pro | 600 | \$99/mo | \$999/yr | | Max | 3,000 | \$199/mo | \$2,000/yr | Each tool invocation counts as 1 call regardless of platform. A typical campaign creation uses 4-6 calls (research + validate + create). Performance queries use 1 call each. See [full pricing](https://www.adspirer.com/pricing). ## Infrastructure | Component | Technology | | - | - | | **Runtime** | Python 3.11 + FastAPI (async) | | **MCP SDK** | Official MCP Python SDK | | **Hosting** | Google Cloud Run (auto-scaling) | | **Sessions** | Redis (auto-expiring, 1hr TTL) | | **Auth** | OAuth 2.1 with PKCE | | **Logging** | Structured JSON logs | ### Server Architecture **mcp.adspirer.com** **OAuth 2.1 + PKCE** **JSON-RPC 2.0 Router** **tools/list — Discover 400+ tools** **tools/call — Execute tool with auth** **Platform Adapters** **Google Ads API (156 tools)** **Meta Marketing API (60 tools)** **Amazon Ads API (61 tools)** **ChatGPT Ads / OpenAI Ads API (36 tools)** **LinkedIn Marketing API (55 tools)** **TikTok Marketing API (37 tools)** **Redis Sessions (1hr TTL)** ### Uptime The MCP server runs on Cloud Run with minimum 1 instance always warm — no cold starts for the first request. Auto-scales based on concurrent connections. ## Supported Clients Any MCP-compatible client can connect. Currently tested and documented: | Client | Transport | Setup Guide | | - | - | - | | ChatGPT (Plus/Pro) | Streamable HTTP | [ChatGPT Setup](/docs/ai-clients/chatgpt) | | Claude (Pro/Max/Team/Enterprise) | Streamable HTTP | [Claude Setup](/docs/ai-clients/claude) | | Claude Code | STDIO | [Claude Code Setup](/docs/ai-clients/claude-code) | | Gemini CLI | Streamable HTTP | [Gemini CLI Setup](/docs/ai-clients/gemini-cli) | | Cursor | Streamable HTTP | [Cursor Setup](/docs/ai-clients/cursor) | | Grok Bot | Streamable HTTP | [Grok Bot Setup](/docs/ai-clients/grok) | | Codex | Streamable HTTP | [Codex Setup](/docs/ai-clients/codex) | | OpenClaw | Streamable HTTP | [OpenClaw Setup](/docs/ai-clients/openclaw) | | Windsurf | Streamable HTTP | [Windsurf Setup](/docs/ai-clients/windsurf) | | Perplexity (Pro/Max/Enterprise) | Streamable HTTP | [Perplexity Setup](/docs/ai-clients/perplexity) | | Manus | Streamable HTTP | [Manus Setup](/docs/ai-clients/manus) | ## FAQ > **What's the difference between the MCP server and the docs MCP?** > > Two separate things. The **product MCP server** at `mcp.adspirer.com/mcp` connects AI assistants to ad platforms (400+ tools). The **docs MCP** at `www.adspirer.com/docs/mcp` is auto-generated by Mintlify and lets AI assistants search Adspirer's documentation. They serve different purposes. > **Can I build my own MCP client that connects to Adspirer?** > > Yes. Any client implementing the MCP specification can connect. Use the MCP SDK for your language (Python, TypeScript, etc.), point it at `https://mcp.adspirer.com/mcp`, and implement OAuth 2.1 for authentication. > **Is MCP the same as an API?** > > MCP is a protocol layer on top of HTTP. Think of it as a standardized way for AI assistants to discover and call APIs. Instead of writing custom API integration code, the AI client speaks MCP and automatically understands what tools are available and how to call them. > **Why not just use a REST API?** > > MCP adds tool discovery, streaming, and a standard authentication flow that AI clients already understand. With a REST API, each AI client would need custom integration code. With MCP, any compliant client connects immediately — no custom code needed. ## Related Documentation * [Quickstart](/docs/quickstart) — Get connected in 5 minutes * [Agent Skills](/docs/agent-skills/overview) — Teach your AI the right workflows * [Core Workflows](/docs/agent-skills/workflows) — Tool sequences for every platform * [Pricing & Plans](https://www.adspirer.com/pricing) * [Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook) — A custom skill, account dossier, and prompt book generated from your own ad account (\$39 one-time, one free on annual) # Quickstart: Set Up Adspirer MCP in 5 Minutes Source: https://www.adspirer.com/docs/quickstart Get started with Adspirer in under 5 minutes: sign up, connect your AI client, link an ad platform, and run your first ad campaign query. **1. Sign Up** Create your free Adspirer account at [adspirer.ai](https://adspirer.ai?utm_source=docs\&utm_medium=page\&utm_content=signup). No credit card required — free tier includes 15 tool calls per month. **2. Connect Your AI Client** Pick your AI assistant and follow the setup guide. > [!NOTE] > > **Claude, ChatGPT, Cursor, and Grok Bot:** Adspirer is an official, reviewed listing in each app's own directory. It's an Anthropic-verified connector in Claude, an OpenAI-reviewed plugin in ChatGPT, and Verified by Cursor in Cursor and Grok Bot. Search for **Adspirer** and add it. Don't set up a custom connector in Claude, Cursor, or Grok Bot. [All listings and links →](/docs/add-to-your-agent#instructions-for-ai-agents) **Chat Apps** > **[ChatGPT](/docs/ai-clients/chatgpt)** > > Official plugin in ChatGPT's Plugins directory. Custom MCP app for the newest tools. Requires Plus or Pro. > **[Claude](/docs/ai-clients/claude)** > > Anthropic-verified connector. Search Adspirer, click Connect to Claude. Requires Pro, Max, Team, or Enterprise. > **[Codex Desktop](/docs/ai-clients/codex-desktop)** > > Codex inside the ChatGPT desktop app. Three chat messages, no terminal. **Developer Tools** > **[Claude Code](/docs/ai-clients/claude-code)** > > One-command plugin install from your terminal. > **[Gemini CLI](/docs/ai-clients/gemini-cli)** > > One-command extension install from your terminal. > **[Cursor](/docs/ai-clients/cursor)** > > Verified by Cursor. One-click marketplace plugin with 14 skills, a subagent, and rules. > **[Grok Bot](/docs/ai-clients/grok)** > > Official Adspirer for Grok Bot plugin, with scheduled reports in the cloud. > **[Codex Terminal](/docs/ai-clients/codex)** > > One-command installer for autonomous agent setup. > **[OpenClaw](/docs/ai-clients/openclaw)** > > Plugin install with 14KB skill file built in. > **[Windsurf](/docs/ai-clients/windsurf)** > > Add MCP config to Windsurf settings. > **[Perplexity](/docs/ai-clients/perplexity)** > > Add custom connector in Perplexity Computer. **Quick MCP Config Reference** **Claude Code** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} /plugin install adspirer-ads-agent@claude-community ``` Anthropic community marketplace, enabled by default, no setup needed. Bundles the MCP connector with slash commands, skills, and an agent. **Cursor** ``` /add-plugin adspirer ``` Or search **adspirer** in **Customize** and add it. It's Verified by Cursor. Sign-in runs on the first tool call. The same listing works in [Grok Bot](/docs/ai-clients/grok). **Grok Bot** No config needed. Open [Adspirer for Grok Bot](https://x.ai/bot/plugin/66672239) and click **Add to Grok Bot**, or search **adspirer** in Grok Bot's **Marketplace**. Then click **Authorize** and sign in. ([Step by step](/docs/ai-clients/grok)) **Codex Terminal** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} codex plugin marketplace add amekala/ads-mcp ``` Then inside Codex run `/plugins` → **Adspirer** tab → install **Adspirer Ads Agent**. OAuth runs on first use. **Codex Desktop** In the ChatGPT desktop app, switch to **Codex** (top-left dropdown) and send three messages: ``` codex plugin marketplace add amekala/ads-mcp ``` ``` install plugin ``` ``` help me oauth it ``` Codex runs each one and opens the Adspirer sign-in. ([Step by step](/docs/ai-clients/codex-desktop)) **OpenClaw** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} openclaw plugins install openclaw-adspirer openclaw adspirer login ``` **Gemini CLI** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} gemini extensions install https://github.com/amekala/ads-mcp ``` Browser opens automatically for OAuth on first tool use. **Windsurf** Add to `~/.codeium/windsurf/mcp_config.json`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "mcpServers": { "adspirer": { "type": "streamable-http", "url": "https://mcp.adspirer.com/mcp" } } } ``` **Perplexity** In Perplexity Computer, click **Connectors** → **+ Custom connector** and enter: | Field | Value | | - | - | | **Name** | `Adspirer` | | **MCP Server URL** | `https://mcp.adspirer.com/mcp` | Check the acknowledgment box and click **Add**, then complete OAuth. **ChatGPT** Open **Plugins** in ChatGPT, click **Add → Add custom MCP server**, and enter: | Field | Value | | - | - | | **Name** | `Adspirer-Custom` | | **Connection** | **Server URL**: `https://mcp.adspirer.com/mcp` | | **Authentication** | **OAuth** | Tick **I understand and want to continue**, click **Create as a plugin**, then **Try in chat → Connect** and click **Authorize** on Adspirer. Works on every ChatGPT plan, including Free. Use this instead of the Adspirer plugin, which is having issues right now. ([Step by step, with screenshots](/docs/ai-clients/chatgpt)) **Claude** No config and no URL. Adspirer is an Anthropic-verified connector. Open **Customize → Connectors**, search **Adspirer**, and click **Connect to Claude**. Want skills and slash commands too? Add the **Adspirer** plugin from **Customize → Plugins** instead. It includes the same connector. ([Step by step](/docs/ai-clients/claude)) **3. Connect an Ad Platform** Link your advertising accounts. You can connect multiple platforms: > **[Google Ads](/docs/ad-platforms/google-ads)** > > 156 tools for Search, PMax, Shopping & App campaigns, keyword research, budget optimization. > **[Meta Ads](/docs/ad-platforms/meta-ads)** > > 60 tools for Facebook & Instagram campaigns, Advantage+ Catalog (dynamic product ads), creative testing. > **[Amazon Ads](/docs/ad-platforms/amazon-ads)** > > 61 tools for Sponsored Products, Brands & Display, ASIN targeting, ACOS/ROAS. > **[ChatGPT Ads](/docs/ad-platforms/chatgpt-ads)** > > 50 tools for pay-per-click chat-card ads inside ChatGPT, created paused. > **[LinkedIn Ads](/docs/ad-platforms/linkedin-ads)** > > 55 tools for B2B advertising, video & carousel, campaign groups, audience forecasting. > **[TikTok Ads](/docs/ad-platforms/tiktok-ads)** > > 37 tools for in-feed video, Spark Ads, and Carousel campaigns. **4. Try It Out** Once connected, ask your AI assistant: Verify your ad platform connections are working. Check my connected ad platforms You should see a table showing your connected accounts with IDs, names, and connection status. Then try something real: Research keywords with real CPC data from Google Keyword Planner. Research Google Ads keywords for "project management software" — show search volume, CPC, and competition level ## What's Next? > **[Agent Skills](/docs/agent-skills/overview)** > > Install skills to teach your AI assistant proven ad management workflows with safety rules. > **[Tool Catalog](/docs/agent-skills/tools)** > > Browse all 400+ tools organized by platform. > **[Set Up Your Project](/docs/guides/set-up-your-project)** > > Turn a one-off chat into a persistent workspace with instructions, context, and schedules. > **[Prompt Engineering Playbook](/docs/agent-skills/prompt-engineering-playbook)** > > A skill, dossier, and prompt book generated from your own ad account. \$39 one-time, one free on annual.