# 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)
</Note>

## 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.
</Note>

## 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

### 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

<Prompt description="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.
</Prompt>

<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`.
</Note>

### 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.

<Prompt description="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.
</Prompt>

## 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

<Prompt description="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?
</Prompt>

### Create a Sponsored Products Campaign

<Prompt description="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.
</Prompt>

### Find Wasted Spend

<Prompt description="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.
</Prompt>

### Launch a Sponsored Brands Campaign

<Prompt description="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.
</Prompt>

## 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.
</Tip>

## Sponsored Brands & Brand Registry

<Warning>
  Sponsored Brands campaigns require Amazon Brand Registry. Sellers supply a brand entity ID during creation, 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.
</Warning>

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.

## 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. 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

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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, and upload a brand logo with `upload_amazon_asset` for productCollection ads.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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 — 36 tools to launch, 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 **36 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
</Note>

## 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.
</Note>

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.

<Prompt description="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.
</Prompt>

### 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 `<head>`, 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 (36 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

### 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

### 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).
</Note>

## How a Launch Works

Launching never spends money on its own. Everything is created **paused**, and you resume it when you're ready.

<Steps>
  <Step title="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]."
  </Step>

  <Step title="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`.)
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

```
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.
</Note>

### 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.

<Prompt description="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.
</Prompt>

### 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.
</Warning>

`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.

<Prompt description="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.
</Prompt>

## Example Prompts

### Launch an Ad

<Prompt description="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.
</Prompt>

### Check Performance

<Prompt description="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.
</Prompt>

### Pause or Adjust Budget

<Prompt description="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.
</Prompt>

## 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.
</Warning>

## 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 `<head>`, 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.

<Steps>
  <Step title="Create the pixel">
    `create_chatgpt_pixel` creates a web measurement pixel and returns the **site snippet ready to paste** into your `<head>`, 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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<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.
</Warning>

## 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.
</Warning>

## 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`, and `archive_chatgpt_ad` require an explicit confirmation — and the agent offers pausing instead when that's what you meant.
* **Targeting edits never widen your reach by accident.** Changing one side of a campaign's location targeting preserves the other, and an unresolvable location leaves targeting untouched rather than clearing it.
* **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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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 `<head>`, 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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.
</Note>

<Frame>
  <iframe title="Google Ads + Claude: Instant Clarity with Adspirer" />
</Frame>

## 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)
</Note>

## 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.
</Tip>

### 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.
* `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 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
* `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.
* `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.
* `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

<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.
</Note>

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.

### 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".
</Warning>

**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.

### 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.
</Tip>

## 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 <Badge>New</Badge>

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 <Badge>New</Badge>

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 <Badge>New</Badge>

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

<Prompt description="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.
</Prompt>

### Research Keywords

<Prompt description="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.
</Prompt>

### Find Wasted Spend

<Prompt description="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.
</Prompt>

### Create a Search Campaign

<Prompt description="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.
</Prompt>

### Create a Performance Max Campaign

<Prompt description="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.
</Prompt>

### Add Search Themes to PMax

<Prompt description="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.
</Prompt>

### Add Audience Signals to PMax

<Prompt description="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.
</Prompt>

### Optimize Budget

<Prompt description="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.
</Prompt>

### Launch a Shopping Campaign

<Prompt description="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.
</Prompt>

## 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.
</Warning>

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.
</Note>

## 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.

### "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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)
</Note>

## 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/<id>` (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.
</Warning>

## 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/<id>; 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.

<Info>
  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.
</Info>

## Example Prompts

### Create a Standard Display Campaign

<Prompt description="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
</Prompt>

### Retargeting Campaign with User Lists

<Prompt description="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
</Prompt>

### Smart Display Campaign

<Prompt description="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
</Prompt>

### Edit Creative on an Existing Display Ad

<Prompt description="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
</Prompt>

### Add Frequency Caps

<Prompt description="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.
</Prompt>

## 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.
</Tip>

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/<id>` 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/<id>` 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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

<Frame>
  <iframe title="LinkedIn Ads with Claude Mobile App and Adspirer" />
</Frame>

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)
</Note>

## 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

<Prompt description="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.
</Prompt>

### Research Targeting for a New Campaign

<Prompt description="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.
</Prompt>

### Forecast Delivery Before Launch

<Prompt description="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?
</Prompt>

### Create a Sponsored Content Campaign

<Prompt description="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.
</Prompt>

### Optimize Budget Allocation

<Prompt description="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.
</Prompt>

### Competitive Targeting Research

<Prompt description="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?
</Prompt>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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)
</Note>

## 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.
</Tip>

<Info>
  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).
</Info>

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.

<Info>
  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.
</Info>

## 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

<Info>
  **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.
</Info>

#### 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.
</Note>

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.
</Tip>

#### 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.

<Prompt description="Check a campaign you just launched.">
  I launched a Meta campaign today. Is it actually delivering, and what has it spent?
</Prompt>

#### 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 locations with `update_meta_ad_set`, the new geo targeting **merges onto the existing targeting** rather than replacing all of it, so a location-only edit doesn't wipe your audiences and placements.

<Prompt description="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.
</Prompt>

### 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.

### 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)
* `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.

<Prompt description="Start a campaign you've reviewed.">
  Set my new Meta campaign to active
</Prompt>

### 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.
</Note>

### 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`.

<Prompt description="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.
</Prompt>

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.

<Prompt description="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.
</Prompt>

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.

<Prompt description="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.
</Prompt>

### 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
* `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.
</Note>

### 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` — Restart paused campaigns
* `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

<Prompt description="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.
</Prompt>

### Detect Creative Fatigue

<Prompt description="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.
</Prompt>

### Create an Image Campaign

<Prompt description="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.
</Prompt>

### Optimize Placements

<Prompt description="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.
</Prompt>

### Audience Analysis

<Prompt description="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.
</Prompt>

### Launch an Advantage+ Catalog (Dynamic Product Ads) campaign

<Prompt description="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.
</Prompt>

## 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.
</Note>

## 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.
</Note>

### 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.
</Warning>

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 `existing_image_hash` its asset discovery returns, so you can build carousels straight from creatives already in your account.
* **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).
* **"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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Start Authentication under Billing and payments">
    Open **Billing and payments** and click **Start Authentication**. Meta emails you a code.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Turn on two-factor authentication">
    Then check [Account Quality](https://www.facebook.com/accountquality) for anything else outstanding against the account.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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)
</Note>

## 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

<Prompt description="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?
</Prompt>

### Create a Campaign

<Prompt description="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.
</Prompt>

### Upload and Validate Video

<Prompt description="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.
</Prompt>

### Analyze What's Working

<Prompt description="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?
</Prompt>

## 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.
</Warning>

### 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:

<Prompt description="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.
</Prompt>

### 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.
</Note>

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.

<Prompt description="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.
</Prompt>

### 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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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)
</Note>

## 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       |

<Info>
  Gmail, Discover, and Display placements are **disabled** for YouTube campaigns. Your ads only show on YouTube.
</Info>

## 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

<Prompt description="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
</Prompt>

### Brand Awareness Campaign

<Prompt description="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
</Prompt>

### Check Performance

<Prompt description="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?
</Prompt>

### Validate a Video

<Prompt description="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.
</Prompt>

## 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.
</Warning>

### 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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 ChatGPT, Claude, Claude Code, Codex, and other AI agents. Share this page with your agent — it has everything the agent needs to walk you through install, sign-in, and connecting your ad accounts.

This page is the installation instructions for Adspirer — for **ChatGPT**, **Claude** (web and desktop), **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.
</Note>

## 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 distributed through reviewed channels — the [ChatGPT App Store](https://chatgpt.com/apps/adspirer/asdk_app_69461dc91ee48191ae4a14eb9bde1c21) and the [Claude plugin directory](https://claude.ai/directory/plugins/adspirer-ads-agent%40knowledge-work-plugins) — and 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<br/>LinkedIn · TikTok · ChatGPT Ads"]
```

**Install steps by client** — give your user the one path for the client you're running in:

* **ChatGPT** (web, desktop, or mobile) — send the user the [Adspirer app in the App Store](https://chatgpt.com/apps/adspirer/asdk_app_69461dc91ee48191ae4a14eb9bde1c21). They tap **Connect**, then sign in with Google or email. Requires ChatGPT Plus, Pro, Business, or Enterprise.
* **Claude** (claude.ai, desktop app, or Cowork) — send the user the [Adspirer plugin in the Claude directory](https://claude.ai/directory/plugins/adspirer-ads-agent%40knowledge-work-plugins). They click **Install**, then sign in when the Adspirer window opens.
* **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, Gemini CLI, Windsurf, or any other MCP client** — 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 → Apps → Adspirer → Connect / Reconnect**, 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 published in both directories. Install straight from the store:

<CardGroup>
  <Card title="ChatGPT App Store" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/chatgpt.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=6106ee76b21067108cdff4760dd7cfb1" href="https://chatgpt.com/apps/adspirer/asdk_app_69461dc91ee48191ae4a14eb9bde1c21">
    Tap **Connect**, sign in with Google or email, done. Requires Plus, Pro, Business, or Enterprise.
  </Card>

  <Card title="Claude Plugin Directory" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c" href="https://claude.ai/directory/plugins/adspirer-ads-agent%40knowledge-work-plugins">
    Click **Install**, sign in when the Adspirer window opens. Works in Claude and Claude Cowork.
  </Card>
</CardGroup>

## 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):

<Prompt description="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.
</Prompt>

**In ChatGPT** (ChatGPT doesn't follow fetched pages by design — ask it to act for you instead):

<Prompt description="ChatGPT finds the Adspirer app in the App Store and guides you through install and connection.">
  Find the Adspirer app in the app store and help me install and connect it so I can manage my ad campaigns from this chat.
</Prompt>

**Agent can't browse the web?** Paste the self-contained version — everything it needs is inline:

<Prompt description="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 (web, desktop, or Cowork), give me this install link to click: [https://claude.ai/directory/plugins/adspirer-ads-agent%40knowledge-work-plugins](https://claude.ai/directory/plugins/adspirer-ads-agent%40knowledge-work-plugins) — In ChatGPT, help me find and connect the Adspirer app in the App Store. 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, 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.
</Prompt>

## 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"
```

<Info>
  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`.
</Info>

## What Happens Next

Whichever path you pick, your agent runs the same flow:

<Steps>
  <Step title="Detects your environment">
    Chat app (ChatGPT, Claude, Cowork) or coding agent (Claude Code, Cursor, Codex, Gemini CLI) — and picks the right install: official app listing, plugin, or MCP config.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

<Check>
  Done when your agent shows your connected ad accounts. Try: *"How are my campaigns doing this month?"*
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="ChatGPT says &#x22;Link not found&#x22; when checking the connection">
    The app's authorization link is stale. Open **Settings → Apps → Adspirer → Connect / Reconnect**, complete the sign-in, and connect at least one ad platform. Then ask your agent to verify again.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Quickstart](/docs/quickstart) — the classic 5-minute manual setup
* [ChatGPT Setup](/docs/ai-clients/chatgpt) · [Claude Setup](/docs/ai-clients/claude) · [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).
</Note>

## How it works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<Info>
  **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.
</Info>

## Cross-platform agents

A single agent can reason and act across **Google, Meta, TikTok, LinkedIn, and Amazon** from one goal. For example:

<Prompt description="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.
</Prompt>

## 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.
</Note>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Community Plugins" icon="puzzle-piece" href="/docs/agent-skills/community-plugins">
    Extend Adspirer with open-source, read-only community analysis tools.
  </Card>

  <Card title="Agent Skills Overview" icon="brain" href="/docs/agent-skills/overview">
    Teach your AI client proven ad-management workflows.
  </Card>

  <Card title="Core Workflows" icon="diagram-project" href="/docs/agent-skills/workflows">
    Step-by-step sequences for campaign creation and optimization.
  </Card>

  <Card title="Pricing & Plans" icon="tag" href="https://www.adspirer.com/pricing">
    Quota by tier for agent runs.
  </Card>
</CardGroup>


# 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.
</Note>

***

## 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.
</Tip>

***

## 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.
</Note>

### 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   |          <Badge>Yes</Badge>         |    <Badge>Yes</Badge> (subagent)    | <Badge>Yes</Badge> (agent config) |
| 400+ Adspirer tools           |          <Badge>Yes</Badge>         |          <Badge>Yes</Badge>         |         <Badge>Yes</Badge>        |
| Skills (workflow enforcement) |        <Badge>1 skill</Badge>       |       <Badge>5 skills</Badge>       |      <Badge>5 skills</Badge>      |
| Slash commands                |      <Badge>5 commands</Badge>      |       <Badge>5 skills</Badge>       |  <Badge>5 dollar commands</Badge> |
| Brand context file            |       <Badge>CLAUDE.md</Badge>      |       <Badge>BRAND.md</Badge>       |      <Badge>AGENTS.md</Badge>     |
| Strategy persistence          |      <Badge>STRATEGY.md</Badge>     |      <Badge>STRATEGY.md</Badge>     |     <Badge>STRATEGY.md</Badge>    |
| Memory (cross-session)        |       <Badge>MEMORY.md</Badge>      |       <Badge>MEMORY.md</Badge>      |    <Badge>Not available</Badge>   |
| Rules (auto-trigger)          |     <Badge>Not available</Badge>    |     <Badge>2 rule files</Badge>     |    <Badge>Safety rules</Badge>    |
| Web research (competitors)    | <Badge>WebSearch + WebFetch</Badge> | <Badge>WebSearch + WebFetch</Badge> |    <Badge>Not available</Badge>   |

***

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.
</Tip>

***

## 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.

<Prompt description="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.
</Prompt>

<Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
</Card>

***

## 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`:

<Steps>
  <Step title="Agent spawns">
    Claude Code creates a subagent with the performance marketing agent prompt and skill preloaded.
  </Step>

  <Step title="Context loads">
    Agent reads `CLAUDE.md`, `STRATEGY.md`, and `MEMORY.md`.
  </Step>

  <Step title="Connections check">
    Calls `get_connections_status` to identify which ad platforms are active.
  </Step>

  <Step title="Data pull">
    For each connected platform, calls performance and wasted spend tools in parallel.
  </Step>

  <Step title="Strategy check">
    Compares campaign data against `STRATEGY.md` directives. Flags "Strategy Drift" items.
  </Step>

  <Step title="Analysis & recommendations">
    Compares actuals vs KPI targets. Cross-references with `MEMORY.md`. Presents a unified scorecard with top 3 recommended actions.
  </Step>
</Steps>

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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  |

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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/
    ```
  </Tab>
</Tabs>

***

## 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`

<Prompt description="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.
</Prompt>

<Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
</Card>

### 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.
</Note>

***

## The Agent Loop

When you invoke `$adspirer-performance-review` in Codex:

<Steps>
  <Step title="Skill loads">
    Codex discovers and loads the performance review skill via progressive disclosure.
  </Step>

  <Step title="Context loads">
    Reads `AGENTS.md` for brand context and KPI targets. Reads `STRATEGY.md` for active directives.
  </Step>

  <Step title="Connections check">
    Calls `get_connections_status` to identify connected ad platforms.
  </Step>

  <Step title="Data pull">
    For each connected platform, calls performance tools via Adspirer MCP.
  </Step>

  <Step title="Strategy check">
    Compares campaign data against `STRATEGY.md`. Flags "Strategy Drift" items.
  </Step>

  <Step title="Results">
    Presents a unified scorecard with recommendations and top 3 actions.
  </Step>
</Steps>

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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/).
  </Accordion>
</AccordionGroup>

## 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

<Info>
  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.
</Info>

* **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

<Prompt description="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.
</Prompt>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Autonomous Ad Ops Agents" icon="robot" href="/docs/agent-skills/ad-ops-agents">
    Background agents that propose changes to an approval queue.
  </Card>

  <Card title="Tool Catalog" icon="wrench" href="/docs/agent-skills/tools">
    The full 400+ built-in tool reference.
  </Card>
</CardGroup>


# 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: subagent architecture, 5 skills, Cursor Rules, memory, and the agent loop.

Your AI advertising manager inside Cursor. The performance marketing agent runs as a **Cursor subagent** with 5 dedicated skills and 2 Cursor 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 can delegate 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

Cursor has two features that no other client offers for Adspirer:

1. **Cursor Rules** (`.mdc` files) — auto-trigger advertising workflows based on context. You don't need to invoke a skill manually. When you mention ad campaigns, the rules kick in automatically.
2. **5 separate skills** — each focused on one workflow. The main skill (`adspirer-ads`) handles all campaigns, while 4 specialized skills handle setup, performance review, ad copy, and wasted spend.

***

## What Gets Installed

The one-command installer sets up everything:

| Component      | File                                            | Purpose                             |
| -------------- | ----------------------------------------------- | ----------------------------------- |
| **MCP Server** | `~/.cursor/mcp.json`                            | 400+ advertising tools via OAuth    |
| **Subagent**   | `.cursor/agents/performance-marketing-agent.md` | Agent prompt with brand awareness   |
| **5 Skills**   | `.cursor/skills/adspirer-*/SKILL.md`            | Workflow instructions per task type |
| **2 Rules**    | `.cursor/rules/*.mdc`                           | Auto-trigger advertising workflows  |

<Tabs>
  <Tab title="One-Command Install (Recommended)">
    Run from your **system terminal**, not Cursor's built-in terminal:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/cursor/adspirer/install.sh)
    ```

    Installs MCP server, subagent, all 5 skills, and Cursor Rules. Restart Cursor after installing.
  </Tab>

  <Tab title="Manual Install">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # Add MCP server
    echo '{"mcpServers":{"adspirer":{"url":"https://mcp.adspirer.com/mcp"}}}' > ~/.cursor/mcp.json

    # Clone and install skills + agent + rules
    git clone https://github.com/amekala/ads-mcp.git /tmp/ads-mcp
    cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/skills ~/.cursor/
    cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/agents ~/.cursor/
    cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/rules ~/.cursor/
    ```
  </Tab>
</Tabs>

***

## The 5 Skills

Cursor uses **5 separate skills**, each focused on one workflow. This maps to Cursor's skill architecture where each skill has its own invocation command.

| 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 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. Each skill is a `SKILL.md` file in `.cursor/skills/adspirer-*/`
4. You can invoke directly with `/adspirer-*` or just describe what you want

<Prompt description="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.
</Prompt>

<Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
</Card>

### Main Skill: adspirer-ads

The comprehensive skill covering all platforms and workflows:

* Campaign creation flows for Google Search, PMax, Meta, LinkedIn, TikTok
* Keyword research with strategy directive filtering
* Cross-platform performance dashboards
* Budget optimization and wasted spend analysis
* Ad extension workflows (sitelinks, callouts, structured snippets)
* Competitive intelligence via web research
* Audience analysis and optimization
* Monitoring and scheduled reporting

### Specialized Skills

The 4 smaller skills focus on specific workflows:

| Skill                  | Steps It Follows                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup**              | Check MCP → Scan folder → Pull live data → Create `BRAND.md` + `STRATEGY.md` → Present summary                                                    |
| **Performance Review** | Read context → Read strategy → Pull all platform data → Pull wasted spend → Unified scorecard → Top 3 actions                                     |
| **Write Ad Copy**      | Read brand voice → Read strategy → Pull campaign structure → Analyze search terms → AI suggestions → Filter through brand rules → Present options |
| **Wasted Spend**       | Check connections → Read strategy → Analyze waste per platform → Budget reallocation → Recommend fixes                                            |

***

## Cursor Rules

Cursor Rules are `.mdc` files that auto-trigger behavior. Adspirer ships 2 rules:

### 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 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 with `alwaysApply: true` | `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.
</Note>

***

## Context Files

The agent uses three persistent files. Cursor's file 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                |

### STRATEGY.md — Strategic Decisions

Same as Claude Code. 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:

<Steps>
  <Step title="Rule activates">
    `brand-workspace.mdc` fires, loading `BRAND.md` and `STRATEGY.md` into context.
  </Step>

  <Step title="Skill loads">
    Cursor matches the performance review skill and loads its full workflow instructions.
  </Step>

  <Step title="Agent spawns">
    The performance marketing subagent starts with brand context, strategy, and memory.
  </Step>

  <Step title="Data pull">
    For each connected platform, calls performance and wasted spend tools via Adspirer MCP.
  </Step>

  <Step title="Strategy check">
    Compares campaign data against `STRATEGY.md`. Flags "Strategy Drift" items.
  </Step>

  <Step title="Results">
    Presents a unified scorecard with recommendations and top 3 actions.
  </Step>
</Steps>

***

## 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               |
| Cursor Rules enforcement    | `use-adspirer.mdc` auto-triggers safety checks                  |

***

## Comparison with Other Clients

| Feature              |          Cursor          |        Claude Code       |     Codex     |
| -------------------- | :----------------------: | :----------------------: | :-----------: |
| Agent type           |         Subagent         |         Subagent         |  Agent config |
| Brand context file   |        `BRAND.md`        |        `CLAUDE.md`       |  `AGENTS.md`  |
| Skills               |        5 separate        |      1 comprehensive     |   5 separate  |
| Commands             |       `/adspirer-*`      |       `/adspirer:*`      | `$adspirer-*` |
| Memory               |        `MEMORY.md`       |        `MEMORY.md`       | Not available |
| Rules (auto-trigger) |       2 rule files       |            --            |  Safety rules |
| Web research         | `WebSearch` + `WebFetch` | `WebSearch` + `WebFetch` | Not available |

***

## FAQ

<AccordionGroup>
  <Accordion title="Do I need Cursor 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.
  </Accordion>

  <Accordion title="Can I edit the rules and skills?">
    Yes. Rules are `.mdc` files in `.cursor/rules/`. Skills are `SKILL.md` files in `.cursor/skills/`. Edit them to change default behaviors, add custom workflows, or modify safety rules.
  </Accordion>

  <Accordion title="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 can delegate to when advertising tasks come up. The subagent has its own context, so ad workflows don't bloat your coding session.
  </Accordion>

  <Accordion title="Can I use Adspirer in Cursor without the agent?">
    Yes. Just add the MCP server and you get 400+ tools directly. But without the agent, skills, and rules, you lose brand awareness, workflow enforcement, strategy persistence, and memory.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [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 5 skills with invocation details
* [Cursor Setup](/docs/ai-clients/cursor) — 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)


# 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.
</Note>

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. |

<Prompt description="Personalized first step based on your connected accounts.">
  I just connected Adspirer — what should I do first?
</Prompt>

## 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. |

<Prompt description="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.
</Prompt>

## 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.
</Tip>

<Prompt description="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.
</Prompt>

## 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.

<Prompt description="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.
</Prompt>

## 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.

<Info>
  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).
</Info>

## 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.

<Card title="A free skill for your agent" icon="gift">
  Agent instructions and eight ready-to-use prompts in one file. Keep it, customize it, or share this page with a friend.

  <FreeSkillDownload />
</Card>

## 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.

<FreeSkillGuide>
  <Tabs>
    <Tab title="Claude" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c">
      <Steps>
        <Step title="Open Skills">
          Open **Settings → Customize → Skills**, then choose **Upload skill**.
        </Step>

        <Step title="Upload your download">
          Choose **SKILL.md** and click **Save**. You can upload the Markdown file directly.

          <Frame>
            <img alt="Claude Upload skill screen showing support for Markdown files with a YAML skill name and description" />
          </Frame>
        </Step>

        <Step title="Try a prompt">
          Open a conversation and paste one of the [starter prompts below](#try-a-starter-prompt).
        </Step>
      </Steps>
    </Tab>

    <Tab title="ChatGPT" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/chatgpt.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=6106ee76b21067108cdff4760dd7cfb1">
      <Steps>
        <Step title="Open Skills">
          Open **Plugins → Skills**, then click **+**.
        </Step>

        <Step title="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.

          <Frame>
            <img alt="ChatGPT Plugins and Skills page with Upload from your computer selected in the plus menu" />
          </Frame>
        </Step>

        <Step title="Try a prompt">
          Open a conversation and paste one of the [starter prompts below](#try-a-starter-prompt).
        </Step>
      </Steps>
    </Tab>

    <Tab title="Coding agent" icon="code">
      <Steps>
        <Step title="Open your repository">
          Open the local repository where you want to use the skill in Claude Code, Codex, Cursor, or your preferred coding agent.
        </Step>

        <Step title="Attach the file and ask your agent to install it">
          Attach **SKILL.md**, then copy this message:

          <Prompt description="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.
          </Prompt>
        </Step>

        <Step title="Try a prompt">
          Once your agent confirms where it saved the skill, paste one of the [starter prompts below](#try-a-starter-prompt).
        </Step>
      </Steps>
    </Tab>
  </Tabs>
</FreeSkillGuide>

<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).
</Note>

## 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.

<AccordionGroup>
  <Accordion title="Understand performance">
    <Prompt description="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.
    </Prompt>

    <Prompt description="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.
    </Prompt>
  </Accordion>

  <Accordion title="Reduce wasted spend">
    <Prompt description="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.
    </Prompt>

    <Prompt description="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.
    </Prompt>
  </Accordion>

  <Accordion title="Plan a campaign">
    <Prompt description="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.
    </Prompt>

    <Prompt description="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.
    </Prompt>
  </Accordion>

  <Accordion title="Improve creative">
    <Prompt description="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.
    </Prompt>

    <Prompt description="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.
    </Prompt>
  </Accordion>
</AccordionGroup>

## Want a starting point tailored to your account?

<Card title="Explore the Agent Playbook" icon="book-open" href="/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.
</Card>


# 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.

<Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
</Card>

***

## 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

<Prompt description="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"
</Prompt>

<Prompt description="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.
</Prompt>

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

<Frame>
  <iframe title="Analyze Campaign Performance Directly from Claude with Adspirer" />
</Frame>

## 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) | <Badge>Full</Badge> + Slash Commands     | `~/.claude/skills/` (via plugin)          |
| [Cursor](/docs/ai-clients/cursor)           | <Badge>Full</Badge> + Subagent + Rules   | `~/.cursor/skills/` + `~/.cursor/agents/` |
| [Codex](/docs/ai-clients/codex)             | <Badge>Full</Badge> + Agent Config       | `~/.agents/skills/` + `~/.codex/agents/`  |
| [OpenClaw](/docs/ai-clients/openclaw)       | <Badge>Bundled</Badge> (14.4KB SKILL.md) | Auto-installed with plugin                |
| [Windsurf](/docs/ai-clients/windsurf)       | <Badge>Coming soon</Badge>               | --                                        |
| Claude (Web/Desktop)                        | <Badge>Supported</Badge>                 | Upload via **Customize → Skills**         |
| ChatGPT                                     | <Badge>Connector only</Badge>            | Use via connectors                        |
| [Perplexity](/docs/ai-clients/perplexity)   | <Badge>Supported</Badge>                 | Upload via **Computer → Skills**          |
| [Manus](/docs/ai-clients/manus)             | <Badge>Skills</Badge> (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)

Go to **Customize → Skills** in Claude. Upload the [Adspirer SKILL.md](https://github.com/amekala/ads-mcp/blob/main/skills/ad-campaign-management/SKILL.md) content as a new skill. See the [Claude Setup Guide](/docs/ai-clients/claude#setup-2-minutes) for step-by-step instructions.

### 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

**Option A: One-command installer (recommended)** — installs MCP server, subagent, all 5 skills, and Cursor Rules. Run from your **system terminal**, not Cursor's built-in terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/cursor/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 ~/.cursor/skills
cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/skills/adspirer-ads ~/.cursor/skills/
cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/skills/adspirer-setup ~/.cursor/skills/
cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/skills/adspirer-performance-review ~/.cursor/skills/
cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/skills/adspirer-write-ad-copy ~/.cursor/skills/
cp -r /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/skills/adspirer-wasted-spend ~/.cursor/skills/
```

Cursor also supports Cursor Rules, which auto-trigger skills based on context (`alwaysApply: true`).

### 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

<Info>
  **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.
</Info>

## 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):

```
<platform>-expert-<your-account>/
├── 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.
</Note>

<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.
</Tip>

## 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:

<Steps>
  <Step title="Reading account structure">
    Pulls the campaigns, ad groups, budgets, and settings that exist right now.
  </Step>

  <Step title="Classifying the account's state">
    Works out what kind of account this is — scaling, stalled, newly built, seasonal.
  </Step>

  <Step title="Writing the account dossier">
    Writes `account-profile.md`: the state read, the priorities, the working cadence.
  </Step>

  <Step title="Writing your prompt book">
    Writes `PROMPTBOOK.md` against your actual campaigns and currency.
  </Step>

  <Step title="Assembling the skill package">
    Builds the folder, validates it against the Agent Skills spec, and packages the `.zip`.
  </Step>
</Steps>

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.
</Warning>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Preview, then buy">
    **Preview Expert** shows sample prompts before you pay. Buy one account, or tick several and
    check out together.
  </Step>

  <Step title="Wait for the build">
    A few minutes. You can close the tab — the kit keeps building.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<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.
</Tip>

## 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).
</Note>

### Claude (web and desktop)

<Steps>
  <Step title="Turn on code execution">
    Skills need it. In Claude, go to **Settings → Capabilities** and turn on code execution.
  </Step>

  <Step title="Open Customize → Skills">
    Go to [Customize → Skills](https://claude.ai/customize/connectors) in Claude and open the
    **Skills** tab.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.

<Steps>
  <Step title="Open Customize">
    Click **Customize** in the left sidebar. You'll see **Skills**, **Connectors**, and
    **Browse Plugins**.
  </Step>

  <Step title="Add the playbook under Skills">
    Add the unzipped folder as a skill. It sits alongside the two skills the Adspirer plugin
    installs — the free ones cover advertising in general, the playbook covers this account.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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 app](/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.
</Warning>

**Plus and Pro — paste into Project instructions**

<Steps>
  <Step title="Create a Project for this ad account">
    One project per ad account keeps the agent from mixing them up.
  </Step>

  <Step title="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.)
  </Step>

  <Step title="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.
  </Step>
</Steps>

**Business, Enterprise, Healthcare, Edu — upload it as a skill**

<Steps>
  <Step title="Open Skills">
    Go to **Skills** in ChatGPT and choose **Create → Upload from your computer**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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)
</Tip>

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**    | `<workspace>/.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.
</Warning>

* **`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.
</Note>

**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 `$<skill-name>` 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.
</Tip>

<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.
</Note>

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.**

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="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).
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Cowork">
    Cowork projects are **desktop-only and stored locally**, which suits the playbook well — the
    folder you downloaded can *be* the project.

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Add the skill">
        In **Customize → Skills**, add the playbook folder as a skill so it sits alongside the two
        skills the Adspirer plugin installs.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="ChatGPT">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Run a prompt">
        Start a chat in the project and paste the first prompt from `PROMPTBOOK.md`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<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.
</Tip>

## 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.

<Check>
  **Refreshes are free and unlimited.** Rebuilding is included in the original \$39 — there is no
  charge for a new version, ever.
</Check>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related documentation

<CardGroup>
  <Card title="Agent Skills" icon="book" href="/docs/agent-skills/skills">
    The 13 free skills every plan gets. The playbook builds on top of these.
  </Card>

  <Card title="Set Up Your Project" icon="folder-tree" href="/docs/guides/set-up-your-project">
    Where the playbook's instructions and context belong in a project.
  </Card>

  <Card title="Pricing" icon="tag" href="/docs/knowledge-base/pricing">
    Plans, tool calls, and where the one-time add-on sits.
  </Card>

  <Card title="Support" icon="life-ring" href="/docs/knowledge-base/support">
    Billing questions, failed builds, and anything else.
  </Card>
</CardGroup>


# 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.

<Card title="Get your free paid media skill" icon="gift" href="/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.
</Card>

## 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 app.

***

## What the skills guarantee

Every skill inherits the same safety contract from `adspirer-agent`:

<Card title="Nothing spends without your approval" icon="shield-check">
  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.
</Card>

* **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.
</Warning>

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

<CardGroup>
  <Card title="Claude Code & Cowork" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c" href="/docs/ai-clients/claude-code">
    Install the Adspirer plugin from the marketplace.
  </Card>

  <Card title="ChatGPT" icon="https://mintcdn.com/adspirer/tm56ipPRpt0nhwwQ/icons/openai.svg?fit=max&auto=format&n=tm56ipPRpt0nhwwQ&q=85&s=5392e998e6c23bb558c633f50ba4d629" href="/docs/ai-clients/chatgpt">
    Skills ship with the Adspirer app.
  </Card>

  <Card title="Codex" icon="https://mintcdn.com/adspirer/tm56ipPRpt0nhwwQ/icons/openai.svg?fit=max&auto=format&n=tm56ipPRpt0nhwwQ&q=85&s=5392e998e6c23bb558c633f50ba4d629" href="/docs/ai-clients/codex">
    Install the Adspirer plugin.
  </Card>

  <Card title="Cursor" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/cursor.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=fc2d5972cbda895e87b17aba40dcd1f1" href="/docs/ai-clients/cursor">
    Install the Adspirer plugin.
  </Card>
</CardGroup>

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.

<Prompt description="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.
</Prompt>

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

* <Badge>Read</Badge> Safe to run anytime. Pulls data, analyzes performance, provides insights. No spending impact.
* <Badge>Write</Badge> 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` — 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."
</Note>

`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 App Store app is the usual case — call it through any platform router instead:

```
google_ads(action: "execute", tool_name: "get_tool_schema", arguments: {"tool_names": ["<name>"]})
```

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)

<Expandable title="View all Google Ads tools">
  | Tool Name                           | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | ----------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `get_campaign_performance`          | <Badge>Read</Badge>  | Pull metrics for campaigns (spend, conversions, CPA, ROAS)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | `research_keywords`                 | <Badge>Read</Badge>  | Find keywords with real CPC data from Google Keyword Planner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | `create_search_campaign`            | <Badge>Write</Badge> | Launch Google Search campaign (created PAUSED)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | `create_pmax_campaign`              | <Badge>Write</Badge> | Launch Performance Max campaign (created PAUSED)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `analyze_wasted_spend`              | <Badge>Read</Badge>  | Find campaigns with wasted spend. Excludes learning-phase (\< 14 days) and insufficient-data (\< \$20 spend) campaigns from waste totals.                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `optimize_budget_allocation`        | <Badge>Read</Badge>  | Recommend budget shifts based on ROAS/CPA                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `analyze_search_terms`              | <Badge>Read</Badge>  | Review actual search queries triggering your ads                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `discover_existing_assets`          | <Badge>Read</Badge>  | Check if account has images/headlines/descriptions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | `suggest_ad_content`                | <Badge>Read</Badge>  | Generate ad headlines and descriptions (Google char limits)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | `validate_and_prepare_assets`       | <Badge>Read</Badge>  | Verify assets meet Google's requirements before campaign creation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | `pause_campaign`                    | <Badge>Write</Badge> | Stop campaigns or ad groups                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | `resume_campaign`                   | <Badge>Write</Badge> | Restart paused campaigns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  | `add_negative_keywords`             | <Badge>Write</Badge> | Block irrelevant search terms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
  | `bulk_update_keyword_status`        | <Badge>Write</Badge> | Pause or re-enable up to 300 keywords in one ad group in a single call. Reversible, and safe to re-run                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  | `add_sitelinks`                     | <Badge>Write</Badge> | Add sitelink extensions (accepts `text`/`headline` + `url`/`link` field names)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | `remove_sitelinks`                  | <Badge>Write</Badge> | Remove sitelink extensions from a campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | `add_callout_extensions`            | <Badge>Write</Badge> | Add callout extensions (short promotional blurbs)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | `remove_callouts`                   | <Badge>Write</Badge> | Remove callout extensions from a campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `add_structured_snippets`           | <Badge>Write</Badge> | Add structured snippet extensions (header + values)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  | `remove_structured_snippets`        | <Badge>Write</Badge> | Remove structured snippet extensions from a campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
  | `list_campaign_extensions`          | <Badge>Read</Badge>  | List everything attached at campaign level — sitelinks, callouts, structured snippets, call assets, business names, and images — each with its status                                                                                                                                                                                                                                                                                                                                                                                                           |
  | `list_call_assets`                  | <Badge>Read</Badge>  | 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`             | <Badge>Write</Badge> | 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`                | <Badge>Write</Badge> | 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`               | <Badge>Write</Badge> | Change a campaign's bid strategy — Maximize Clicks, Maximize Conversions, Target CPA, Target ROAS, or Target Impression Share (page position + target share, with an optional max CPC ceiling in the account's currency). 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`       | <Badge>Read</Badge>  | Diagnose sudden CPA spikes or CTR drops                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | `help_user_upload`                  | <Badge>Read</Badge>  | Guide user through asset upload process                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | `add_pmax_search_themes`            | <Badge>Write</Badge> | Add search themes to a PMax campaign's asset group (max 50). Guides Google's automated targeting.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  | `get_pmax_search_themes`            | <Badge>Read</Badge>  | View current search themes on a PMax campaign (max 50 per asset group)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  | `remove_pmax_search_themes`         | <Badge>Write</Badge> | Remove specific search themes from a PMax campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | `add_pmax_audience_signal`          | <Badge>Write</Badge> | Add audience signal to PMax campaign. Combines in-market, affinity, custom audiences, and user lists.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | `get_pmax_audience_signals`         | <Badge>Read</Badge>  | View current audience signals on a PMax campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `remove_pmax_audience_signal`       | <Badge>Write</Badge> | Remove an audience signal from a PMax campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | `search_audiences`                  | <Badge>Read</Badge>  | Search Google Ads audiences by keyword across in-market, affinity, and custom types                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  | `get_campaign_targeting`            | <Badge>Read</Badge>  | View location and language targeting on existing campaigns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | `pause_ad_group`                    | <Badge>Write</Badge> | Pause an individual ad group within a campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | `resume_ad_group`                   | <Badge>Write</Badge> | Resume a paused ad group                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  | `update_campaign`                   | <Badge>Write</Badge> | 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`           | <Badge>Write</Badge> | 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`                    | <Badge>Write</Badge> | 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`         | <Badge>Write</Badge> | 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`           | <Badge>Read</Badge>  | List all conversion actions in the account (purchases, form fills, calls) with status and tracking method                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `get_conversion_action_performance` | <Badge>Read</Badge>  | Pull conversion volume, value, and CPA broken down by conversion action — see which actions drive results                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `update_conversion_action`          | <Badge>Write</Badge> | 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`                | <Badge>Read</Badge>  | Per-ad metrics (Search/Display/Demand Gen/YouTube) with head-to-head comparison and ad-strength                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
  | `get_ad_creative`                   | <Badge>Read</Badge>  | Export an ad's headlines, descriptions, images, YouTube videos, and carousel cards                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  | `link_merchant_center`              | <Badge>Write</Badge> | Link a Google Merchant Center feed to enable Shopping                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | `get_merchant_center_links`         | <Badge>Read</Badge>  | List linked Merchant Center accounts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
  | `create_shopping_campaign`          | <Badge>Write</Badge> | Launch a Standard Shopping campaign from a Merchant Center feed (created PAUSED)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `add_shopping_ad_group`             | <Badge>Write</Badge> | Add an ad group to a Shopping campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  | `add_shopping_product_ad`           | <Badge>Write</Badge> | Add the product ad that surfaces feed items                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | `add_product_group`                 | <Badge>Write</Badge> | Build the product partition tree (subdivide by brand/category/item and bid per partition)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `create_app_campaign`               | <Badge>Write</Badge> | Launch a Universal App campaign — installs, engagement, or pre-registration (created PAUSED)                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | `create_demandgen_campaign`         | <Badge>Write</Badge> | Launch a Demand Gen campaign across YouTube, Shorts, Discover, and Gmail (created PAUSED)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
  | `add_pmax_asset_group`              | <Badge>Write</Badge> | Add an asset group to a Performance Max campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `get_pmax_asset_performance`        | <Badge>Read</Badge>  | See which PMax assets Google rates Best / Good / Low                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
  | `add_pmax_campaign_logo`            | <Badge>Write</Badge> | Link a square logo (and optionally the business name) at the campaign level, as Brand Guidelines PMax campaigns require                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | `get_pmax_conversion_goals`         | <Badge>Read</Badge>  | Read a campaign's conversion goals — category, origin, and whether each one is biddable                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  | ...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                                                                                                                                                                                                                                                                                                             |
</Expandable>

## LinkedIn Ads Tools (55)

<Expandable title="View all LinkedIn Ads tools">
  | Tool Name                                  | Type                 | Description                                                                                                                                                                                 |
  | ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `get_linkedin_campaign_performance`        | <Badge>Read</Badge>  | Pull metrics for LinkedIn campaigns (spend, clicks, conversions, cost per lead)                                                                                                             |
  | `get_linkedin_organizations`               | <Badge>Read</Badge>  | List user's LinkedIn company pages (required before campaign creation)                                                                                                                      |
  | `search_linkedin_targeting`                | <Badge>Read</Badge>  | Find B2B audiences by job title, industry, company size, seniority                                                                                                                          |
  | `research_business_for_linkedin_targeting` | <Badge>Read</Badge>  | Input competitor name, get targeting suggestions                                                                                                                                            |
  | `create_linkedin_image_campaign`           | <Badge>Write</Badge> | Launch sponsored content campaign (created PAUSED). Supports campaign groups and creative naming.                                                                                           |
  | `add_linkedin_campaign_to_group`           | <Badge>Write</Badge> | Add a campaign to an existing campaign group                                                                                                                                                |
  | `add_linkedin_carousel_creative`           | <Badge>Write</Badge> | Add carousel creative variations to campaigns                                                                                                                                               |
  | `discover_linkedin_assets`                 | <Badge>Read</Badge>  | Check existing creatives in LinkedIn (includes videos uploaded via Campaign Manager)                                                                                                        |
  | `validate_and_prepare_linkedin_assets`     | <Badge>Read</Badge>  | Verify images meet LinkedIn requirements (1200x627px or 1200x1200px)                                                                                                                        |
  | `add_linkedin_creative`                    | <Badge>Write</Badge> | Add new sponsored posts to existing campaigns                                                                                                                                               |
  | `analyze_linkedin_creative_performance`    | <Badge>Read</Badge>  | See which images/copy combinations perform best                                                                                                                                             |
  | `optimize_linkedin_budget`                 | <Badge>Read</Badge>  | Recommend budget reallocation based on cost per lead                                                                                                                                        |
  | `update_linkedin_campaign`                 | <Badge>Write</Badge> | Change budgets, bids, or targeting                                                                                                                                                          |
  | `pause_linkedin_campaign`                  | <Badge>Write</Badge> | Stop campaigns or ad groups                                                                                                                                                                 |
  | `explain_linkedin_anomaly`                 | <Badge>Read</Badge>  | Diagnose sudden CTR, CPC, or conversion rate changes                                                                                                                                        |
  | `manage_linkedin_conversions`              | <Badge>Write</Badge> | Set up and track conversion events (form fills, downloads)                                                                                                                                  |
  | `create_linkedin_video_campaign`           | <Badge>Write</Badge> | Launch a video sponsored content campaign (created PAUSED)                                                                                                                                  |
  | `create_linkedin_carousel_campaign`        | <Badge>Write</Badge> | Launch a multi-card carousel campaign (created PAUSED)                                                                                                                                      |
  | `create_linkedin_text_campaign`            | <Badge>Write</Badge> | Launch a text ad campaign (created PAUSED)                                                                                                                                                  |
  | `create_linkedin_campaign_group`           | <Badge>Write</Badge> | Create a campaign group with a shared budget/schedule                                                                                                                                       |
  | `estimate_linkedin_audience_size`          | <Badge>Read</Badge>  | Estimate reachable audience size for a targeting spec before launch                                                                                                                         |
  | `forecast_linkedin_campaign_supply`        | <Badge>Read</Badge>  | Forecast impressions, clicks, and spend at a given budget                                                                                                                                   |
  | `get_linkedin_audience_insights`           | <Badge>Read</Badge>  | See which job functions, industries, and seniorities engage                                                                                                                                 |
  | `clone_linkedin_campaign`                  | <Badge>Write</Badge> | 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 |
</Expandable>

## Meta Ads Tools (60)

<Expandable title="View all 60 Meta Ads tools">
  | Tool Name                           | Type                 | Description                                                                                                                                                                                                         |
  | ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `get_meta_campaign_performance`     | <Badge>Read</Badge>  | 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`             | <Badge>Read</Badge>  | Find audiences by interests, demographics, behaviors                                                                                                                                                                |
  | `select_meta_campaign_type`         | <Badge>Read</Badge>  | Choose: Image, Video, or Carousel based on creative assets                                                                                                                                                          |
  | `discover_meta_assets`              | <Badge>Read</Badge>  | Check existing creatives in Meta                                                                                                                                                                                    |
  | `list_meta_promotable_apps`         | <Badge>Read</Badge>  | 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`  | <Badge>Read</Badge>  | Verify image/video URLs meet Meta requirements (dimensions, file size)                                                                                                                                              |
  | `create_meta_image_campaign`        | <Badge>Write</Badge> | Launch single-image campaign (created PAUSED)                                                                                                                                                                       |
  | `create_meta_video_campaign`        | <Badge>Write</Badge> | Launch video campaign (created PAUSED)                                                                                                                                                                              |
  | `create_meta_carousel_campaign`     | <Badge>Write</Badge> | Launch multi-card carousel campaign (created PAUSED)                                                                                                                                                                |
  | `analyze_meta_ad_performance`       | <Badge>Read</Badge>  | Deep analysis of ad-level performance with recommendations                                                                                                                                                          |
  | `analyze_meta_audiences`            | <Badge>Read</Badge>  | 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`      | <Badge>Read</Badge>  | Identify ads losing effectiveness over time (declining CTR after 14+ days)                                                                                                                                          |
  | `optimize_meta_budget`              | <Badge>Read</Badge>  | Recommend budget reallocation based on ROAS/CPA                                                                                                                                                                     |
  | `optimize_meta_placements`          | <Badge>Read</Badge>  | Shift spend to best-performing placements (Feed, Stories, Reels)                                                                                                                                                    |
  | `explain_meta_anomaly`              | <Badge>Read</Badge>  | Diagnose sudden CPA spikes or CTR drops                                                                                                                                                                             |
  | `update_meta_campaign`              | <Badge>Write</Badge> | Change budgets, bids, targeting, or the campaign's bid strategy (capped strategies need an ad-set bid cap first)                                                                                                    |
  | `pause_meta_campaign`               | <Badge>Write</Badge> | Stop campaigns or ad sets                                                                                                                                                                                           |
  | `browse_meta_targeting`             | <Badge>Read</Badge>  | Explore Meta's targeting categories                                                                                                                                                                                 |
  | `list_meta_custom_audiences`        | <Badge>Read</Badge>  | View custom audiences (database lists, lookalikes, website, engagement)                                                                                                                                             |
  | `add_meta_ad_set`                   | <Badge>Write</Badge> | Add ad sets to existing campaigns (lifetime budgets, end dates, placements)                                                                                                                                         |
  | `add_meta_ad`                       | <Badge>Write</Badge> | Add ads to existing ad sets                                                                                                                                                                                         |
  | `analyze_meta_wasted_spend`         | <Badge>Read</Badge>  | Identify campaigns with poor ROAS and recommend cuts                                                                                                                                                                |
  | `get_meta_audience_insights`        | <Badge>Read</Badge>  | Audience breakdown by age, gender, and interests                                                                                                                                                                    |
  | `resume_meta_campaign`              | <Badge>Write</Badge> | Restart paused campaigns                                                                                                                                                                                            |
  | `list_meta_campaigns`               | <Badge>Read</Badge>  | List all campaigns with status and budget, shown in the ad account's own currency                                                                                                                                   |
  | `get_meta_campaign_details`         | <Badge>Read</Badge>  | Detailed campaign info — budgets, bids, and remaining spend in the account's own currency                                                                                                                           |
  | `list_meta_ad_sets`                 | <Badge>Read</Badge>  | List ad sets in a campaign, with budgets in the account's own currency                                                                                                                                              |
  | `list_meta_ads`                     | <Badge>Read</Badge>  | List ads in an ad set                                                                                                                                                                                               |
  | `update_meta_ad_set`                | <Badge>Write</Badge> | Update ad set budgets, targeting, or schedule                                                                                                                                                                       |
  | `update_meta_ad`                    | <Badge>Write</Badge> | Update ad creative or status                                                                                                                                                                                        |
  | `get_meta_ad_creatives`             | <Badge>Read</Badge>  | View creative details for ads                                                                                                                                                                                       |
  | `create_meta_dco_ad`                | <Badge>Write</Badge> | Create dynamic creative optimization ads                                                                                                                                                                            |
  | `duplicate_meta_campaign`           | <Badge>Write</Badge> | Duplicate an existing campaign                                                                                                                                                                                      |
  | `list_meta_lead_forms`              | <Badge>Read</Badge>  | View lead forms in your ad account                                                                                                                                                                                  |
  | `get_meta_lead_form_submissions`    | <Badge>Read</Badge>  | Pull lead submissions from a form                                                                                                                                                                                   |
  | `list_meta_pages`                   | <Badge>Read</Badge>  | 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`      | <Badge>Read</Badge>  | View connected Instagram accounts                                                                                                                                                                                   |
  | `list_meta_pixels`                  | <Badge>Read</Badge>  | View Meta Pixels in your ad account                                                                                                                                                                                 |
  | `get_meta_adset_performance`        | <Badge>Read</Badge>  | 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`                | <Badge>Read</Badge>  | List product catalogs available to the ad account (Advantage+ Catalog / DPA)                                                                                                                                        |
  | `list_meta_products`                | <Badge>Read</Badge>  | Browse products inside a catalog                                                                                                                                                                                    |
  | `list_meta_product_sets`            | <Badge>Read</Badge>  | View product sets (targetable subsets of a catalog)                                                                                                                                                                 |
  | `create_meta_product_set`           | <Badge>Write</Badge> | Create a product set with filter rules (e.g. "best sellers under \$50")                                                                                                                                             |
  | `validate_catalog_readiness`        | <Badge>Read</Badge>  | Pre-flight check: is the catalog + pixel data ready for retargeting or prospecting only?                                                                                                                            |
  | `create_meta_catalog_campaign`      | <Badge>Write</Badge> | Launch an Advantage+ Catalog (dynamic product ads) campaign (created PAUSED)                                                                                                                                        |
  | `add_meta_catalog_ad_set`           | <Badge>Write</Badge> | Add a catalog ad set (audience, budget, retargeting window)                                                                                                                                                         |
  | `add_meta_catalog_ad`               | <Badge>Write</Badge> | Add a catalog ad (creative format + product set)                                                                                                                                                                    |
  | `analyze_meta_catalog_performance`  | <Badge>Read</Badge>  | Product-level performance across the catalog                                                                                                                                                                        |
  | `get_meta_product_performance`      | <Badge>Read</Badge>  | Per-product spend, sales, and ROAS                                                                                                                                                                                  |
  | `detect_meta_catalog_waste`         | <Badge>Read</Badge>  | Flag products burning budget with no return                                                                                                                                                                         |
  | `diagnose_meta_catalog_funnel`      | <Badge>Read</Badge>  | Walk the catalog funnel (view → add-to-cart → purchase) to find leaks                                                                                                                                               |
  | `compare_meta_catalog_product_sets` | <Badge>Read</Badge>  | Compare performance across product sets                                                                                                                                                                             |
  | `update_meta_catalog_campaign`      | <Badge>Write</Badge> | Edit an existing catalog campaign — name, status, budget, spend cap, bid strategy, schedule, or swap the catalog                                                                                                    |
  | `update_meta_catalog_ad_set`        | <Badge>Write</Badge> | Edit a catalog ad set — budget, bidding, targeting, placements, schedule, or swap the product set, conversion event, or retargeting window                                                                          |
  | `update_meta_catalog_ad`            | <Badge>Write</Badge> | Edit a catalog ad — name, status, creative, copy, CTA, landing page, or product set                                                                                                                                 |
  | `get_meta_pixel_stats`              | <Badge>Read</Badge>  | 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`              | <Badge>Read</Badge>  | Account-level app-promotion performance: total installs and cost per install (CPI)                                                                                                                                  |
  | `get_meta_app_campaigns`            | <Badge>Read</Badge>  | Installs and CPI per app campaign, each compared to your account average                                                                                                                                            |
  | `get_meta_app_adsets`               | <Badge>Read</Badge>  | Installs and CPI per ad set — which audiences and placements deliver the cheapest installs                                                                                                                          |
  | `get_meta_app_creatives`            | <Badge>Read</Badge>  | Installs and CPI per creative, ranked cheapest first                                                                                                                                                                |
</Expandable>

## TikTok Ads Tools (37)

<Expandable title="View all TikTok Ads tools">
  | Tool Name                            | Type                 | Description                                                                                                                                                                                                 |
  | ------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `get_tiktok_campaign_performance`    | <Badge>Read</Badge>  | Campaign summary with TikTok-specific video and engagement metrics                                                                                                                                          |
  | `get_tiktok_ad_performance`          | <Badge>Read</Badge>  | Ad-level analysis with hook rate, video completion, and engagement                                                                                                                                          |
  | `analyze_tiktok_wasted_spend`        | <Badge>Read</Badge>  | ROAS-based waste detection with campaign status awareness                                                                                                                                                   |
  | `optimize_tiktok_budget`             | <Badge>Read</Badge>  | Budget allocation recommendations based on performance                                                                                                                                                      |
  | `detect_tiktok_creative_fatigue`     | <Badge>Read</Badge>  | Hook rate decline as the primary fatigue signal                                                                                                                                                             |
  | `explain_tiktok_anomaly`             | <Badge>Read</Badge>  | Diagnose sudden changes in TikTok campaign performance                                                                                                                                                      |
  | `get_tiktok_audience_insights`       | <Badge>Read</Badge>  | Age/gender breakdown with CPA ranking                                                                                                                                                                       |
  | `analyze_tiktok_geo_performance`     | <Badge>Read</Badge>  | Country-level performance analysis                                                                                                                                                                          |
  | `list_tiktok_ad_videos`              | <Badge>Read</Badge>  | List videos already in your TikTok library with the `video_id` needed to reuse one                                                                                                                          |
  | `list_tiktok_pixels`                 | <Badge>Read</Badge>  | List TikTok Pixels with the numeric `pixel_id` and the exact optimization events each supports                                                                                                              |
  | `list_tiktok_lead_pages`             | <Badge>Read</Badge>  | 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`             | <Badge>Read</Badge>  | Browse existing images in the TikTok Asset Library                                                                                                                                                          |
  | `validate_and_prepare_tiktok_assets` | <Badge>Read</Badge>  | Verify videos meet TikTok requirements (9:16 vertical, 5-60 seconds)                                                                                                                                        |
  | `upload_tiktok_images`               | <Badge>Write</Badge> | Upload images to TikTok Asset Library                                                                                                                                                                       |
  | `create_tiktok_video_campaign`       | <Badge>Write</Badge> | Launch an In-Feed video campaign from a video URL, an existing `video_id`, or an organic post (created PAUSED)                                                                                              |
  | `add_tiktok_ad_group`                | <Badge>Write</Badge> | Add ad group with full targeting to existing campaign                                                                                                                                                       |
  | `add_tiktok_ad`                      | <Badge>Write</Badge> | Add ad to existing ad group (video or Spark Ad; images ride along as supporting assets)                                                                                                                     |
  | `search_tiktok_targeting`            | <Badge>Read</Badge>  | Search interests, keywords, regions, languages, action categories, carriers, device models                                                                                                                  |
  | `list_tiktok_campaigns`              | <Badge>Read</Badge>  | List all campaigns with status, objective, and budget                                                                                                                                                       |
  | `get_tiktok_campaign_details`        | <Badge>Read</Badge>  | Detailed campaign info                                                                                                                                                                                      |
  | `update_tiktok_campaign`             | <Badge>Write</Badge> | Update campaign name, budget, budget mode                                                                                                                                                                   |
  | `pause_tiktok_campaign`              | <Badge>Write</Badge> | Pause a TikTok campaign                                                                                                                                                                                     |
  | `resume_tiktok_campaign`             | <Badge>Write</Badge> | Resume a paused TikTok campaign                                                                                                                                                                             |
  | `list_tiktok_ad_groups`              | <Badge>Read</Badge>  | List ad groups, filter by campaign                                                                                                                                                                          |
  | `update_tiktok_ad_group`             | <Badge>Write</Badge> | Update ad group name, budget, targeting, schedule                                                                                                                                                           |
  | `pause_tiktok_ad_group`              | <Badge>Write</Badge> | Pause a TikTok ad group                                                                                                                                                                                     |
  | `resume_tiktok_ad_group`             | <Badge>Write</Badge> | Resume a paused TikTok ad group                                                                                                                                                                             |
  | `list_tiktok_ads`                    | <Badge>Read</Badge>  | List ads, filter by ad group or campaign                                                                                                                                                                    |
  | `pause_tiktok_ad`                    | <Badge>Write</Badge> | Pause a TikTok ad                                                                                                                                                                                           |
  | `resume_tiktok_ad`                   | <Badge>Write</Badge> | Resume a paused TikTok ad                                                                                                                                                                                   |
  | `explain_tiktok_objective`           | <Badge>Read</Badge>  | 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                                                                                  |
</Expandable>

## Amazon Ads Tools (61)

<Expandable title="View Amazon Ads tools">
  | Tool Name                                                                                                        | Type                 | Description                                                                                                            |
  | ---------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
  | `list_amazon_profiles`                                                                                           | <Badge>Read</Badge>  | List advertiser profiles across NA, EU, and FE                                                                         |
  | `list_amazon_campaigns`                                                                                          | <Badge>Read</Badge>  | List Sponsored Products / Brands / Display campaigns                                                                   |
  | `create_amazon_sp_campaign`                                                                                      | <Badge>Write</Badge> | Create a Sponsored Products campaign (created PAUSED)                                                                  |
  | `create_amazon_sb_campaign`                                                                                      | <Badge>Write</Badge> | Create a Sponsored Brands campaign (created PAUSED)                                                                    |
  | `create_amazon_sd_campaign`                                                                                      | <Badge>Write</Badge> | Create a Sponsored Display campaign (created PAUSED)                                                                   |
  | `update_amazon_campaigns`                                                                                        | <Badge>Write</Badge> | Update name, budget, or bidding across campaign types                                                                  |
  | `pause_amazon_campaigns` / `resume_amazon_campaigns`                                                             | <Badge>Write</Badge> | Pause or resume campaigns                                                                                              |
  | `delete_amazon_campaigns`                                                                                        | <Badge>Write</Badge> | Archive campaigns                                                                                                      |
  | `list_amazon_ad_groups` / `create_amazon_ad_groups` / `update_amazon_ad_groups` / `delete_amazon_ad_groups`      | <Badge>Write</Badge> | Manage Sponsored Products ad groups                                                                                    |
  | `list_amazon_product_ads` / `add_amazon_product_ads` / `update_amazon_product_ads` / `delete_amazon_product_ads` | <Badge>Write</Badge> | Manage product ads (your ASINs/SKUs)                                                                                   |
  | `list_amazon_keywords` / `add_amazon_keywords` / `update_amazon_keywords` / `delete_amazon_keywords`             | <Badge>Write</Badge> | Manage keywords for manual targeting                                                                                   |
  | `list_amazon_negative_keywords` / `add_amazon_negative_keywords` / `delete_amazon_negative_keywords`             | <Badge>Write</Badge> | Block irrelevant search terms                                                                                          |
  | `list_amazon_targets` / `add_amazon_targets` / `update_amazon_targets` / `delete_amazon_targets`                 | <Badge>Write</Badge> | Manage product and category targeting                                                                                  |
  | `list_amazon_sb_ad_groups`                                                                                       | <Badge>Read</Badge>  | List Sponsored Brands ad groups                                                                                        |
  | `create_amazon_sb_ad` / `list_amazon_sb_ads` / `update_amazon_sb_ads`                                            | <Badge>Write</Badge> | Manage Sponsored Brands ads (all 7 ad types)                                                                           |
  | `list_amazon_sb_creatives` / `update_amazon_sb_creative`                                                         | <Badge>Write</Badge> | Manage Sponsored Brands creative assets                                                                                |
  | `list_amazon_sb_keywords` / `add_amazon_sb_keywords` / `update_amazon_sb_keywords` / `delete_amazon_sb_keywords` | <Badge>Write</Badge> | Manage Sponsored Brands keywords                                                                                       |
  | `add_amazon_sb_negative_keywords`                                                                                | <Badge>Write</Badge> | Add negative keywords to Sponsored Brands                                                                              |
  | `list_amazon_sb_targets` / `add_amazon_sb_targets` / `update_amazon_sb_targets`                                  | <Badge>Write</Badge> | Manage Sponsored Brands targets                                                                                        |
  | `add_amazon_sb_themes`                                                                                           | <Badge>Write</Badge> | Add theme-based targets to Sponsored Brands                                                                            |
  | `upload_amazon_asset`                                                                                            | <Badge>Write</Badge> | Upload a creative asset (e.g. a brand logo)                                                                            |
  | `search_amazon_assets`                                                                                           | <Badge>Read</Badge>  | Find existing assets in your Amazon library                                                                            |
  | `get_amazon_moderation`                                                                                          | <Badge>Read</Badge>  | 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`                                          | <Badge>Read</Badge>  | Sponsored Products keyword & bid suggestions                                                                           |
  | `get_amazon_sb_keyword_recommendations` / `get_amazon_sb_bid_recommendations`                                    | <Badge>Read</Badge>  | Sponsored Brands keyword & bid suggestions                                                                             |
  | `get_amazon_budget_recommendations` / `get_amazon_budget_usage`                                                  | <Badge>Read</Badge>  | Budget recommendations and consumption                                                                                 |
  | `get_amazon_campaign_performance`                                                                                | <Badge>Read</Badge>  | Impressions, clicks, spend, sales, ACOS, ROAS                                                                          |
  | `get_amazon_search_terms`                                                                                        | <Badge>Read</Badge>  | The search terms shoppers used to find your ads                                                                        |
  | `get_amazon_report`                                                                                              | <Badge>Read</Badge>  | Retrieve an async Amazon (Reporting v3) report by ID                                                                   |
  | `analyze_amazon_wasted_spend`                                                                                    | <Badge>Read</Badge>  | Find keywords/targets spending without converting                                                                      |
  | `optimize_amazon_budget`                                                                                         | <Badge>Read</Badge>  | Budget reallocation based on ACOS and ROAS                                                                             |
  | `get_amazon_product_performance`                                                                                 | <Badge>Read</Badge>  | Per-ASIN/SKU performance breakdown                                                                                     |
  | `analyze_amazon_placements`                                                                                      | <Badge>Read</Badge>  | Compare performance across placements                                                                                  |
  | `analyze_amazon_targeting`                                                                                       | <Badge>Read</Badge>  | Evaluate keyword and product targeting effectiveness                                                                   |
  | `get_amazon_purchased_products`                                                                                  | <Badge>Read</Badge>  | Cross-sell view of what shoppers actually bought                                                                       |
  | `amazon_unified_api`                                                                                             | <Badge>Write</Badge> | Direct Amazon Advertising API access for advanced operations                                                           |
</Expandable>

## ChatGPT Ads Tools (36)

<Expandable title="View all ChatGPT Ads tools">
  | Tool Name                                                                         | Type                 | Description                                                                                                                                                                                                                            |
  | --------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `list_chatgpt_accounts`                                                           | <Badge>Read</Badge>  | 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`                                 | <Badge>Read</Badge>  | List campaigns or get one in detail                                                                                                                                                                                                    |
  | `create_chatgpt_campaign`                                                         | <Badge>Write</Badge> | 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`                                                         | <Badge>Write</Badge> | Change budget, bidding, schedule, or targeting. Only the targeting side you name changes — the other is preserved — and any field OpenAI ignored is reported rather than claimed as applied                                            |
  | `pause_chatgpt_campaign` / `resume_chatgpt_campaign`                              | <Badge>Write</Badge> | Stop serving, or resume to go live                                                                                                                                                                                                     |
  | `archive_chatgpt_campaign`                                                        | <Badge>Write</Badge> | Archive a campaign. Permanent — OpenAI has no un-archive, so this asks you to confirm first                                                                                                                                            |
  | `list_chatgpt_ad_groups` / `get_chatgpt_ad_group`                                 | <Badge>Read</Badge>  | List ad groups or get one                                                                                                                                                                                                              |
  | `create_chatgpt_ad_group`                                                         | <Badge>Write</Badge> | Add an ad group (bid + targeting)                                                                                                                                                                                                      |
  | `update_chatgpt_ad_group`                                                         | <Badge>Write</Badge> | Update bid, schedule, or targeting                                                                                                                                                                                                     |
  | `pause_chatgpt_ad_group` / `resume_chatgpt_ad_group` / `archive_chatgpt_ad_group` | <Badge>Write</Badge> | Control ad-group state. Archiving is permanent and asks you to confirm                                                                                                                                                                 |
  | `list_chatgpt_ads` / `get_chatgpt_ad`                                             | <Badge>Read</Badge>  | List ads or get one                                                                                                                                                                                                                    |
  | `create_chatgpt_ad`                                                               | <Badge>Write</Badge> | Create a chat\_card ad (title, body, image, URL)                                                                                                                                                                                       |
  | `update_chatgpt_ad`                                                               | <Badge>Write</Badge> | Update an ad's creative                                                                                                                                                                                                                |
  | `pause_chatgpt_ad` / `resume_chatgpt_ad` / `archive_chatgpt_ad`                   | <Badge>Write</Badge> | Control ad state. Archiving is permanent and asks you to confirm                                                                                                                                                                       |
  | `launch_chatgpt_ad`                                                               | <Badge>Write</Badge> | One-shot: campaign → ad group → upload → ad (PAUSED)                                                                                                                                                                                   |
  | `upload_chatgpt_creative`                                                         | <Badge>Write</Badge> | Upload a chat\_card image from a public URL                                                                                                                                                                                            |
  | `chatgpt_geo_lookup`                                                              | <Badge>Read</Badge>  | Resolve a location to a targeting value                                                                                                                                                                                                |
  | `get_chatgpt_performance`                                                         | <Badge>Read</Badge>  | Impressions, clicks, spend, CTR, CPC                                                                                                                                                                                                   |
  | `get_chatgpt_insights`                                                            | <Badge>Read</Badge>  | Scoped insights (fields, filters, sort, pagination)                                                                                                                                                                                    |
  | `set_chatgpt_conversions_config` / `get_chatgpt_conversions_config`               | <Badge>Write</Badge> | Configure or review Pixel / Conversions API                                                                                                                                                                                            |
  | `list_chatgpt_conversion_events`                                                  | <Badge>Read</Badge>  | Conversion events being recorded                                                                                                                                                                                                       |
  | `test_chatgpt_conversion`                                                         | <Badge>Write</Badge> | Send a test conversion to verify tracking                                                                                                                                                                                              |
  | `list_chatgpt_pixels`                                                             | <Badge>Read</Badge>  | Your measurement pixels, each with its Source ID (`cds_…`) and short Pixel ID                                                                                                                                                          |
  | `create_chatgpt_pixel`                                                            | <Badge>Write</Badge> | 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`                                              | <Badge>Write</Badge> | 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`                                                     | <Badge>Read</Badge>  | Conversion event settings with event type, source, and attribution window                                                                                                                                                              |
  | `create_chatgpt_event_setting`                                                    | <Badge>Write</Badge> | 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                                                                      |
</Expandable>

## Audit Tools (1)

| Tool Name                   | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audit_conversion_tracking` | <Badge>Read</Badge> | 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` | <Badge>Read</Badge> | 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)

<Expandable title="View all 16 Automation tools">
  ### Watch Agent (Proactive Signal)

  | Tool Name              | Type                 | Description                                                                                                                                                                                   |
  | ---------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `run_watch_now`        | <Badge>Read</Badge>  | 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`  | <Badge>Read</Badge>  | 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` | <Badge>Write</Badge> | 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` | <Badge>Read</Badge>  | List all actions staged by the Watch Agent that are waiting for your approval (pending\_approval, executed, rejected, expired).                                                               |
  | `manage_action`        | <Badge>Write</Badge> | Approve or reject a specific pending action staged by the Watch Agent.                                                                                                                        |

  ### Monitors & Alerts

  | Tool Name             | Type                 | Description                                                                                                                                                                                                                |
  | --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `create_monitor`      | <Badge>Write</Badge> | 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`       | <Badge>Read</Badge>  | View all active performance monitors (excludes deleted/tombstoned alerts).                                                                                                                                                 |
  | `delete_monitor`      | <Badge>Write</Badge> | Remove a monitoring alert permanently.                                                                                                                                                                                     |
  | `get_monitor_history` | <Badge>Read</Badge>  | View all past trigger events for a specific alert — timestamps, metric values, and what triggered it.                                                                                                                      |
  | `test_monitor`        | <Badge>Read</Badge>  | 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`        | <Badge>Write</Badge> | Schedule daily/weekly performance summaries via email. Briefs now attach a PDF.                                                                                                     |
  | `generate_report_now`   | <Badge>Read</Badge>  | Generate an ad-hoc cross-platform performance report immediately.                                                                                                                   |
  | `list_scheduled_tasks`  | <Badge>Read</Badge>  | View all scheduled briefs, monitors, and reports with status.                                                                                                                       |
  | `manage_scheduled_task` | <Badge>Write</Badge> | 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`        | <Badge>Write</Badge> | Launch an async AI-powered research job (competitor analysis, keyword research, market landscape, audience insights, campaign strategy).                                            |
  | `get_research_status`   | <Badge>Read</Badge>  | Check the status and results of an in-progress or completed research job.                                                                                                           |
</Expandable>

## 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`      | <Badge>Read</Badge>  | Pull GA4 property data — sessions, conversions, traffic sources, landing-page performance, real-time. See the [Google Analytics integration page](/docs/integrations/google-analytics).                      |
| `klaviyo`               | <Badge>Read</Badge>  | Pull Klaviyo campaigns (email + SMS), flows, segments, profiles, and metrics. See the [Klaviyo integration page](/docs/integrations/klaviyo).                                                                |
| `google_search_console` | <Badge>Write</Badge> | 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`    | <Badge>Write</Badge> | 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.

## System Tools (5)

| Tool Name                 | Type                 | Description                                                                                                                                                                                                                                       |
| ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_connections_status`  | <Badge>Read</Badge>  | Show all connected ad platforms and account IDs                                                                                                                                                                                                   |
| `list_connected_accounts` | <Badge>Read</Badge>  | 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`  | <Badge>Write</Badge> | 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`        | <Badge>Read</Badge>  | Check Adspirer plan limits (tool calls used/remaining this month)                                                                                                                                                                                 |
| `get_business_profile`    | <Badge>Read</Badge>  | 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).

<Expandable title="View all 9 Diagnostic & Helper tools">
  | Tool Name                 | Type                | Description                                                                  |
  | ------------------------- | ------------------- | ---------------------------------------------------------------------------- |
  | `start_here`              | <Badge>Read</Badge> | The single best next step for your exact state, with a worked example prompt |
  | `suggest_next_action`     | <Badge>Read</Badge> | Ranks the highest-value things to do right now from your live data           |
  | `list_what_i_can_do`      | <Badge>Read</Badge> | Personalized capability menu by goal, filtered to your connected platforms   |
  | `get_campaign_spec`       | <Badge>Read</Badge> | Required fields, character limits, and allowed values for a campaign type    |
  | `validate_campaign_draft` | <Badge>Read</Badge> | Dry-run validates a campaign draft against the platform spec (no write)      |
  | `explain_platform_error`  | <Badge>Read</Badge> | Translates a raw platform error into a plain-language cause and fix          |
  | `why_did_this_fail`       | <Badge>Read</Badge> | Summarizes your recent failed actions and the errors behind them             |
  | `verify_campaign_is_live` | <Badge>Read</Badge> | Real live check that a campaign exists and is serving (all 6 platforms)      |
  | `usage_value_summary`     | <Badge>Read</Badge> | Tool calls used vs. included this period and what they accomplished          |
</Expandable>

`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.
</Note>

## 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
</Warning>

## 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/<id>
                             → 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
</Warning>

## 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
</Warning>

## 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
</Warning>

## 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
</Warning>

## 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
</Warning>

## 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
</Warning>

## 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)
</Tip>

### Safety Rules

<Warning>
  * Must select organization first (no org = campaign creation fails)
  * Minimum \$10/day budget
  * Image dimensions: 1200x627px or 1200x1200px
</Warning>

## 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)
   → set up daily or weekly 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)
</Note>

## 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"]`
</Note>

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

Two ways to connect ChatGPT to Adspirer: the one-click App Store app, or a custom MCP connector that always has the newest tools — Amazon Ads, ChatGPT Ads, Google Analytics, Search Console. Manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads with 400+ tools.

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 — the difference is how current the tool list is.

|           | **App Store app**                                                    | **Custom connector**                                                                       |
| --------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Setup     | Open **Apps**, search "Adspirer," click **Connect**. About a minute. | Turn on **Developer mode**, click **Create app**, paste the server URL. About two minutes. |
| Platforms | Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads                       | All of those **plus Amazon Ads, ChatGPT Ads, Google Analytics, and Google Search Console** |
| New tools | Wait for OpenAI to approve each app update                           | Available the day they ship                                                                |
| Warnings  | None                                                                 | ChatGPT labels Developer mode **Elevated risk** (expected — explained below)               |

<Note>
  **The App Store app is behind.** Every update to a ChatGPT app goes through OpenAI's review, and our latest one hasn't been published yet. Until it is, the App Store version has no Amazon Ads, ChatGPT Ads, Google Analytics, or Google Search Console tools. If you need any of those — or want every new tool the day it ships — use the **Custom connector** tab below.
</Note>

<Frame>
  <iframe title="Run Google Ads Directly from ChatGPT with Adspirer" />
</Frame>

## Prerequisites

<Note>
  * A ChatGPT **Plus**, **Pro**, **Business**, or **Enterprise** account (apps and Developer mode 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
</Note>

## Setup

<Tabs>
  <Tab title="App Store (1 minute)">
    The quick path. Fine if you only run Google Ads, Meta Ads, LinkedIn Ads, or TikTok Ads and can wait for new tools to clear OpenAI's review.

    <Steps>
      <Step title="Open Apps and search for Adspirer">
        In ChatGPT, open **Apps** from the left sidebar (or **Settings → Apps**). In the search box, type **Adspirer** and select it from the results.

        <img alt="ChatGPT Apps directory with 'Adspirer' typed in the search box, showing the Adspirer app — Create, launch & analyze ads" />
      </Step>

      <Step title="Click Connect">
        On the Adspirer app page, click **Connect** in the top right.

        <img alt="Adspirer app listing page in the ChatGPT App Store with the Connect button" />
      </Step>

      <Step title="Sign in with Adspirer">
        The **Add Adspirer to ChatGPT** dialog appears. 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.

        <img alt="Add Adspirer to ChatGPT dialog with the Sign in with Adspirer button and a Reference memories and chats toggle" />

        <Info>
          The dialog includes a **"Reference memories and chats"** toggle. Enabling it lets ChatGPT use your past conversations and memories when working with Adspirer. Leave it on (recommended) or off based on your preference.
        </Info>
      </Step>

      <Step title="Start managing ads">
        Return to ChatGPT and start a new conversation. Mention **@adspirer** (or just ask about your campaigns) and ChatGPT will call Adspirer's tools.

        ```
        @adspirer check my connected ad platforms
        ```

        You should see a table of your connected accounts across all platforms with account IDs, names, and connection status.
      </Step>
    </Steps>

    <Check>
      You're connected through the App Store app. Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads tools are available in any new chat — mention **@adspirer** to call them.
    </Check>
  </Tab>

  <Tab title="Custom connector (latest tools)">
    The direct path. ChatGPT talks to `mcp.adspirer.com` itself, so you get every tool — Amazon Ads, ChatGPT Ads, Google Analytics, Google Search Console, and whatever ships next — without waiting on an app review.

    <Steps>
      <Step title="Open Settings → Apps">
        In ChatGPT, click your profile icon, open **Settings**, and click **Apps** in the left navigation. Scroll to the bottom of the app list to find **Advanced settings**.

        <img alt="ChatGPT Settings with Apps selected in the left nav, showing the Advanced settings row with a Create app button and a Drafts section" />
      </Step>

      <Step title="Turn on Developer mode">
        Click **Advanced settings** and switch **Developer mode** on. You don't need to touch **Enforce CSP in developer mode**.

        <img alt="ChatGPT Advanced settings with the Developer mode toggle enabled and an Elevated Risk badge" />

        <Warning>
          ChatGPT marks Developer mode **ELEVATED RISK** because it lets you add apps OpenAI hasn't reviewed — that's the whole point of this path. Adspirer's custom connector is the same server behind the reviewed App Store app. You sign in on adspirer.ai with OAuth; ChatGPT never sees your ad-platform passwords.
        </Warning>
      </Step>

      <Step title="Create the app">
        Click **Create app** — it's next to **Advanced settings** in the app list, and at the top of the Advanced settings screen. Fill in:

        | Field              | Value                                                                           |
        | ------------------ | ------------------------------------------------------------------------------- |
        | **Name**           | `Adspirer-MCP` — any name works. This is what you'll @mention in chats.         |
        | **Description**    | Optional, e.g. `Google, Meta, Amazon, LinkedIn, TikTok Ads`                     |
        | **Logo**           | Optional. Any square image — it only changes how the app looks in your sidebar. |
        | **MCP Server URL** | `https://mcp.adspirer.com/mcp`                                                  |
        | **Authentication** | **OAuth**                                                                       |

        <Info>
          Choosing OAuth expands a section with client registration, scopes, and similar fields. Leave all of it alone — ChatGPT discovers the right values from the server.
        </Info>

        Tick **I understand and want to continue**, then click **Add**.
      </Step>

      <Step title="Sign in with Adspirer">
        Click **Connect**. Your browser opens Adspirer's login page — sign in (or create an account), approve ChatGPT, and link the ad platforms you want to manage. Then return to ChatGPT.
      </Step>

      <Step title="Start managing ads">
        Start a new conversation. Mention the app by the name you gave it, or just ask about your campaigns.

        ```
        @Adspirer-MCP check my connected ad platforms
        ```

        You should see a table of your connected accounts across all platforms with account IDs, names, and connection status.
      </Step>
    </Steps>

    <Check>
      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.
    </Check>
  </Tab>
</Tabs>

<Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
</Card>

## Connection Details

Both paths talk to the same server. The App Store app fills these in for you; for the custom connector — or any other MCP client — you paste them yourself:

```
Name:           Adspirer-MCP (any name)
MCP Server URL: https://mcp.adspirer.com/mcp
Authentication: OAuth
Required Plan:  ChatGPT Plus, Pro, Business, or Enterprise
```

## 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 the custom connector; the App Store app is missing Amazon Ads, ChatGPT Ads, Google Analytics, and Google Search Console until OpenAI publishes the next update.

| 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>

<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.
</Tip>

## Example Prompts

### Research Keywords

<Prompt description="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
</Prompt>

### Create a Campaign

<Prompt description="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
</Prompt>

### Audit Performance

<Prompt description="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.
</Prompt>

### Amazon Ads Wasted Spend

<Prompt description="ACOS-based wasted spend analysis — custom connector only.">
  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.
</Prompt>

### Ads vs. On-Site Behavior

<Prompt description="Correlate Google Ads spend with GA4 sessions and conversions — custom connector only.">
  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?
</Prompt>

<Tip>
  Mention the app in your message — **@adspirer** for the App Store app, or whatever you named your custom connector — 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..."
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="Which should I use — the App Store app or the custom connector?">
    If you only run Google Ads, Meta Ads, LinkedIn Ads, or TikTok Ads, the App Store app is the easiest: one click, no warnings. If you need **Amazon Ads**, **ChatGPT Ads**, **Google Analytics**, or **Google Search Console** — or you want new tools the day they ship rather than after OpenAI's next app review — use the custom connector. Both connect to the same Adspirer account and the same server, so nothing about your ad platform connections changes.
  </Accordion>

  <Accordion title="Can I have both installed at once?">
    Yes. They share one Adspirer account and one tool-call quota. If both are installed, @mention the one you want in a chat so ChatGPT doesn't pick the other. Once the App Store app catches up you can remove the custom one, or keep it — it never falls behind.
  </Accordion>

  <Accordion title="Why does ChatGPT show an Elevated Risk warning for Developer mode?">
    Developer mode lets you add apps OpenAI hasn't reviewed, so ChatGPT warns about all of them. Adspirer's custom connector is the same server that backs the reviewed App Store app. Authentication is OAuth — you sign in on adspirer.ai and ChatGPT holds a token, not your Google, Meta, or Amazon passwords. If you'd rather not enable Developer mode, the App Store app is the alternative, minus the platforms it's missing.
  </Accordion>

  <Accordion title="I installed the App Store app and ChatGPT can't find any Amazon Ads, ChatGPT Ads, or Google Analytics tools.">
    That's expected. The App Store listing hasn't been updated since those shipped, and it won't have them until OpenAI approves the next version. Follow the **Custom connector** tab above — about two minutes — and the tools are there.
  </Accordion>

  <Accordion title="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 App Store app'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. The custom connector never hits this — it always carries the current tool list.
  </Accordion>

  <Accordion title="What are ChatGPT apps?">
    ChatGPT apps let ChatGPT securely connect to external services. They use the Model Context Protocol (MCP) — the same open standard used by Claude. Adspirer's app 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).
  </Accordion>

  <Accordion title="Which ChatGPT plans support apps and Developer mode?">
    Apps are available on Plus and Pro for individual users, and on Business and Enterprise with admin controls. Developer mode is on the same plans; on Business and Enterprise, ask your workspace admin if you don't see the toggle under **Advanced settings**. The free ChatGPT tier has neither.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I use Adspirer with both ChatGPT and Claude?">
    Yes. Your Adspirer account works across all platforms. Connect the same MCP URL to ChatGPT, Claude, Perplexity, Claude Code, Cursor, or any MCP-compatible client. Your ad account connections carry across all of them.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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 ChatGPT 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 **Settings → Apps**, find Adspirer (App Store) or your custom app under **Drafts**, and reset permissions.
    2. **Reconnect:**
       * *App Store app* — **Settings → Apps**, find Adspirer, click **Disconnect**, then reopen the Adspirer app and click **Connect** again.
       * *Custom connector* — **Settings → Apps → Advanced settings**, remove the app you created, then **Create app** again with `https://mcp.adspirer.com/mcp` and sign in.
    3. **Refresh your Adspirer session:** Go to [adspirer.ai](https://adspirer.ai), log out, log back in, then return to ChatGPT.

    ChatGPT apps and connectors 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.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Amazon Ads Integration](/docs/ad-platforms/amazon-ads) — Sponsored Products, Brands, and Display (custom connector)
* [Google Analytics 4 Integration](/docs/integrations/google-analytics) — Correlate ad spend with on-site behavior (custom connector)
* [Claude Chat App Setup](/docs/ai-clients/claude) — Claude's MCP 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

Install Adspirer Ads & Performance Marketing Agent from Claude's Connector Directory. Manage Google, Meta, Amazon, ChatGPT, LinkedIn, and TikTok Ads with 400+ tools.

<Note>
  **Adspirer is now available in Claude's Connector Directory** as **Adspirer Ads & Performance Marketing Agent**. Search for it, add it, and connect—there is no custom connector URL to paste for the standard setup.
</Note>

The best MCP experience for advertising. Install Adspirer from Claude's Connector Directory and manage campaigns with Claude's native tool invocation and progress streaming.

<Frame>
  <iframe title="Claude Cowork + Adspirer: 30 Days of Ads Analyzed in One Prompt" />
</Frame>

## 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))
  * At least one ad platform account: Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, or TikTok Ads
</Note>

## Setup (2 Minutes)

<Steps>
  <Step title="Find Adspirer in the Connector Directory">
    Open [Claude Connectors](https://claude.ai/customize/connectors), click **Add**, and search for the connector's full name:

    ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Adspirer Ads & Performance Marketing Agent
    ```

    You can also navigate manually to **Customize → Connectors → Add**. Select the **Community** connector published by **Adspirer**.

    <Frame>
      <img alt="Claude Connector Directory search results showing Adspirer Ads & Performance Marketing Agent as a Community connector" />
    </Frame>
  </Step>

  <Step title="Add the Connector">
    Open the listing and review its description and available tools. Click **Add to your team**. Depending on your Claude plan and workspace permissions, the button may already say **Connect**; if so, continue to the next step.

    <Frame>
      <img alt="Adspirer Ads & Performance Marketing Agent listing in Claude with the Add to your team button" />
    </Frame>
  </Step>

  <Step title="Connect Your Adspirer Account">
    Once the connector is available to you or your team, click **Connect** on its listing.

    <Frame>
      <img alt="Adspirer Ads & Performance Marketing Agent listing in Claude with the Connect button" />
    </Frame>

    Your browser opens Adspirer's OAuth flow. Sign in or create an account, authorize Claude, and link the ad platforms you want to manage.
  </Step>

  <Step title="Complete Authentication">
    Finish the OAuth flow and return to Claude. If you close the authorization window early, Claude shows a **You started connecting...but didn't finish** message. Click **Connect** on that screen to resume.

    <Frame>
      <img alt="Claude connector screen explaining that the Adspirer connection was started but not finished, with a Connect button to resume" />
    </Frame>
  </Step>

  <Step title="Verify the Connection">
    Return to **Customize → Connectors**. **Adspirer Ads & Performance Marketing Agent** should appear in the connector list with a checkmark in the **Status** column.

    <Frame>
      <img alt="Claude Connectors page showing Adspirer Ads & Performance Marketing Agent with a connected status checkmark" />
    </Frame>
  </Step>

  <Step title="Add the Adspirer Skill (Recommended)">
    Skills teach Claude the *right way* to use Adspirer's 400+ tools — research before creating, validate before launching, confirm before spending. Without a skill, Claude guesses the tool order. With it, Claude follows proven advertising workflows with safety rules.

    Open the raw skill file, select all, and copy:

    <Card title="Copy SKILL.md from GitHub" icon="copy" href="https://raw.githubusercontent.com/amekala/ads-mcp/main/skills/ad-campaign-management/SKILL.md">
      Opens the raw file — press ⌘A then ⌘C (or Ctrl+A, Ctrl+C) to copy the full content.
    </Card>

    **Then add it to Claude:**

    1. Go to [Customize → Skills](https://claude.ai/customize/connectors) in Claude
    2. Click the **Skills** tab
    3. Click **Upload skill** and paste the copied content
    4. Set the skill name to `ad-campaign-management`
    5. Set the description to: `Manage ad campaigns across Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads. Use when the user wants to analyze campaign performance, research keywords, create campaigns, optimize budgets, or manage ad accounts via the Adspirer MCP server.`

    <Tip>
      The skill file is maintained in the [ads-mcp GitHub repository](https://github.com/amekala/ads-mcp/blob/main/skills/ad-campaign-management/SKILL.md) and always reflects the latest tools and workflows. Check back for updates as new platforms and tools are added.
    </Tip>
  </Step>

  <Step title="Start a New Chat">
    Return to Claude and click **Connect apps** below the text input. Enable **Adspirer Ads & Performance Marketing Agent**, then start managing your campaigns with natural language.

    ```
    Check my connected ad platforms
    ```

    You should see a table showing your connected accounts across all platforms with account IDs, names, and connection status.
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

<Check>
  You're connected. Claude can now use the tools from **Adspirer Ads & Performance Marketing Agent** when you ask about your ad campaigns.
</Check>

## Connector Details

<Tabs>
  <Tab title="Connector Directory">
    ```
    Name:           Adspirer Ads & Performance Marketing Agent
    Developer:      Adspirer
    Listing:        Community
    Authentication: OAuth
    Required Plan:  Claude Pro, Max, Team, or Enterprise
    ```

    Install this listing directly from Claude's Connector Directory.
  </Tab>

  <Tab title="Manual MCP Fallback">
    If the directory listing is unavailable in your region or workspace, add a custom connector with this URL:

    ```
    MCP Server URL: https://mcp.adspirer.com/mcp
    Authentication: OAuth (auto-discovered)
    ```
  </Tab>

  <Tab title="Claude Code (Terminal)">
    For developer/terminal setup, see the full [Claude Code Setup Guide](/docs/ai-clients/claude-code). One command installs the MCP connector along with slash commands, skills, and an agent:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    /plugin install adspirer-ads-agent@claude-community
    ```
  </Tab>
</Tabs>

## 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>

<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.
</Tip>

## Example Prompts

### Research Keywords

<Prompt description="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
</Prompt>

### Create a Campaign

<Prompt description="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
</Prompt>

### Cross-Platform Audit

<Prompt description="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.
</Prompt>

## Team & Enterprise Setup

For organizations using Claude Team or Enterprise:

**Admin Setup:**

1. Go to **Admin Settings → Customize → Connectors**
2. Click **Add** and search for **Adspirer Ads & Performance Marketing Agent**
3. Open the Community connector published by **Adspirer**
4. Click **Add to your team** and enable it for the organization

**Team Member Setup:**

1. Go to **Customize → Connectors**
2. Find **Adspirer Ads & Performance Marketing Agent** → Click **Connect**
3. Complete OAuth to link your individual 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

<AccordionGroup>
  <Accordion title="Do I need to add a custom connector or paste the MCP URL?">
    No. For the standard Claude setup, install **Adspirer Ads & Performance Marketing Agent** directly from the Connector Directory. The manual MCP URL is only a fallback if the directory listing is unavailable in your region or workspace.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I use Adspirer with both Claude and ChatGPT?">
    Yes. Your Adspirer account works across all supported AI clients. Install **Adspirer Ads & Performance Marketing Agent** from Claude's Connector Directory and the official Adspirer app from ChatGPT's App Store. Your Adspirer account and ad platform connections carry across both.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [ChatGPT Setup](/docs/ai-clients/chatgpt) — ChatGPT's MCP connector
* [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.
</Tip>

<Frame>
  <iframe title="Adspirer + Claude Code: Create Google Ads Campaigns From Your Terminal" />
</Frame>

## 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)
</Note>

## 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).
</Note>

<Steps>
  <Step title="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**.

    <Frame>
      <img alt="Claude Code plugin manager Marketplaces tab with + Add Marketplace option" />
    </Frame>

    Enter the marketplace source and press Enter:

    ```
    amekala/ads-mcp
    ```

    <Frame>
      <img alt="Add Marketplace dialog with amekala/ads-mcp entered as the GitHub source" />
    </Frame>

    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
    ```
  </Step>

  <Step title="Find and Install the Plugin">
    Switch to the **Discover** tab — you'll see **Adspirer Advertising Agent**.

    <Frame>
      <img alt="Plugin Discover tab showing Adspirer Advertising Agent plugin" />
    </Frame>

    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
    ```
  </Step>

  <Step title="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.

    <Frame>
      <img alt="Claude Code output confirming Adspirer Advertising Agent installed, followed by reload-plugins output" />
    </Frame>
  </Step>

  <Step title="Authenticate with Adspirer">
    The plugin's MCP server needs a one-time OAuth sign-in. Type `/mcp` to open the MCP server manager.

    <Frame>
      <img alt="Typing the /mcp slash command in Claude Code" />
    </Frame>

    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**.

    <Frame>
      <img alt="Adspirer OAuth authorization page showing requested scopes" />
    </Frame>

    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.

    <Frame>
      <img alt="MCP server manager showing plugin:adspirer-advertising-agent:adspirer connected" />
    </Frame>
  </Step>

  <Step title="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.

    <Frame>
      <img alt="Adspirer slash commands in Claude Code" />
    </Frame>
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

### 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.

<Check>
  You're connected. Claude Code now has access to 400+ advertising tools from your terminal.
</Check>

## 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

<Prompt description="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)
</Prompt>

### Google PMax Campaign

<Prompt description="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
</Prompt>

### Meta Ads Campaign

<Prompt description="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
</Prompt>

### LinkedIn Ads Campaign

<Prompt description="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]
</Prompt>

### Cross-Platform Audit

<Prompt description="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.
</Prompt>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

<Info>
  **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** | Browse Plugins → Install Adspirer in **Customize** (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                     |
</Info>

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.

<Frame>
  <iframe title="How to connect Claude Cowork with Adspirer" />
</Frame>

## 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, LinkedIn Ads, or TikTok Ads
</Note>

## Setup (5 Minutes)

The recommended path is **Browse Plugins → Install Adspirer**. This installs the connector along with 5 slash commands, two skills, and a Performance Marketing Agent in one step.

### 1. Open Cowork and Customize

<Steps>
  <Step title="Open Claude Cowork">
    Open the Claude desktop app (or claude.ai) and click the **Cowork** tab at the top.

    <Frame>
      <img alt="Claude Cowork tab" />
    </Frame>
  </Step>

  <Step title="Go to Customize">
    Click **Customize** in the left sidebar. You'll see options for Skills, Connectors, and Browse Plugins.

    <Frame>
      <img alt="Claude Cowork Customize page" />
    </Frame>
  </Step>
</Steps>

### 2. Browse Plugins and install Adspirer

The plugin bundles the Adspirer connector with 5 slash commands, two skills, and a Performance Marketing Agent — the full agent experience in one install.

<Steps>
  <Step title="Browse Plugins and Install Adspirer">
    Click **Browse plugins** and search for **adspirer**. You'll see the **adspirer-ads-agent** plugin in the official marketplace. Click on it to install.
  </Step>

  <Step title="Review Plugin Contents">
    Once installed, you'll see everything included in the Adspirer plugin:

    **Commands** — Slash commands that trigger proven advertising workflows:

    * `/performance-review` — Run a cross-platform performance review
    * `/refresh-brand-context` — Re-scan brand docs and update CLAUDE.md
    * `/setup` — Set up your brand workspace
    * `/wasted-spend` — Find and fix wasted ad spend across all platforms
    * `/write-ad-copy` — Write brand-voice-compliant ad copy

    **Skills** — Two skills that teach Claude advertising best practices

    **Agents** — A Performance Marketing Agent that specializes in using Adspirer's 400+ tools

    <Frame>
      <img alt="Adspirer plugin commands, skills, and agents" />
    </Frame>
  </Step>

  <Step title="Install the Connector">
    In the left sidebar under the Adspirer plugin, click **Connectors**. You'll see the **adspirer** connector. Click **Install**.

    <Warning>
      **Install button grayed out?** Two common causes:

      * **You're on a VPN** — Many corporate VPNs block the connector handshake to `mcp.adspirer.com`. Disconnect from the VPN and try again.
      * **IT hasn't enabled external connectors** — On Claude Team/Enterprise, external MCP connectors are off by default and won't appear on the intranet until your workspace admin enables them. Ask your IT or workspace admin to allow external connectors for Adspirer.
    </Warning>

    <Frame>
      <img alt="Adspirer connector with Install button" />
    </Frame>
  </Step>

  <Step title="Add the Connector">
    A popup appears with the connector pre-filled (name: `adspirer`, URL: `https://mcp.adspirer.com/mcp`). Click **Add**.

    <Frame>
      <img alt="Add custom connector dialog" />
    </Frame>
  </Step>

  <Step title="Authenticate with Adspirer">
    Your browser opens and redirects to Adspirer's OAuth page. Sign in (or create an account) and link your Google Ads, Meta Ads, Amazon Ads, ChatGPT Ads, LinkedIn Ads, and/or TikTok accounts.

    Once authorized, the connector status flips to **connected** with all 400+ tools 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 — and remember Adspirer also creates every new campaign paused by default.
    </Tip>

    <Frame>
      <img alt="Connected Adspirer connector showing tools" />
    </Frame>

    <Tip>
      If the connector doesn't show as connected right away, restart Claude and check again.
    </Tip>
  </Step>
</Steps>

### 3. Open a brand folder and try it

<Steps>
  <Step title="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.

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

<Check>
  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.
</Check>

## 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

<Prompt description="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
</Prompt>

### Create a Campaign

<Prompt description="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
</Prompt>

### Cross-Platform Audit

<Prompt description="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.
</Prompt>

## 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 5 slash commands, two skills, and a Performance Marketing Agent that knows how to use all 400+ Adspirer tools in the right order with safety rules — all installed in one click from Browse Plugins.
* **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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What does the Adspirer plugin include?">
    The plugin installs: the MCP server connection, 5 slash commands (setup, performance-review, write-ad-copy, wasted-spend, refresh-brand-context), 2 advertising skills, and 1 performance marketing agent — all bundled into a single Browse Plugins → Install step.
  </Accordion>

  <Accordion title="The Install 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 Install button becomes clickable.
    * **Your IT team hasn't enabled external connectors.** On Claude Team/Enterprise, external MCP connectors are off by default and won't appear on the intranet until your workspace admin enables them. Ask IT or your workspace admin to allow external connectors for Adspirer.

    Once either is resolved, the Install button activates and you can proceed.
  </Accordion>

  <Accordion title="Claude says &#x22;No OAuth flow is in progress&#x22;">
    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.

    **Workaround (one-time, \~30 seconds):** in Claude, go to **Settings → Connectors → Add custom connector**, enter `https://mcp.adspirer.com/mcp`, and connect from there. The OAuth flow completes cleanly, and the connector stays linked afterward.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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.
</Note>

## 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
</Note>

## Setup

<Tabs>
  <Tab title="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.
    </Note>

    <Steps>
      <Step title="Open Codex">
        Launch a Codex session in your terminal:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        codex
        ```
      </Step>

      <Step title="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`.
      </Step>

      <Step title="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**.
      </Step>

      <Step title="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`.
      </Step>

      <Step title="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`
      </Step>

      <Step title="Try It Now">
        <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Shell Installer">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="Restart Codex">
        Close and reopen Codex to load the new config.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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`
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual Setup">
    <Steps>
      <Step title="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
        ```
      </Step>

      <Step title="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/
        ```
      </Step>

      <Step title="Add the MCP Server">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        codex mcp add adspirer --url https://mcp.adspirer.com/mcp
        ```
      </Step>

      <Step title="Install Agent Config">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        mkdir -p ~/.codex/agents
        cp agents/performance-marketing-agent.toml ~/.codex/agents/
        ```
      </Step>

      <Step title="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"
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Check>
  You're connected. Codex now has 400+ advertising tools available for autonomous and interactive use.
</Check>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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.
</Note>

## 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
</Note>

## Setup (3 Messages)

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.

    <Frame>
      <img alt="ChatGPT desktop app with Codex selected in the top-left dropdown, showing the Codex sidebar and a new chat asking what to work on" />
    </Frame>
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Message 2 — install the plugin">
    ```
    install plugin
    ```

    Codex confirms **Installed and verified** — `adspirer-ads-agent@adspirer-marketplace`.

    <Frame>
      <img alt="Codex chat showing the marketplace add command confirmed as registered, then 'install plugin' confirmed as installed and verified for adspirer-ads-agent" />
    </Frame>
  </Step>

  <Step title="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`.

    <Frame>
      <img alt="Codex chat confirming Adspirer OAuth is complete and verified, with status enabled, authentication OAuth, and the mcp.adspirer.com endpoint" />
    </Frame>
  </Step>

  <Step title="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.
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

<Check>
  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.
</Check>

## 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.

<Steps>
  <Step title="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.

    <Frame>
      <img alt="ChatGPT desktop app Computer use settings with Any App, Google Chrome (browser extension installed), and Microsoft Excel toggled on, and Locked use off" />
    </Frame>

    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.
  </Step>

  <Step title="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.

    <Frame>
      <img alt="ChatGPT desktop app Computer history settings, toggled on, with a Pause button and a Permissions row with a Choose button" />
    </Frame>

    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.
  </Step>
</Steps>

<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.
</Warning>

### 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.

<Steps>
  <Step title="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-<brand>/`, containing:

    ```
    AGENTS.md
    PROMPTBOOK.md
    README.md
    SKILL.md
    agents/google-ads-expert-<brand>.md
    agents/google-ads-expert-<brand>.toml
    references/account-profile.md
    references/working-with-adspirer.md
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<Prompt description="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.
</Prompt>

### Find Wasted Spend

<Prompt description="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.
</Prompt>

### Write Ad Copy in Your Brand Voice

<Prompt description="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.
</Prompt>

### Create a Campaign

<Prompt description="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
</Prompt>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I also use the Adspirer app in ChatGPT itself?">
    Yes. The [ChatGPT app](/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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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

Connect Cursor IDE to Adspirer MCP. Manage Google, Meta, Amazon, ChatGPT Ads, LinkedIn, and TikTok Ads from your editor with 400+ tools, 5 skills, and a marketing subagent.

Manage ads from your code editor. One command to install, 400+ tools, automatic workflow rules, zero context-switching.

## Prerequisites

<Note>
  * [Cursor IDE](https://cursor.com/) installed (v2.4+ recommended for subagent support)
  * [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
</Note>

## Setup

<Tabs>
  <Tab title="Quick Install (Recommended)">
    **Run this from your system terminal** (Terminal.app, iTerm, Windows Terminal, etc.), **not** Cursor's built-in terminal.

    <Steps>
      <Step title="Run the Installer">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/cursor/adspirer/install.sh)
        ```

        This installs the performance marketing subagent, all 5 skills, and the MCP server config automatically.
      </Step>

      <Step title="Restart Cursor">
        Close and reopen Cursor to load the new MCP config.
      </Step>

      <Step title="Authenticate with Adspirer">
        1. Open **Cursor Settings > MCP**
        2. Find `adspirer` in the server list
        3. Click on it to authenticate — a browser window opens for Adspirer login
        4. Sign in, authorize access, and return to Cursor

        If `adspirer` is missing, add it manually: **Cursor Settings > MCP > Add Server** with URL:

        ```
        https://mcp.adspirer.com/mcp
        ```
      </Step>

      <Step title="Set Up Your Brand Workspace">
        Open your brand folder and switch to **Agent mode** (not Ask or Edit mode):

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        cd ~/Clients/YourBrand
        cursor .
        ```

        Then say:

        ```
        set up my brand workspace
        ```

        The agent will connect to your ad accounts, scan for brand docs, pull live campaign data, and create `BRAND.md`. If it doesn't trigger automatically, type: `/adspirer-setup`
      </Step>

      <Step title="Try It Now">
        <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual Setup">
    <Steps>
      <Step title="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/cursor/adspirer
        ```
      </Step>

      <Step title="Install Subagent and Skills">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        mkdir -p ~/.cursor/agents ~/.cursor/skills
        cp .cursor/agents/performance-marketing-agent.md ~/.cursor/agents/
        cp -r .cursor/skills/adspirer-ads ~/.cursor/skills/
        cp -r .cursor/skills/adspirer-setup ~/.cursor/skills/
        cp -r .cursor/skills/adspirer-performance-review ~/.cursor/skills/
        cp -r .cursor/skills/adspirer-write-ad-copy ~/.cursor/skills/
        ```
      </Step>

      <Step title="Add the MCP Server">
        Add to `~/.cursor/mcp.json`:

        ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
        {
          "mcpServers": {
            "adspirer": {
              "url": "https://mcp.adspirer.com/mcp"
            }
          }
        }
        ```

        Or use **Cursor Settings > MCP > Add Server** with URL `https://mcp.adspirer.com/mcp`.
      </Step>

      <Step title="Copy Rules (Optional)">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        cd ~/Clients/YourBrand
        mkdir -p .cursor/rules
        cp /tmp/ads-mcp/plugins/cursor/adspirer/.cursor/rules/*.mdc .cursor/rules/
        ```
      </Step>

      <Step title="Restart and Authenticate">
        Restart Cursor. Open **Cursor Settings > MCP**, find `adspirer`, and click to authenticate via browser.
      </Step>

      <Step title="Set Up Your Brand Workspace">
        Open your brand folder, switch to **Agent mode**, and say:

        ```
        set up my brand workspace
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Check>
  You're connected. Cursor now has access to 400+ advertising tools with automatic workflow enforcement.
</Check>

## 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`             | 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 Cursor will match the right skill automatically.

## What You Can Do

400+ tools across 6 ad platforms, accessible from Cursor's AI 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

<Prompt description="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
</Prompt>

### Google PMax Campaign

<Prompt description="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
</Prompt>

### Meta Ads Creative Testing

<Prompt description="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
</Prompt>

### LinkedIn B2B Lead Gen

<Prompt description="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]
</Prompt>

### Cross-Platform Performance Report

<Prompt description="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
</Prompt>

## How Cursor Rules Improve Your Workflow

If you installed the Cursor Rule (included in both the one-command installer and manual install), here's what changes:

### Before Rules:

**You:** "Create a Google Ads campaign for running shoes"

**Cursor:** Immediately calls `create_search_campaign` with generic parameters — fails because no keyword research, no asset validation.

### After Rules:

**You:** "Create a Google Ads campaign for running shoes"

**Cursor:** Automatically follows the workflow:

1. Calls `get_connections_status` (verify you're managing the right account)
2. Calls `research_keywords` with "running shoes" seed keywords
3. Shows you CPC data and keyword suggestions
4. Calls `discover_existing_assets` (check if you have images/headlines already)
5. Calls `validate_and_prepare_assets` (make sure assets meet Google's requirements)
6. Calls `create_search_campaign` with validated data
7. **Asks for your confirmation** before actually creating the campaign

Rules turn one vague prompt into a complete, validated workflow. You still control the final decision — nothing launches without your approval.

## Safety Features

* **All campaigns created PAUSED:** Review before they spend money
* **User confirmation required:** Cursor asks before any write action
* **Read-before-write enforcement:** Skills prevent campaign creation without research
* **Connection checks:** Always verifies you're managing the correct account first
* **No automatic retries:** If something fails, Cursor waits for your input instead of retrying blindly

## Troubleshooting

| Problem                                   | Solution                                                                                       |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Install fails with permission/hooks error | Run the install from your **system terminal**, not Cursor's built-in terminal (it's sandboxed) |
| MCP server not showing                    | Open Cursor Settings > MCP > Add server with URL `https://mcp.adspirer.com/mcp`                |
| MCP connection error                      | Click the server in Settings > MCP to re-authenticate via browser                              |
| Authentication failed                     | Remove and re-add the MCP server in Cursor Settings                                            |
| OAuth window doesn't open                 | Check browser pop-up blocker. Try restarting Cursor.                                           |
| No ad platforms connected                 | Connect platforms at [adspirer.com](https://www.adspirer.com)                                  |
| Skills not showing                        | Verify: `ls ~/.cursor/skills/` — should show `adspirer-*` directories                          |
| Subagent not triggering                   | Ensure you're in **Agent mode** (not Ask or Edit). Try `/adspirer-setup` directly.             |
| 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

<AccordionGroup>
  <Accordion title="What's the difference between global and per-project config?">
    **Global (`~/.cursor/mcp.json`):** Adspirer works in every Cursor project. Use this if you manage ads regularly.

    **Per-project (`.cursor/mcp.json`):** Adspirer only works in that specific project. Use this if you're working on a client's codebase and want ad management tools only for that client.
  </Accordion>

  <Accordion title="Can I use Adspirer with Cursor Composer?">
    Yes. Cursor Composer (multi-file editing mode) has full access to Adspirer tools. You can ask Composer to analyze campaigns, generate reports, and save the output as markdown files in your project — all in one flow.
  </Accordion>

  <Accordion title="Do I need both Skills and Cursor Rules?">
    No, but they complement each other. Skills teach Cursor *how* to use the tools. Cursor Rules enforce *when* and *why* to use them. The one-command installer includes both.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Claude Code Setup Guide](/docs/ai-clients/claude-code)
* [Google Ads Integration Guide](/docs/ad-platforms/google-ads)
* [Google Ads + Adspirer Integration](https://www.adspirer.com/integrations/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 `.cursor/agents/` (\$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
</Note>

## Setup

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

### 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.

<Check>
  You're connected. Gemini CLI now has access to 400+ advertising tools from your terminal.
</Check>

## 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

<Prompt description="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)
</Prompt>

### Google PMax Campaign

<Prompt description="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
</Prompt>

### Cross-Platform Audit

<Prompt description="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.
</Prompt>

## 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

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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 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
</Note>

## Setup

<Steps>
  <Step title="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.
    </Warning>
  </Step>

  <Step title="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**
  </Step>

  <Step title="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`
    </Tip>
  </Step>

  <Step title="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:

    <Tabs>
      <Tab title="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
      </Tab>

      <Tab title="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
      </Tab>
    </Tabs>

    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.
    </Tip>
  </Step>

  <Step title="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.
    </Note>
  </Step>

  <Step title="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.

    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

## 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

<Steps>
  <Step title="You send a prompt in Manus" icon="message">
    Ask Manus anything — "Show my campaign performance", "Create a Google Search campaign", or "Set up a daily performance brief".
  </Step>

  <Step title="Manus uses Adspirer skills and tools" icon="wand-magic-sparkles">
    Manus reads the imported skill instructions, discovers 400+ Adspirer MCP tools, and follows the correct workflow order automatically.
  </Step>

  <Step title="Adspirer MCP server handles authentication" icon="key">
    Your API key (sent via the `Authorization` header) is validated server-side via SHA-256 hash lookup. Your raw key is never stored.
  </Step>

  <Step title="Data is fetched from your ad accounts" icon="chart-line">
    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.
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="'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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="'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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup>
  <Card title="Performance Marketing Agent Skill" icon="chart-line" href="https://github.com/amekala/ads-mcp/blob/main/skills/performance-marketing-agent/SKILL.md">
    Full skill reference for performance analysis, optimization, and reporting workflows.
  </Card>

  <Card title="Ad Campaign Management Skill" icon="bullhorn" href="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.
  </Card>

  <Card title="Explore All Tools" icon="wrench" href="/docs/agent-skills/tools">
    Browse the full catalog of 400+ advertising tools available through Manus.
  </Card>

  <Card title="Ad Platform Setup" icon="plug" href="/docs/ad-platforms/google-ads">
    Connect your Google Ads, Meta Ads, LinkedIn, or TikTok accounts.
  </Card>
</CardGroup>


# 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))
</Note>

## Setup

<Tabs>
  <Tab title="Local Install">
    Install OpenClaw on your own machine (Mac, Linux, or Windows with WSL).

    <Steps>
      <Step title="Install OpenClaw">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        npm install -g openclaw
        ```
      </Step>

      <Step title="Initialize OpenClaw">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        openclaw init
        ```

        This creates `~/.openclaw/openclaw.json` with default settings.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Authenticate with Adspirer">
        <Tabs>
          <Tab title="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.
          </Tab>

          <Tab title="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.
          </Tab>
        </Tabs>
      </Step>

      <Step title="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.
      </Step>

      <Step title="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
      </Step>

      <Step title="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.
      </Step>

      <Step title="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"

        <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
        </Card>
      </Step>
    </Steps>

    <Check>
      You're connected. OpenClaw is now a fully configured advertising agent with built-in workflows.
    </Check>
  </Tab>

  <Tab title="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).
    </Tip>

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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).
      </Step>

      <Step title="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**
      </Step>

      <Step title="Access Your Server's Terminal">
        In Hostinger's hPanel, open the **Terminal** or **SSH Access** for your VPS.
      </Step>

      <Step title="Install the Adspirer Plugin">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        openclaw plugins install openclaw-adspirer
        ```
      </Step>

      <Step title="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
        ```
      </Step>

      <Step title="Restart the Gateway">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        openclaw gateway restart
        ```
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Connect WhatsApp (Optional)">
        In the OpenClaw dashboard, go to **Channels** → click **Show QR code** → scan with WhatsApp (**Settings → Linked Devices → Link a Device**).
      </Step>

      <Step title="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.

        <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
        </Card>
      </Step>
    </Steps>

    <Check>
      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.
    </Check>
  </Tab>
</Tabs>

## 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).

<Steps>
  <Step title="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.
    </Warning>
  </Step>

  <Step title="Authenticate with the API Key">
    <Tabs>
      <Tab title="CLI Flag">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        openclaw adspirer login --token sk_live_your_token_here
        ```
      </Tab>

      <Tab title="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.
      </Tab>

      <Tab title="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
        ```
      </Tab>

      <Tab title="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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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
  </Step>

  <Step title="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...
    ```
  </Step>
</Steps>

<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.
</Note>

## 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 <key>`      | 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.
</Note>

| 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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.

<Frame>
  <iframe title="Manage Google Ads from Perplexity Computer with Adspirer MCP" />
</Frame>

## 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
</Note>

## Setup (2 Minutes)

<Steps>
  <Step title="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.

    <Frame>
      <img alt="Perplexity Computer home page showing Computer sidebar with Connectors option" />
    </Frame>
  </Step>

  <Step title="Open Connectors">
    Click **Connectors** in the left sidebar to see all available connectors. Then click **+ Custom connector** in the top-right corner.

    <Frame>
      <img alt="Perplexity Connectors page showing available connectors and Custom connector button" />
    </Frame>
  </Step>

  <Step title="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**.

    <Frame>
      <img alt="Add custom connector dialog with Adspirer name, description, and MCP server URL filled in" />
    </Frame>
  </Step>

  <Step title="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.

    <Frame>
      <img alt="Adspirer OAuth authorization page showing requested permissions" />
    </Frame>
  </Step>

  <Step title="Verify Connection">
    After authorization, you'll return to the Connectors page. Adspirer appears with a green checkmark indicating it's connected and ready.

    <Frame>
      <img alt="Perplexity Connectors page showing Adspirer connected with green checkmark" />
    </Frame>
  </Step>

  <Step title="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:

    <Card title="Download SKILL.md from GitHub" icon="download" href="https://github.com/amekala/ads-mcp/raw/main/shared/skills/adspirer-ads/SKILL.md">
      Click to download the `adspirer-ads` skill file.
    </Card>

    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

    <Frame>
      <img alt="Perplexity Upload skill dialog showing file requirements and drag-and-drop area" />
    </Frame>

    5. The skill appears as **adspirer-ads** in your Skills list. Perplexity applies it automatically when you ask about advertising.

    <Frame>
      <img alt="Perplexity skill detail showing adspirer-ads skill with SKILL.md file and description" />
    </Frame>

    <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.
    </Tip>
  </Step>

  <Step title="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.
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

<Check>
  You're connected. Perplexity Computer will automatically use Adspirer tools when you ask about your ad campaigns.
</Check>

## 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

<Prompt description="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.
</Prompt>

### Cross-Platform Performance Audit

<Prompt description="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.
</Prompt>

### Market Research + Campaign

<Prompt description="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.
</Prompt>

## 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.
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Documentation

* [ChatGPT Setup](/docs/ai-clients/chatgpt) — ChatGPT's MCP connector
* [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
</Note>

## Setup (3 Minutes)

<Steps>
  <Step title="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.
  </Step>

  <Step title="Restart Windsurf">
    MCP configs load on startup. Close Windsurf completely and reopen it.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Try It Now">
    <Card title="Sign up for Adspirer — free to start" icon="rocket" href="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.
    </Card>
  </Step>
</Steps>

<Check>
  You're connected. Windsurf now has access to 400+ advertising tools from the AI chat panel.
</Check>

## 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

<Prompt description="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
</Prompt>

### Google PMax Campaign

<Prompt description="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
</Prompt>

### Meta Ads Campaign

<Prompt description="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
</Prompt>

### LinkedIn Ads Campaign

<Prompt description="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]
</Prompt>

### Wasted Spend Audit

<Prompt description="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.
</Prompt>

## 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.
</Note>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## 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.

<Card title="Get your API key" icon="key" href="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.
</Card>

|                         |                                                                      |
| :---------------------- | :------------------------------------------------------------------- |
| **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.

<CardGroup>
  <Card title="Slack ChatOps for campaigns" icon="slack">
    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.
  </Card>

  <Card title="Daily account briefings" icon="sun">
    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.
  </Card>

  <Card title="Portfolio rollups for owners" icon="chart-pie">
    Weekly health summary across every client account — who's over/under target, budget utilization, top / bottom 5 performers, per-manager breakdown.
  </Card>

  <Card title="Alert thresholds & auto-pause" icon="bell">
    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.
  </Card>

  <Card title="SaaS product embedding" icon="rocket">
    Your app creates a starter campaign for every new customer during onboarding. `Idempotency-Key` makes signup retries safe even under network flakiness.
  </Card>

  <Card title="Headless CI / scheduled ops" icon="code-branch">
    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.
  </Card>
</CardGroup>

### 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.
</Tip>

## 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/<tool_name>/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

<Tabs>
  <Tab title="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": {}}'
    ```
  </Tab>

  <Tab title="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"])
    ```
  </Tab>

  <Tab title="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);
    ```
  </Tab>

  <Tab title="n8n">
    Use the **HTTP Request** node:

    | Field             | Value                                                            |
    | :---------------- | :--------------------------------------------------------------- |
    | Method            | `POST`                                                           |
    | URL               | `https://api.adspirer.ai/api/v1/tools/<tool_name>/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.
  </Tab>
</Tabs>

## 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.
</Tip>

### 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

<CardGroup>
  <Card title="Google Ads" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/google-ads.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=523927ffe08f8a180fe35b7cdd522541" href="/docs/api-reference/google-ads/create-search-campaign">
    51 tools — campaigns, ad groups, keywords, extensions, Performance Max, Demand Gen
  </Card>

  <Card title="Meta Ads" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/meta.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=3d0d90257e6e8b1d7b22b4ad6ea959b8" href="/docs/api-reference/meta-ads/add-meta-ad">
    36 tools — image, video, carousel, DCO, audiences, placements
  </Card>

  <Card title="LinkedIn Ads" icon="https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/icons/linkedin.svg?fit=max&auto=format&n=vhaKM86uNtBGo98V&q=85&s=59bacb73f680a3ecf7df34306ad2ba04" href="/docs/api-reference/linkedin-ads/add-linkedin-campaign-to-group">
    45 tools — campaigns, creatives, audiences, conversion tracking
  </Card>

  <Card title="TikTok Ads" icon="https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/icons/tiktok.svg?fit=max&auto=format&n=vhaKM86uNtBGo98V&q=85&s=a76c6259ebbd339771558f26cf72baac" href="/docs/api-reference/tiktok-ads/add-tiktok-ad">
    29 tools — campaigns, ad groups, ads, geo, optimization events
  </Card>

  <Card title="Monitoring & Reporting" icon="chart-line" href="/docs/api-reference/monitoring/create-monitor">
    13 tools — cross-platform performance, wasted spend, search terms
  </Card>

  <Card title="Account Management" icon="user-gear" href="/docs/api-reference/general/list-connected-accounts">
    3 tools — list connected accounts, connection status, usage
  </Card>
</CardGroup>

<Note>
  The endpoint reference above is being expanded to the full **400+ tool** surface. **Amazon Ads** (61 tools) and **ChatGPT Ads** (36 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.
</Note>

## 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<br/>(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<br/>{lookback_days: 1, ad_account_id}
        A-->>N: metrics
        N->>N: Compute alert state (🟢🟡🔴)
    end
    N->>S: DM each account manager<br/>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<br/>{condition: CPL > target+$20 for 2 days,<br/>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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

<Update label="September 12, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [PMax Brand Guidelines](/docs/ad-platforms/google-ads#pmax-brand-guidelines)
</Update>

<Update label="September 11, 2026" description="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.

  <Prompt description="Check a campaign you just launched.">
    I launched a Meta campaign today. Is it actually delivering, and what has it spent?
  </Prompt>

  ## 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)
</Update>

<Update label="September 8, 2026" description="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)
</Update>

<Update label="September 6, 2026" description="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)
</Update>

<Update label="August 30, 2026" description="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)
</Update>

<Update label="August 25, 2026" description="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.

  <Prompt description="See your promotable Pages before you launch.">
    Which Facebook Pages can I run Meta ads from on my ad account?
  </Prompt>

  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)
</Update>

<Update label="August 25, 2026" description="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)
</Update>

<Update label="August 24, 2026" description="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.

  <Prompt description="Check an Amazon ad's review status.">
    Check the moderation status of my Amazon ad and tell me if anything was
    rejected and why.
  </Prompt>

  **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)
</Update>

<Update label="August 24, 2026" description="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)
</Update>

<Update label="August 24, 2026" description="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)
</Update>

<Update label="August 24, 2026" description="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)
</Update>

<Update label="August 22, 2026" description="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#campaign-creation-failed-error)
</Update>

<Update label="August 22, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [Ad extensions and assets](/docs/ad-platforms/google-ads#ad-extensions-assets)
</Update>

<Update label="August 18, 2026" description="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.

  <Prompt description="Run competitor research on Meta with no Google Ads account connected.">
    Show me the Facebook and Instagram ads figma.com is running right now.
  </Prompt>

  → [Competitor research](/docs/agent-skills/tools#competitor-research-1)
</Update>

<Update label="August 18, 2026" description="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**.
  </Warning>

  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)
</Update>

<Update label="August 17, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [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.

  <Prompt description="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.
  </Prompt>

  → [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)
</Update>

<Update label="August 17, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [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 `<head>`, 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.

  <Prompt description="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.
  </Prompt>

  → [ChatGPT Ads conversion tracking](/docs/ad-platforms/chatgpt-ads)
</Update>

<Update label="August 17, 2026" description="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)
</Update>

<Update label="August 16, 2026" description="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)
</Update>

<Update label="August 16, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [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.

  <Prompt description="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.
  </Prompt>

  → [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)
</Update>

<Update label="August 15, 2026" description="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)
</Update>

<Update label="August 14, 2026" description="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.
  </Warning>

  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.

  <Prompt description="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.
  </Prompt>

  → [Tool catalog](/docs/agent-skills/tools)
</Update>

<Update label="August 13, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [Integration tool reference](/docs/agent-skills/tools)
</Update>

<Update label="August 13, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [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.
  </Note>

  → [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.

  <Prompt description="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.
  </Prompt>

  → [Google Ads integration](/docs/ad-platforms/google-ads)
</Update>

<Update label="August 12, 2026" description="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`.

  <Prompt description="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.
  </Prompt>

  → [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.
  </Warning>

  → [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)
</Update>

<Update label="August 11, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [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#campaign-creation-failed-error)

  ## 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.
  </Warning>

  → [Meta budget guidelines](/docs/ad-platforms/meta-ads#budget-guidelines)
</Update>

<Update label="August 9, 2026" description="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`.

  <Prompt description="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.
  </Prompt>

  → [TikTok Ads integration](/docs/ad-platforms/tiktok-ads)
</Update>

<Update label="August 8, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  → [Google Ads integration](/docs/ad-platforms/google-ads)
</Update>

<Update label="August 8, 2026" description="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)
</Update>

<Update label="August 7, 2026" description="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.

  <Prompt description="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.
  </Prompt>

  ## 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)
</Update>

<Update label="August 6, 2026" description="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.

  <Prompt description="Scope the conversion audit to a single account.">
    Audit conversion tracking for just my main Google Ads account, not all of them
  </Prompt>

  → [Meta Ads integration](/docs/ad-platforms/meta-ads) · [Tool catalog](/docs/agent-skills/tools)
</Update>

<Update label="August 6, 2026" description="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)
</Update>

<Update label="August 5, 2026" description="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)
</Update>

<Update label="July 7, 2026" description="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)
</Update>

<Update label="July 6, 2026" description="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)
</Update>

<Update label="July 4, 2026" description="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)
</Update>

<Update label="July 3, 2026" description="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)
</Update>

<Update label="July 2, 2026" description="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)
</Update>

<Update label="June 30, 2026" description="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)
</Update>

<Update label="June 24, 2026" description="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)
</Update>

<Update label="June 23, 2026" description="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)
</Update>

<Update label="June 22, 2026" description="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)
</Update>

<Update label="June 20, 2026" description="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.
</Update>

<Update label="June 18, 2026" description="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)
</Update>

<Update label="June 17, 2026" description="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)
</Update>

<Update label="June 16, 2026" description="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.
</Update>

<Update label="June 12, 2026" description="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.
</Update>

<Update label="June 11, 2026" description="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)
</Update>

<Update label="June 10, 2026" description="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.
</Update>

<Update label="June 9, 2026" description="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.
</Update>

<Update label="June 8, 2026" description="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.
</Update>

<Update label="June 6, 2026" description="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.
</Update>

<Update label="June 5, 2026" description="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.
</Update>

<Update label="June 2, 2026" description="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).
</Update>

<Update label="June 1, 2026" description="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.
</Update>

<Update label="May 31, 2026" description="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.
</Update>

<Update label="May 30, 2026" description="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.
</Update>

<Update label="May 30, 2026" description="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."
</Update>

<Update label="May 29, 2026" description="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.
  </Note>

  ### 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.
</Update>

<Update label="May 29, 2026" description="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)
</Update>

<Update label="May 26, 2026" description="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.
</Update>

<Update label="May 25, 2026" description="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.
</Update>

<Update label="May 24, 2026" description="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.
</Update>

<Update label="May 22, 2026" description="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.
</Update>

<Update label="May 21, 2026" description="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.
</Update>

<Update label="May 20, 2026" description="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**
</Update>

<Update label="May 16, 2026" description="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.
</Update>

<Update label="May 15, 2026" description="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)**.
  </Note>
</Update>

<Update label="May 14, 2026" description="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.
</Update>

<Update label="May 12, 2026" description="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/<id>` resource names from `list_google_languages`) |
  | `locations_to_add`        | Append geo targets (free-text or `geoTargetConstants/<id>` 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**
</Update>

<Update label="May 9, 2026" description="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.
</Update>

<Update label="April 30, 2026" description="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.
</Update>

<Update label="April 29, 2026" description="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).
</Update>

<Update label="April 23, 2026" description="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.
</Update>

<Update label="April 22, 2026" description="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/<tool_name>/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.
</Update>

<Update label="April 20, 2026" description="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.
</Update>

<Update label="April 16, 2026" description="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.
</Update>

<Update label="April 16, 2026" description="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.
</Update>

<Update label="April 13, 2026" description="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).
</Update>

<Update label="April 8, 2026" description="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
</Update>

<Update label="April 7, 2026" description="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.
</Update>

<Update label="April 5, 2026" description="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
</Update>

<Update label="April 3, 2026" description="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
</Update>

<Update label="April 3, 2026" description="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).
</Update>

<Update label="March 30, 2026" description="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.
</Update>

<Update label="March 25, 2026" description="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.
</Update>

<Update label="March 24, 2026" description="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.
</Update>

<Update label="March 22, 2026" description="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.
</Update>

<Update label="March 21, 2026" description="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.
</Update>

<Update label="March 21, 2026" description="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.
</Update>

<Update label="March 21, 2026" description="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.
</Update>

<Update label="March 19, 2026" description="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.
</Update>

<Update label="March 18, 2026" description="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
</Update>

<Update label="March 17, 2026" description="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.
</Update>

<Update label="March 16, 2026" description="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.
</Update>

<Update label="March 15, 2026" description="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
</Update>

<Update label="March 14, 2026" description="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
</Update>

<Update label="March 12, 2026" description="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
</Update>

<Update label="March 10, 2026" description="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
</Update>

<Update label="March 11, 2026" description="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)
</Update>

<Update label="March 7, 2026" description="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
</Update>

<Update label="March 5, 2026" description="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.
</Update>

<Update label="March 3, 2026" description="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
</Update>

<Update label="February 28, 2026" description="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
</Update>

<Update label="February 27, 2026" description="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
</Update>

<Update label="February 26, 2026" description="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.
</Update>

<Update label="February 22, 2026" description="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
</Update>

<Update label="February 16, 2026" description="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.
</Update>

<Update label="February 2026" description="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`.
</Update>

<Update label="January 2026" description="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.
</Update>

<Update label="December 2025" description="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.
</Update>

<Update label="November 2025" description="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
</Update>

<Update label="October 2025" description="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.
</Update>

<Update label="September 2025" description="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
</Update>


# 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 <Tooltip>MCP</Tooltip> 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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:**

* <Tooltip>MCP</Tooltip> 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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 <Tooltip>CPC</Tooltip> 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)
</Tip>

## 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                                                      |
| --------------------- | ------------------------- | ---------------------------------------------------------- |
| <Badge>HIGH</Badge>   | ≥75th percentile CPC      | Top 25% most expensive keywords = highest commercial value |
| <Badge>MEDIUM</Badge> | 25th-75th percentile      | Middle 50%                                                 |
| <Badge>LOW</Badge>    | 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: Open ChatGPT and Find Adspirer**

Now that your accounts are connected, add Adspirer to ChatGPT:

1. Open [ChatGPT](https://chat.openai.com)
2. Go to **Settings → Apps** (or use the App search)
3. Search for **"Adspirer"**
4. Click **Connect**

**Step 4: Authorize the Connection**

When you connect, ChatGPT will ask you to authorize Adspirer:

1. Click the authorization link
2. Sign in with your **Adspirer account** (the one you created in Step 1)
3. Approve the connection

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)
</Tip>

## 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)
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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:

<CardGroup>
  <Card title="Project instructions" icon="scroll">
    The agent's always-on "constitution" — its role, its hard rules, and how it
    works. Read on every task.
  </Card>

  <Card title="Skills" icon="book">
    On-demand playbooks for specific jobs (build a search campaign, optimize a
    portfolio). Loaded only when the task calls for them.
  </Card>

  <Card title="Scheduled tasks" icon="clock">
    Automation. The same Cowork agent, run unattended on a schedule, making bounded,
    guardrailed changes and posting a summary.
  </Card>
</CardGroup>

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.
</Note>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Leave memory on">
    Project memory lets the agent reuse prior builds, naming conventions, and
    decisions across sessions.
  </Step>
</Steps>

## 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.

<Accordion title="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.
  ```
</Accordion>

## 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.

<Accordion title="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.
  ```
</Accordion>

## 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.

<CardGroup>
  <Card title="Shadow mode by default" icon="ghost">
    A `MODE: shadow` switch makes the task compute and report what it *would* do, but
    write nothing. New tasks start here for a week.
  </Card>

  <Card title="Hard guardrails" icon="shield-halved">
    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.
  </Card>

  <Card title="Single writer" icon="user-lock">
    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.
  </Card>

  <Card title="Propose vs. act" icon="scale-balanced">
    Small, reversible changes auto-apply. Pauses, big moves, and anything beyond a cap
    are *proposed* — applied next run only after a human approves.
  </Card>

  <Card title="Catch-up safe" icon="rotate">
    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.
  </Card>

  <Card title="Notify every run" icon="bell">
    Acted, proposed, or nothing — each run posts a summary to your channel so a human
    can always see and reverse it.
  </Card>
</CardGroup>

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.

<Accordion title="Copy-paste: generic scheduled-task prompt">
  ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
  You are our <platform> 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 <platform> campaigns in the "<pool name>" budget pool.
  POOL CAP: $<X>/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.
  ```
</Accordion>

<Accordion title="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.
</Accordion>

### Rolling it out safely

<Steps>
  <Step title="Start in shadow mode">
    Set the optimizer skill to `MODE: shadow`. The task computes and posts what it would
    do, but changes nothing.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<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.
</Warning>

## Where to go next

<CardGroup>
  <Card title="Connect Claude Cowork" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c" href="/docs/ai-clients/claude-cowork">
    Connect a Cowork project to your ad accounts.
  </Card>

  <Card title="Agent Skills overview" icon="brain" href="/docs/agent-skills/overview">
    What skills are, the safety rules, and how to install them.
  </Card>

  <Card title="Core workflows" icon="arrows-spin" href="/docs/agent-skills/workflows">
    The exact tool sequences for builds, analysis, and automation.
  </Card>

  <Card title="Always-on on a VPS" icon="server" href="/docs/guides/deploy-paid-media-agent-hostinger">
    Run an agent 24/7 on your own server.
  </Card>
</CardGroup>

<Accordion title="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.
</Accordion>

<Snippet />


# 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)
</Note>

## Step 1: Buy a Hostinger VPS with OpenClaw Pre-Installed

A <Tooltip>VPS</Tooltip> 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.

<Steps>
  <Step title="Go to Hostinger's OpenClaw VPS Page">
    Visit the [Hostinger VPS marketplace](https://www.hostinger.com/vps) and look for the OpenClaw hosting option.
  </Step>

  <Step title="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.
    </Tip>
  </Step>

  <Step title="Click Deploy">
    OpenClaw is auto-selected as the application to install. Just click **Deploy** to continue.
  </Step>
</Steps>

## Step 2: Configure Your Server

After clicking Deploy, Hostinger asks you to set some configuration values. This is where you connect Adspirer.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
    </Warning>
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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>
</Steps>

## Step 3: Access Your OpenClaw Dashboard

<Steps>
  <Step title="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`
  </Step>

  <Step title="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>
</Steps>

## 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 <Tooltip>terminal</Tooltip> and run a few commands.

<Steps>
  <Step title="Open the Terminal">
    In Hostinger's hPanel, find the **Terminal** or **SSH Access** option for your VPS. Click to open it.

    <Info>
      If you've never used a terminal before — don't worry. You'll copy and paste 4 commands. That's it.
    </Info>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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>
</Steps>

## 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.

<Steps>
  <Step title="Open the Connections Page">
    Go to [adspirer.ai/connections](https://adspirer.ai/connections) from any device with a browser (your laptop, phone, etc.).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Check>
  Your ad agent is live. It's running 24/7 on your Hostinger server, connected to your ad platforms, and ready to work.
</Check>

## 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)

<Steps>
  <Step title="Open the Channels Section">
    In your OpenClaw dashboard (the browser URL from Step 3), navigate to **Channels**.
  </Step>

  <Step title="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.
    </Tip>
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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.

<Card title="Read more: Marketing Agency Automation" icon="building" href="/docs/guides/marketing-agency-automation">
  Deep dive into how agencies are scaling with AI — team structures, automation roadmaps, and ROI analysis.
</Card>

## 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.

<Card title="Start free — 15 tool calls/month, no credit card" icon="rocket" href="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.
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="'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
    ```
  </Accordion>

  <Accordion title="'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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup>
  <Card title="Google Ads Guide" icon="magnifying-glass" href="https://www.adspirer.com/blog/google-ads-automation">
    Automate keyword research, campaign creation, and optimization
  </Card>

  <Card title="Meta Ads Guide" icon="meta" href="/docs/guides/automate-facebook-ads">
    Create image, video, and carousel campaigns with AI
  </Card>

  <Card title="Agency Automation" icon="building" href="/docs/guides/marketing-agency-automation">
    Scale your agency with AI — team structures and workflows
  </Card>

  <Card title="OpenClaw Setup Docs" icon="plug" href="/docs/ai-clients/openclaw">
    Full OpenClaw plugin reference, CLI commands, and configuration
  </Card>
</CardGroup>


# 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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)
</Note>

## 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

<Prompt description="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
</Prompt>

### 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

<Prompt description="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.
</Prompt>

### 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

<Prompt description="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
</Prompt>

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

<Prompt description="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
</Prompt>

## Workflow 5: Ad Copy Optimization

Let Computer research what's working in your industry, then improve your ads.

### The Prompt

<Prompt description="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
</Prompt>

## 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

<Steps>
  <Step title="Set up Perplexity + Adspirer">
    Follow the [Perplexity Setup Guide](/docs/ai-clients/perplexity) to add Adspirer as a custom connector in Perplexity Computer.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Try the competitor research workflow">
    Copy the Competitor Research → Campaign Creation prompt from Workflow 1 above and customize it for your business.
  </Step>
</Steps>

## 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.
</Warning>

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.

<CardGroup>
  <Card title="Describe the result, not the steps" icon="bullseye">
    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.
  </Card>

  <Card title="Goal · Context · Output · Boundaries" icon="list-check">
    The four parts of a good work prompt: what to do, what to look at, the format and length, and
    what must stay unchanged.
  </Card>

  <Card title="Add a late-run guardrail" icon="hourglass-half">
    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."*
  </Card>

  <Card title="Refine first, then schedule" icon="flask">
    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.
  </Card>
</CardGroup>

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

<Accordion title="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.
  ```
</Accordion>

<Accordion title="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.
  ```
</Accordion>

<Accordion title="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."
</Accordion>

<Accordion title="Competitor landing-page watch">
  ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
  Every Monday, check <competitor URL> for changes to their offer, pricing, or hero message, and
  tell me what's different from last week. Summary only.
  ```
</Accordion>

## 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:

<CardGroup>
  <Card title="Cowork for Ad Ops" icon="robot" href="/docs/guides/claude-cowork-ad-ops">
    The seven-property safety model for a self-optimizing task you can trust.
  </Card>

  <Card title="Set up your project" icon="folder-tree" href="/docs/guides/set-up-your-project">
    Instructions, context, memory, and connectors — the foundation a schedule runs on.
  </Card>
</CardGroup>

<Snippet />


# 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.
</Note>

## 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.

<Tabs>
  <Tab title="Claude Cowork">
    Cowork has a dedicated field for every one of the five parts. Requires Claude Max, Team, or
    Enterprise, and the Adspirer plugin installed from **Customize → Browse plugins**
    ([setup](/docs/ai-clients/claude-cowork)).

    <Steps>
      <Step title="Open Cowork">
        In the Claude desktop app (or claude.ai), click the **Cowork** tab at the top.

        <Frame>
          <img alt="Claude desktop app with the Cowork tab selected" />
        </Frame>
      </Step>

      <Step title="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"*.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.

        <Frame>
          <img alt="Claude Cowork Customize page showing Skills, Connectors, and Browse plugins" />
        </Frame>
      </Step>

      <Step title="Confirm Adspirer and a notification channel">
        In **Customize → Connectors**, confirm the Adspirer connector 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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    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).
  </Tab>

  <Tab title="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.

    <Steps>
      <Step title="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.

        <Frame>
          <img alt="ChatGPT with the Work toggle selected, showing the Project, Files, and Plugins chips under the composer" />
        </Frame>
      </Step>

      <Step title="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.

        <Frame>
          <img alt="ChatGPT sidebar with the Projects section expanded and a project listed" />
        </Frame>
      </Step>

      <Step title="Open Project settings">
        Open the project, click the **⋯** menu at the top right, and choose **Project settings**.

        <Frame>
          <img alt="ChatGPT project page with the three-dot menu open, showing Project settings and Pin project" />
        </Frame>
      </Step>

      <Step title="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.

        <Frame>
          <img alt="ChatGPT Project settings dialog with the Instructions field, a Memory dropdown set to Default memory, and Library access enabled" />
        </Frame>
      </Step>

      <Step title="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.
      </Step>

      <Step title="Turn on Adspirer under Plugins">
        Click the **Plugins** chip and make sure **Adspirer** is on for this project. If you
        connected via the custom connector, it appears under the name you gave it.
      </Step>

      <Step title="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.

        <Frame>
          <img alt="ChatGPT Skills page with the plus menu open, showing Create with chat, Create with editor, and Upload from your computer" />
        </Frame>

        Don't see **Skills**? Your plan doesn't include it yet. The instructions field and the
        Adspirer app's built-in skills carry the same behavior; see the
        [plan note](/docs/agent-skills/prompt-engineering-playbook#chatgpt).
      </Step>

      <Step title="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 **@adspirer** in the prompt if ChatGPT is slow to call tools on its own.
      </Step>
    </Steps>

    <Note>
      The ChatGPT App Store listing is behind the custom connector. If a routine needs Amazon Ads,
      ChatGPT Ads, or Google Analytics, connect via the
      [custom connector](/docs/ai-clients/chatgpt) path before you schedule anything.
    </Note>
  </Tab>

  <Tab title="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)).

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Attach the zip and send the install prompt">
        Drag the `.zip` into the composer (or click **+** and attach it), then send:

        <Prompt description="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.
        </Prompt>

        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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="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)).

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Send the install prompt with the zip path">
        Drag the `.zip` from Finder into the terminal window to paste its path, then send:

        <Prompt description="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.
        </Prompt>

        Confirm with `/skills`, or invoke the expert directly as `/google-ads-expert-<brand>`.
      </Step>

      <Step title="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`.
      </Step>

      <Step title="Create remote routines">
        Ask for the weekly dashboard as a **remote routine**. A local task only runs while the
        machine is awake.
      </Step>
    </Steps>
  </Tab>

  <Tab title="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)).

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.

        <Frame>
          <img alt="ChatGPT desktop app with Codex selected, showing the Codex sidebar and a new chat asking what to work on" />
        </Frame>
      </Step>

      <Step title="Attach the zip and send the install prompt">
        Click **+** in the composer (or drag the `.zip` in), then send:

        <Prompt description="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.
        </Prompt>

        Codex ends with a link to the new agent. Click it, or start a **New chat** and ask for the
        expert by name.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  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.
</Info>

## 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.
</Tip>

## 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.

<Accordion title="Copy-paste: starter agent instructions">
  ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Agent instructions — <Brand> Google Ads paid-media agent (Adspirer)

  ## The business
  <What you sell, to whom, where, at what price. What a conversion is worth.
   Seasonality, promotions, and anything a new hire would need to know on day one.>

  ## Your role
  You are the paid-media agent for <Brand>'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: <target CPA / ROAS / contribution margin, with the number>
  - A conversion is: <the exact conversion action(s) that count>
  - Secondary signals to report, never to optimize toward: <e.g. CTR, impression share>

  ## Scope
  - Google Ads account <ID> 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.
  ```
</Accordion>

**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.
</Tip>

**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, <Tooltip>CPA</Tooltip>, <Tooltip>ROAS</Tooltip> 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.
</Warning>

<Prompt description="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.
</Prompt>

<Prompt description="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.
</Prompt>

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 app. 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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-<brand>/`.
  </Step>

  <Step title="Upload each file into its part of the project">
    The kit is laid out to match this page. Use the table below.
  </Step>
</Steps>

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.
</Tip>

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:

<Prompt description="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.
</Prompt>

## Where to go next

<CardGroup>
  <Card title="Scheduled tasks" icon="clock" href="/docs/guides/scheduled-tasks">
    More routine prompts, late-run guardrails, and what a cadence costs in tool calls.
  </Card>

  <Card title="Cowork for Ad Ops" icon="robot" href="/docs/guides/claude-cowork-ad-ops">
    The full always-on build and the safety model for routines that make changes.
  </Card>

  <Card title="Agent Skills" icon="brain" href="/docs/agent-skills/skills">
    The 13 free skills, what each enforces, and how to install them per client.
  </Card>

  <Card title="Prompt Engineering Playbook" icon="wand-magic-sparkles" href="/docs/agent-skills/prompt-engineering-playbook">
    The agent playbook from Expert Space: instructions, dossier, skill, and prompt book generated from your account.
  </Card>

  <Card title="Managing multiple clients" icon="users" href="/docs/knowledge-base/multi-client">
    One project per client per platform, without letting automation collide.
  </Card>

  <Card title="Connect your AI client" icon="plug" href="/docs/mcp">
    Cowork, ChatGPT, Claude Code, Codex Desktop, and every other client Adspirer supports.
  </Card>
</CardGroup>

<Snippet />


# 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**: <Tooltip>CPMs</Tooltip> 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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)

<Tooltip>MCP</Tooltip> 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:

* <Badge>Read</Badge> **tools** pull data and analyze performance. Safe to run anytime. No spending impact. Examples: `get_campaign_performance`, `research_keywords`, `analyze_wasted_spend`.
* <Badge>Write</Badge> **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

<Steps>
  <Step title="You trigger a connection">
    Either through your AI client's MCP settings or by running setup (`/adspirer:setup`).
  </Step>

  <Step title="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.
  </Step>

  <Step title="You authorize permissions">
    You see exactly what Adspirer is requesting (read campaigns, create ads, manage budgets). You approve.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>
</Steps>

### 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.
</Note>

***

## 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)
</Note>

## 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.

<Info>
  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.
</Info>

## 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.

## 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 | <Badge>Included</Badge> |
| Pro  | <Badge>Included</Badge> |
| Max  | <Badge>Included</Badge> |

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.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Which GA4 properties does the agent see?">
    Whichever properties you have access to under the Google account you used for the OAuth grant. If you have multiple GA4 properties, the agent will ask which one to query (or you can specify by property ID).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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)
</Note>

## 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.

<Info>
  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.
</Info>

## 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 | <Badge>Included</Badge> |
| Pro  | <Badge>Included</Badge> |
| Max  | <Badge>Included</Badge> |

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.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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, and more.

Adspirer is an <Tooltip>MCP</Tooltip> 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.

<Card title="Get started in 5 minutes" icon="rocket" href="/docs/quickstart">
  Sign up, connect your AI client, and start managing ads with natural language.
</Card>

## Connect Your AI Assistant

Choose how you want to manage ads. Chat apps for conversational use, developer tools for terminal workflows.

<Columns>
  <Card title="ChatGPT" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/chatgpt.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=6106ee76b21067108cdff4760dd7cfb1" href="/docs/ai-clients/chatgpt">
    MCP connector for ChatGPT Plus/Pro.
  </Card>

  <Card title="Claude" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c" href="/docs/ai-clients/claude">
    MCP connector for Claude Chat (Pro/Max/Team/Enterprise).
  </Card>

  <Card title="Claude Cowork" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c" href="/docs/ai-clients/claude-cowork">
    Brand-aware workspace mode in the Claude desktop app — folder + connector + optional plugin.
  </Card>

  <Card title="Claude Code" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude-code.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=4873968842d36554bb6a8d15c886e00d" href="/docs/ai-clients/claude-code">
    Anthropic's separate terminal/CLI developer tool. One command to connect.
  </Card>

  <Card title="Gemini CLI" icon="https://mintcdn.com/adspirer/3OjfThfXkO753jUS/icons/gemini.svg?fit=max&auto=format&n=3OjfThfXkO753jUS&q=85&s=3415ee990e815a422f4f6dd50eb96ac8" href="/docs/ai-clients/gemini-cli">
    Google's AI CLI with one-command install.
  </Card>

  <Card title="Cursor" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/cursor.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=fc2d5972cbda895e87b17aba40dcd1f1" href="/docs/ai-clients/cursor">
    MCP setup in your IDE.
  </Card>

  <Card title="Codex Terminal" icon="https://mintcdn.com/adspirer/d1-3M_DPxPhMWBSu/icons/codex.svg?fit=max&auto=format&n=d1-3M_DPxPhMWBSu&q=85&s=b31cb81882fba09f78a7d90639f6c97a" href="/docs/ai-clients/codex">
    Autonomous agent setup in the terminal.
  </Card>

  <Card title="Codex Desktop" icon="https://mintcdn.com/adspirer/d1-3M_DPxPhMWBSu/icons/codex.svg?fit=max&auto=format&n=d1-3M_DPxPhMWBSu&q=85&s=b31cb81882fba09f78a7d90639f6c97a" href="/docs/ai-clients/codex-desktop">
    Codex inside the ChatGPT desktop app — three messages, no terminal.
  </Card>

  <Card title="OpenClaw" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/openclaw.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=507164157fe5912c1dae95a190a65267" href="/docs/ai-clients/openclaw">
    Plugin with zero configuration.
  </Card>

  <Card title="Windsurf" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/windsurf.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=dc8feecaa6bf135782d4fd9d7703929e" href="/docs/ai-clients/windsurf">
    Codeium's AI-powered editor.
  </Card>

  <Card title="Perplexity" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/perplexity.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=e1ee0859a3ade5ea84a9a9d5df37e6c5" href="/docs/ai-clients/perplexity">
    Search-powered ad management via Computer.
  </Card>
</Columns>

## Ad Platforms

Each platform integration comes with dedicated tools for campaign creation, performance analysis, and optimization.

<Columns>
  <Card title="Google Ads" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/google-ads.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=523927ffe08f8a180fe35b7cdd522541" href="/docs/ad-platforms/google-ads">
    156 tools — Search, PMax, Shopping, App, Display, YouTube, Demand Gen, keyword research, budget optimization.
  </Card>

  <Card title="Meta Ads" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/meta.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=3d0d90257e6e8b1d7b22b4ad6ea959b8" href="/docs/ad-platforms/meta-ads">
    60 tools — Facebook & Instagram campaigns, Advantage+ Catalog (dynamic product ads), creative testing, lead gen.
  </Card>

  <Card title="Amazon Ads" icon="https://mintcdn.com/adspirer/tm56ipPRpt0nhwwQ/icons/amazon.svg?fit=max&auto=format&n=tm56ipPRpt0nhwwQ&q=85&s=1931358385448531df132fa40cc27ea9" href="/docs/ad-platforms/amazon-ads">
    61 tools — Sponsored Products, Brands & Display, ASIN targeting, ACOS/ROAS analytics.
  </Card>

  <Card title="ChatGPT Ads" icon="https://mintcdn.com/adspirer/tm56ipPRpt0nhwwQ/icons/openai.svg?fit=max&auto=format&n=tm56ipPRpt0nhwwQ&q=85&s=5392e998e6c23bb558c633f50ba4d629" href="/docs/ad-platforms/chatgpt-ads">
    36 tools — pay-per-click chat-card ads inside ChatGPT responses, created paused.
  </Card>

  <Card title="LinkedIn Ads" icon="https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/icons/linkedin.svg?fit=max&auto=format&n=vhaKM86uNtBGo98V&q=85&s=59bacb73f680a3ecf7df34306ad2ba04" href="/docs/ad-platforms/linkedin-ads">
    55 tools — B2B targeting, image/video/text/carousel, campaign groups, audience forecasting.
  </Card>

  <Card title="TikTok Ads" icon="https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/icons/tiktok.svg?fit=max&auto=format&n=vhaKM86uNtBGo98V&q=85&s=a76c6259ebbd339771558f26cf72baac" href="/docs/ad-platforms/tiktok-ads">
    37 tools — In-feed video, Spark Ads, Carousel, full campaign analytics.
  </Card>
</Columns>

## Integrations

Stitch paid media to the rest of your marketing stack. Available on **Plus, Pro, and Max** plans.

<Columns>
  <Card title="Google Analytics 4" icon="chart-line" href="/docs/integrations/google-analytics">
    Correlate ad spend with on-site behavior — sessions, conversions, traffic sources, landing-page performance.
  </Card>

  <Card title="Klaviyo" icon="envelope" href="/docs/integrations/klaviyo">
    Pull email + SMS campaigns, flows, segments, and revenue alongside paid media for full-funnel analysis.
  </Card>
</Columns>

## Beyond one-off commands

Adspirer isn't just a tool surface — it runs work for you and shares results with your team.

<Columns>
  <Card title="Autonomous Ad Ops Agents" icon="robot" href="/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.
  </Card>

  <Card title="Shareable Dashboards" icon="chart-mixed" href="/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.
  </Card>

  <Card title="Community Plugins" icon="puzzle-piece" href="/docs/agent-skills/community-plugins">
    Extend Adspirer with open-source, community-contributed analysis tools — read-only and sandboxed.
  </Card>

  <Card title="Available in 100+ languages" icon="language" href="/docs/knowledge-base/localization">
    The Adspirer dashboard and onboarding are localized into **116 languages** with full right-to-left support.
  </Card>
</Columns>

## See It in Action

<Frame>
  <iframe title="Adspirer: Manage Ad Campaigns with AI" />
</Frame>

## Go Deeper

<Columns>
  <Card title="Agent Skills" icon="brain" href="/docs/agent-skills/overview">
    Teach your AI assistant proven ad management workflows.
  </Card>

  <Card title="Tool Catalog" icon="wrench" href="/docs/agent-skills/tools">
    Complete reference of all 400+ tools by platform.
  </Card>

  <Card title="Core Workflows" icon="diagram-project" href="/docs/agent-skills/workflows">
    Step-by-step sequences for campaign creation and optimization.
  </Card>

  <Card title="Guides" icon="book-open" href="/docs/guides/chatgpt-google-ads-keywords">
    In-depth tutorials for Google Ads, Meta Ads, TikTok, and more.
  </Card>

  <Card title="Diagnostic & Helper Tools" icon="stethoscope" href="/docs/agent-skills/diagnostic-helper-tools">
    Free, quota-free tools to get started, pre-flight a launch, and diagnose errors.
  </Card>
</Columns>

## 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.

<Card title="REST API Reference" icon="code" href="/docs/api-reference/introduction">
  400+ endpoints, interactive try-it playground, copy-paste examples for curl, Python, Node, and n8n.
</Card>


# 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
* **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, <Tooltip>CPA</Tooltip>, <Tooltip>ROAS</Tooltip>, <Tooltip>CTR</Tooltip>)
* 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.

## 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                                                                                                                                      |

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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 <Tooltip>MCP</Tooltip> — 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").
</Tip>

## 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

<CardGroup>
  <Card title="Perplexity Setup" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/perplexity.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=e1ee0859a3ade5ea84a9a9d5df37e6c5" href="/docs/ai-clients/perplexity">
    Connect via OAuth in Perplexity Computer. Search + ads in one agent.
  </Card>

  <Card title="Manus Setup" icon="wand-magic-sparkles" href="/docs/ai-clients/manus">
    Connect via API key. Dashboards, briefs, and monitoring.
  </Card>

  <Card title="Codex Setup" icon="https://mintcdn.com/adspirer/d1-3M_DPxPhMWBSu/icons/codex.svg?fit=max&auto=format&n=d1-3M_DPxPhMWBSu&q=85&s=b31cb81882fba09f78a7d90639f6c97a" href="/docs/ai-clients/codex">
    One-command install. Scheduled autonomous tasks.
  </Card>

  <Card title="OpenClaw Setup" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/openclaw.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=507164157fe5912c1dae95a190a65267" href="/docs/ai-clients/openclaw">
    Pre-configured ad agent with bundled skills.
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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?

<AccordionGroup>
  <Accordion title="What is Adspirer?">
    Adspirer is an <Tooltip>MCP</Tooltip> 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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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)               |         Skill upload         |     [Guide](/docs/ai-clients/claude)    |
    | [Cursor](/docs/ai-clients/cursor)               |    Full (subagent + rules)   |     [Guide](/docs/ai-clients/cursor)    |
    | [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 only          |    [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)     |
  </Accordion>
</AccordionGroup>

## How It Works

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="What is MCP?">
    <Tooltip>MCP</Tooltip> (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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Do I need to install anything?">
    It depends on your AI client:

    * **Claude (web/desktop):** No install. Add a connector URL in settings. [Guide →](/docs/ai-clients/claude)
    * **ChatGPT:** No install. Add a connector in settings. [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:** One command (bash installer). [Guide →](/docs/ai-clients/cursor)
    * **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)
  </Accordion>
</AccordionGroup>

## Ad Platforms

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Pricing & Billing

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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#whats-a-tool-call).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Security & Privacy

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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 Ads MCP, click **Disconnect**, then **Connect** again and complete the OAuth flow
    * **ChatGPT (App Store app):** Go to **Settings → Apps**, find Adspirer, click **Disconnect**, then reopen the Adspirer app, click **Connect**, and complete OAuth
    * **ChatGPT (custom connector):** Go to **Settings → Apps → Advanced settings**, remove the Adspirer app you created, then **Create app** again with `https://mcp.adspirer.com/mcp` and sign in
    * **Claude Code:** Type `/plugin` → **Installed** tab → select **adspirer** → **Authenticate** (or use `/mcp` → **plugin:adspirer-ads-agent:adspirer MCP Server** → **Authenticate**)
    * **Cursor:** Re-connect via MCP settings

    **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).
    </Note>
  </Accordion>

  <Accordion title="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 / Ads MCP
    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).
    </Tip>
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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 → Apps
    * **Cursor:** Re-connect via MCP settings

    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.
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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's a Tool Call?](/docs/knowledge-base/pricing#whats-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`.


# 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.
</Note>

## 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

<CardGroup>
  <Card title="Automatic detection" icon="wand-magic-sparkles">
    Adspirer detects your browser's preferred language on first visit and shows the interface in it automatically.
  </Card>

  <Card title="One-click switcher" icon="globe">
    Prefer a different language? Switch any time from the language switcher — the full interface updates instantly.
  </Card>

  <Card title="Right-to-left support" icon="align-right">
    RTL languages render with correct layout direction throughout, not just translated text.
  </Card>

  <Card title="Remembered across devices" icon="mobile">
    Your language preference follows your account, so the dashboard opens in your language on every device you sign in from.
  </Card>
</CardGroup>

## 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.

<Prompt description="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.
</Prompt>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup>
  <Card title="One account, six platforms" icon="plug">
    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.
  </Card>

  <Card title="Write, not just read" icon="pen-to-square">
    Google's official MCP is read-only. Flyweel is read-only. Adspirer creates campaigns, adjusts budgets, and optimizes — with safety rails.
  </Card>

  <Card title="Maintained, not a side project" icon="shield-check">
    Commercial support with 24-hour SLA on Max. Most community MCPs are solo-maintained GitHub repos that can go stale before your next launch.
  </Card>
</CardGroup>

## 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 (<Tooltip>GAQL</Tooltip> 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 <Tooltip>PKCE</Tooltip>, 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, 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.

<CardGroup>
  <Card title="One platform, one account, read-only needs" icon="magnifying-glass">
    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.
  </Card>

  <Card title="You need a platform we don't cover" icon="puzzle-piece">
    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)
  </Card>

  <Card title="Cross-warehouse analytics, not campaign execution" icon="database">
    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.
  </Card>

  <Card title="A one-off engineer doing local analysis" icon="terminal">
    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.
  </Card>
</CardGroup>

## Where Adspirer Wins

<CardGroup>
  <Card title="Multi-platform, campaign-depth work" icon="layer-group">
    When you're running Google + Meta + Amazon + LinkedIn or TikTok and you need to launch, optimize, and pace from chat — not just query.
  </Card>

  <Card title="Agencies with many clients" icon="briefcase">
    Multi-account routing across multiple platforms in one conversation. See [multi-client](/docs/knowledge-base/multi-client).
  </Card>

  <Card title="Teams that care about safety rails" icon="lock">
    Destructive operations are structurally unavailable. No "oops, deleted the wrong campaign" class of failure.
  </Card>

  <Card title="AI-first stacks beyond Claude Desktop" icon="wand-magic-sparkles">
    First-class across ChatGPT, Claude Code, Cursor, Codex, Windsurf, OpenClaw, Manus, and more.
  </Card>
</CardGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What AI clients does Adspirer work with?">
    ChatGPT, Claude Desktop, Claude Web, Claude Code, Claude Cowork, Cursor, Codex, Windsurf, OpenClaw, Gemini CLI, Manus, Perplexity, and Custom GPTs. See the [AI Clients section](/docs/ai-clients/chatgpt) for setup guides per client.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

## Related Reading

<CardGroup>
  <Card title="Best ad MCP servers in 2026" icon="list-ol" href="https://www.adspirer.com/blog/best-ad-mcp-servers-2026">
    Ranked honest reviews of every credible ad MCP server.
  </Card>

  <Card title="Why not Google's free MCP?" icon="circle-question" href="/docs/knowledge-base/why-not-official-google-ads-mcp">
    The detailed breakdown of what Google's official MCP does and doesn't do.
  </Card>

  <Card title="What Adspirer can & can't do" icon="list-check" href="/docs/knowledge-base/capabilities">
    Full capability list and stated limitations.
  </Card>

  <Card title="Platform comparison" icon="scale-balanced" href="/docs/knowledge-base/platform-comparison">
    Google vs Meta vs Amazon vs TikTok for advertisers.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/docs/knowledge-base/pricing">
    Plans, tool call limits, and usage examples.
  </Card>

  <Card title="Security" icon="shield" href="/docs/knowledge-base/security">
    OAuth, encryption, and data handling specifics.
  </Card>
</CardGroup>

## 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. 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 |
| <Badge>Max</Badge> (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.
</Tip>

### 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.
</Tip>

<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.
</Note>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Does switching accounts cost a tool call?">
    No. Account switching is a session operation and does not count against your tool call limit.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>


# 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 <Tooltip>MCP</Tooltip> 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         |
| [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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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 <Tooltip>CPC</Tooltip>** | \$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 <Tooltip>ACOS</Tooltip> 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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.
</Tip>

## Plans

| Plan                        | Tool Calls/Month | Monthly  | Annual     | Best For                                             |
| --------------------------- | ---------------- | -------- | ---------- | ---------------------------------------------------- |
| <Badge>Free Forever</Badge> | 15               | \$0      | —          | Testing and evaluation                               |
| <Badge>Plus</Badge>         | 150 + overage    | \$49/mo  | \$485/yr   | Individual advertisers, small accounts               |
| <Badge>Pro</Badge>          | 600              | \$99/mo  | \$999/yr   | Individual marketers, 1 ad account                   |
| <Badge>Max</Badge>          | 3,000            | \$199/mo | \$2,000/yr | Multi-platform, multi-account, sequential sub-agents |

<Info>
  **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.
</Info>

## 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.
</Warning>

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 |
| ------------------- | :-----: | :----: |
| <Badge>Free</Badge> |    1    |    1   |
| <Badge>Plus</Badge> |    1    |  **5** |
| <Badge>Pro</Badge>  |    1    |  **5** |
| <Badge>Max</Badge>  |  **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.
</Tip>

See [full pricing details](https://www.adspirer.com/pricing).

<Info>
  **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.
</Info>

## 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.
</Tip>

| 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      |

<Info>
  **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.
  * Annual subscribers **never** hit overage charges; the yearly pool is their total budget for the year.
</Info>

## 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 |
| ------------------- | ----------------------------------- | ------------------- |
| <Badge>Free</Badge> | One-time at signup                  | 90 days (at signup) |
| <Badge>Plus</Badge> | Regular background sync (see above) | 90 days rolling     |
| <Badge>Pro</Badge>  | Regular background sync (see above) | 90 days rolling     |
| <Badge>Max</Badge>  | Regular background sync (see above) | 90 days rolling     |

<Info>
  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.
</Info>

<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.
</Note>

## Which Plan Do I Need?

Use this guide based on your situation:

| Your Situation                                                              | Recommended Plan                                                                                    |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Testing Adspirer, exploring tools                                           | <Badge>Free</Badge> 15 calls/mo                                                                     |
| Solo marketer, 1 platform, under \$1K/mo ad spend, 1-5 campaigns            | <Badge>Plus</Badge> \$49/mo                                                                         |
| 2+ platforms, $1K-$10K/mo spend, small team (2-5), or 6-20 campaigns/mo     | <Badge>Pro</Badge> \$99/mo                                                                          |
| 3+ platforms with active spend, or $10K-$50K/mo spend with any other factor | <Badge>Max</Badge> \$199/mo                                                                         |
| \$50K+/mo ad spend, 10+ team members, or agency with multiple clients       | <Badge>Max</Badge> \$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.
</Tip>

## 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 + <Tooltip>ROAS</Tooltip>/<Tooltip>CPA</Tooltip> 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)          |

<Info>
  **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.
</Info>

### Monthly Usage Examples

| Scenario                                                 | Estimated Calls | Recommended Plan                           |
| -------------------------------------------------------- | --------------- | ------------------------------------------ |
| Setup verification + 1 trial campaign                    | 12–15/mo        | <Badge>Free</Badge>                        |
| Weekly check (1 platform) + 1 campaign/month             | 12–18/mo        | <Badge>Free</Badge> or <Badge>Plus</Badge> |
| Daily monitoring (2 platforms) + 2 campaigns/mo          | 40–80/mo        | <Badge>Plus</Badge>                        |
| Active multi-platform: 4–6 campaigns + weekly audits     | 100–200/mo      | <Badge>Plus</Badge> or <Badge>Pro</Badge>  |
| Heavy usage: daily monitoring, frequent launches, audits | 200–600/mo      | <Badge>Pro</Badge>                         |
| Agency, multi-client, high-volume                        | 600+/mo         | <Badge>Max</Badge>                         |

## 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.
</Tip>

## 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>
  Overage billing 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. **Annual subscribers (Plus, Pro, or Max) never hit overage** — the yearly pool is their total budget for the year.
</Tip>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I pay per call instead of monthly?">
    Plus subscribers get per-call overage billing after their 150 included calls — $0.50 per additional call, capped at $50/month. Pro and Max plans are fixed subscriptions without per-call billing.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>


# 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.

<Info>
  **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.
</Info>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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."**
  </Step>

  <Step title="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"*.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.
</Tip>

## 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.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does my link expire?">
    No. Your link and code are permanent and never change.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How long do bonus calls last?">
    180 days from the day they are granted. They are spent automatically alongside your normal monthly allowance.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

<Info>
  Adspirer never sees your ad platform passwords. All authentication uses OAuth 2.1 with <Tooltip>PKCE</Tooltip> — the same standard used by banking apps.
</Info>

## 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.)

### Token Lifecycle

| Token         | Lifetime | Purpose                                      |
| ------------- | -------- | -------------------------------------------- |
| Access token  | 1 hour   | Authorizes tool calls                        |
| Refresh token | 30 days  | Generates new access tokens without re-login |

Tokens are encrypted at rest and automatically refreshed. If a token expires, 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) |

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>


# 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Disconnect and Reconnect the Connector">
    * **Claude:** Customize → Connectors → Disconnect Ads MCP → Connect again → Complete OAuth
    * **ChatGPT (App Store app):** Settings → Apps → find Adspirer → Disconnect → reopen the Adspirer app → Connect → Complete OAuth
    * **ChatGPT (custom connector):** Settings → Apps → Advanced settings → remove the app you created → Create app with `https://mcp.adspirer.com/mcp` → Complete OAuth
    * **Claude Code:** `/plugin` → **Installed** tab → **adspirer** → **Authenticate** (or `/mcp` → **plugin:adspirer-ads-agent:adspirer MCP Server** → **Authenticate**)

    Claude and ChatGPT web connectors may disconnect every 1–2 weeks. This is normal — just re-enable and re-authenticate.
  </Step>

  <Step title="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
  </Step>
</Steps>

<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).
</Note>

<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.
</Tip>

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.
</Note>

## Community

<Card title="Join our Discord" icon="discord" href="https://discord.gg/ddZr3xTR">
  Ask questions, share workflows, get help from the team and other Adspirer users. The fastest way to get answers.
</Card>

## Report an Issue

Found a bug or something not working? Open a GitHub issue with the details.

<Card title="Open a GitHub Issue" icon="github" href="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.
</Card>

### 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:

<Card title="Request a Feature" icon="lightbulb" href="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.
</Card>

## 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.

<Card title="Book a Demo" icon="calendar" href="https://www.adspirer.com/book-demo">
  Priority support, dedicated onboarding, and custom integrations for agencies and teams.
</Card>

## Quick Links

<CardGroup>
  <Card title="FAQ" icon="circle-question" href="/docs/knowledge-base/faq">
    Common questions about Adspirer — pricing, security, platforms, troubleshooting
  </Card>

  <Card title="Glossary" icon="book-open" href="/docs/knowledge-base/glossary">
    Advertising and technology terms used across Adspirer
  </Card>

  <Card title="Security" icon="shield-halved" href="/docs/knowledge-base/security">
    OAuth, encryption, data handling, and how to revoke access
  </Card>

  <Card title="Pricing" icon="credit-card" href="/docs/knowledge-base/pricing">
    Plans, tool call limits, and what's included
  </Card>

  <Card title="Prompt Engineering Playbook" icon="wand-magic-sparkles" href="/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
  </Card>
</CardGroup>


# 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 <Tooltip>GAQL</Tooltip> 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.

<Info>
  **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.
</Info>

## 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:

<CardGroup>
  <Card title="Google Ads only, read-only" icon="magnifying-glass">
    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.
  </Card>

  <Card title="GAQL-fluent developer" icon="code">
    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.
  </Card>

  <Card title="Gemini-centric stack" icon="sparkles">
    You're building on Gemini and you want the most canonical Google-blessed integration. This is it.
  </Card>

  <Card title="Diagnostic-only agency audits" icon="clipboard-check">
    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.
  </Card>
</CardGroup>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Reading

<CardGroup>
  <Card title="MCP Server Comparison (pillar)" icon="scale-unbalanced" href="/docs/knowledge-base/mcp-server-comparison">
    Adspirer vs every credible alternative — the core comparison doc.
  </Card>

  <Card title="Best Ad MCP Servers 2026" icon="list-ol" href="https://www.adspirer.com/blog/best-ad-mcp-servers-2026">
    The full ranked landscape with honest reviews.
  </Card>

  <Card title="What Adspirer can & can't do" icon="list-check" href="/docs/knowledge-base/capabilities">
    The capability matrix and stated limitations.
  </Card>

  <Card title="Google Ads integration" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/google-ads.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=523927ffe08f8a180fe35b7cdd522541" href="/docs/ad-platforms/google-ads">
    Setup guide, tool list, and workflows for Google Ads.
  </Card>

  <Card title="Security" icon="shield" href="/docs/knowledge-base/security">
    OAuth model, encryption, and data handling.
  </Card>

  <Card title="Pricing" icon="credit-card" href="/docs/knowledge-base/pricing">
    Free tier and paid plan details.
  </Card>
</CardGroup>

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, Codex, OpenClaw, Windsurf, Perplexity, and Manus — all connecting to the same endpoint.

## MCP Server URL

<Info>
  **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.
</Info>

## Transport

Adspirer supports two MCP transport mechanisms:

| Transport           | Used By                                              | How It Works                                                                                                              |
| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Streamable HTTP** | ChatGPT, Claude, Cursor, Windsurf, Perplexity, Manus | HTTP POST for requests, <Tooltip>SSE</Tooltip> 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 <Tooltip>PKCE</Tooltip>** — 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.
</Note>

### 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

<Tree>
  <TreeItem title="mcp.adspirer.com" icon="server">
    <TreeItem title="OAuth 2.1 + PKCE" icon="lock" />

    <TreeItem title="JSON-RPC 2.0 Router" icon="route">
      <TreeItem title="tools/list — Discover 400+ tools" />

      <TreeItem title="tools/call — Execute tool with auth" />
    </TreeItem>

    <TreeItem title="Platform Adapters" icon="plug">
      <TreeItem title="Google Ads API (156 tools)" />

      <TreeItem title="Meta Marketing API (60 tools)" />

      <TreeItem title="Amazon Ads API (61 tools)" />

      <TreeItem title="ChatGPT Ads / OpenAI Ads API (36 tools)" />

      <TreeItem title="LinkedIn Marketing API (55 tools)" />

      <TreeItem title="TikTok Marketing API (37 tools)" />
    </TreeItem>

    <TreeItem title="Redis Sessions (1hr TTL)" icon="database" />
  </TreeItem>
</Tree>

### 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)           |
| 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Connect Your AI Client">
    Pick your AI assistant and follow the setup guide:

    **Chat Apps**

    <CardGroup>
      <Card title="ChatGPT" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/chatgpt.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=6106ee76b21067108cdff4760dd7cfb1" href="/docs/ai-clients/chatgpt">
        App Store app, or a custom connector for the newest tools. Requires Plus or Pro.
      </Card>

      <Card title="Claude" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=5a0cf872fbf9d5eaae304c65c4d3e28c" href="/docs/ai-clients/claude">
        Add the MCP connector in Claude Settings. Requires Pro, Max, Team, or Enterprise.
      </Card>

      <Card title="Codex Desktop" icon="https://mintcdn.com/adspirer/d1-3M_DPxPhMWBSu/icons/codex.svg?fit=max&auto=format&n=d1-3M_DPxPhMWBSu&q=85&s=b31cb81882fba09f78a7d90639f6c97a" href="/docs/ai-clients/codex-desktop">
        Codex inside the ChatGPT desktop app. Three chat messages, no terminal.
      </Card>
    </CardGroup>

    **Developer Tools**

    <CardGroup>
      <Card title="Claude Code" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/claude-code.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=4873968842d36554bb6a8d15c886e00d" href="/docs/ai-clients/claude-code">
        One-command plugin install from your terminal.
      </Card>

      <Card title="Gemini CLI" icon="https://mintcdn.com/adspirer/3OjfThfXkO753jUS/icons/gemini.svg?fit=max&auto=format&n=3OjfThfXkO753jUS&q=85&s=3415ee990e815a422f4f6dd50eb96ac8" href="/docs/ai-clients/gemini-cli">
        One-command extension install from your terminal.
      </Card>

      <Card title="Cursor" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/cursor.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=fc2d5972cbda895e87b17aba40dcd1f1" href="/docs/ai-clients/cursor">
        One-command installer with 5 skills and subagent.
      </Card>

      <Card title="Codex Terminal" icon="https://mintcdn.com/adspirer/d1-3M_DPxPhMWBSu/icons/codex.svg?fit=max&auto=format&n=d1-3M_DPxPhMWBSu&q=85&s=b31cb81882fba09f78a7d90639f6c97a" href="/docs/ai-clients/codex">
        One-command installer for autonomous agent setup.
      </Card>

      <Card title="OpenClaw" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/openclaw.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=507164157fe5912c1dae95a190a65267" href="/docs/ai-clients/openclaw">
        Plugin install with 14KB skill file built in.
      </Card>

      <Card title="Windsurf" icon="https://mintcdn.com/adspirer/3Cmu7BGXJhgAiZSY/icons/windsurf.svg?fit=max&auto=format&n=3Cmu7BGXJhgAiZSY&q=85&s=dc8feecaa6bf135782d4fd9d7703929e" href="/docs/ai-clients/windsurf">
        Add MCP config to Windsurf settings.
      </Card>

      <Card title="Perplexity" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/perplexity.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=e1ee0859a3ade5ea84a9a9d5df37e6c5" href="/docs/ai-clients/perplexity">
        Add custom connector in Perplexity Computer.
      </Card>
    </CardGroup>

    **Quick MCP Config Reference**

    <Tabs>
      <Tab title="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.
      </Tab>

      <Tab title="Cursor">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        bash <(curl -fsSL https://raw.githubusercontent.com/amekala/ads-mcp/main/plugins/cursor/adspirer/install.sh)
        ```

        Run from your **system terminal**, not Cursor's built-in terminal. Then restart Cursor.
      </Tab>

      <Tab title="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.
      </Tab>

      <Tab title="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))
      </Tab>

      <Tab title="OpenClaw">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
        openclaw plugins install openclaw-adspirer
        openclaw adspirer login
        ```
      </Tab>

      <Tab title="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.
      </Tab>

      <Tab title="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"
            }
          }
        }
        ```
      </Tab>

      <Tab title="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.
      </Tab>

      <Tab title="ChatGPT">
        No config needed — open **Apps** in ChatGPT, search **"Adspirer,"** and click **Connect**.

        The App Store app is behind on updates and has no Amazon Ads, ChatGPT Ads, Google Analytics, or Search Console tools. For those, turn on **Developer mode** and add Adspirer as a custom connector with `https://mcp.adspirer.com/mcp` instead. ([Both paths, step by step](/docs/ai-clients/chatgpt))
      </Tab>

      <Tab title="Claude">
        No config needed — add the MCP connector from Claude's Settings page:

        **MCP Server URL:** `https://mcp.adspirer.com/mcp`
      </Tab>
    </Tabs>
  </Step>

  <Step title="Connect an Ad Platform">
    Link your advertising accounts. You can connect multiple platforms:

    <CardGroup>
      <Card title="Google Ads" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/google-ads.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=523927ffe08f8a180fe35b7cdd522541" href="/docs/ad-platforms/google-ads">
        156 tools for Search, PMax, Shopping & App campaigns, keyword research, budget optimization.
      </Card>

      <Card title="Meta Ads" icon="https://mintcdn.com/adspirer/TdPg9YWtsb-THudf/icons/meta.svg?fit=max&auto=format&n=TdPg9YWtsb-THudf&q=85&s=3d0d90257e6e8b1d7b22b4ad6ea959b8" href="/docs/ad-platforms/meta-ads">
        60 tools for Facebook & Instagram campaigns, Advantage+ Catalog (dynamic product ads), creative testing.
      </Card>

      <Card title="Amazon Ads" icon="https://mintcdn.com/adspirer/tm56ipPRpt0nhwwQ/icons/amazon.svg?fit=max&auto=format&n=tm56ipPRpt0nhwwQ&q=85&s=1931358385448531df132fa40cc27ea9" href="/docs/ad-platforms/amazon-ads">
        61 tools for Sponsored Products, Brands & Display, ASIN targeting, ACOS/ROAS.
      </Card>

      <Card title="ChatGPT Ads" icon="https://mintcdn.com/adspirer/tm56ipPRpt0nhwwQ/icons/openai.svg?fit=max&auto=format&n=tm56ipPRpt0nhwwQ&q=85&s=5392e998e6c23bb558c633f50ba4d629" href="/docs/ad-platforms/chatgpt-ads">
        36 tools for pay-per-click chat-card ads inside ChatGPT, created paused.
      </Card>

      <Card title="LinkedIn Ads" icon="https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/icons/linkedin.svg?fit=max&auto=format&n=vhaKM86uNtBGo98V&q=85&s=59bacb73f680a3ecf7df34306ad2ba04" href="/docs/ad-platforms/linkedin-ads">
        55 tools for B2B advertising, video & carousel, campaign groups, audience forecasting.
      </Card>

      <Card title="TikTok Ads" icon="https://mintcdn.com/adspirer/vhaKM86uNtBGo98V/icons/tiktok.svg?fit=max&auto=format&n=vhaKM86uNtBGo98V&q=85&s=a76c6259ebbd339771558f26cf72baac" href="/docs/ad-platforms/tiktok-ads">
        37 tools for in-feed video, Spark Ads, and Carousel campaigns.
      </Card>
    </CardGroup>
  </Step>

  <Step title="Try It Out">
    Once connected, ask your AI assistant:

    <Prompt description="Verify your ad platform connections are working.">
      Check my connected ad platforms
    </Prompt>

    You should see a table showing your connected accounts with IDs, names, and connection status.

    Then try something real:

    <Prompt description="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
    </Prompt>
  </Step>
</Steps>

## What's Next?

<CardGroup>
  <Card title="Agent Skills" icon="brain" href="/docs/agent-skills/overview">
    Install skills to teach your AI assistant proven ad management workflows with safety rules.
  </Card>

  <Card title="Tool Catalog" icon="wrench" href="/docs/agent-skills/tools">
    Browse all 400+ tools organized by platform.
  </Card>

  <Card title="Set Up Your Project" icon="folder-tree" href="/docs/guides/set-up-your-project">
    Turn a one-off chat into a persistent workspace with instructions, context, and schedules.
  </Card>

  <Card title="Prompt Engineering Playbook" icon="wand-magic-sparkles" href="/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.
  </Card>
</CardGroup>