> ## Documentation Index
> Fetch the complete documentation index at: https://adadvisor.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Available Tools and Capabilities

> Complete reference for every tool your AI assistant can use through AdAdvisor for reading, creating, and managing your Meta ad campaigns.

Once connected, your AI assistant can read, create, and manage everything in your Meta (Facebook and Instagram) ad accounts. Describe what you want in plain English and it handles the rest.

This page covers every tool, what it does, and an example of how to use it.

> [!NOTE]
>
> Tools that create or change things always ask for your confirmation first. Nothing happens on your ad account without you saying yes.

## Reading your data

Browse what's in your ad account: campaigns, ad sets, ads, creatives, and audiences. These pull from your synced data.

| Tool | What it does | Example prompt |
| - | - | - |
| `list_ad_accounts` | Lists all your Meta ad accounts with name, ID, currency, sync status, and pixel info. Always the first tool called. | *"What ad accounts do I have connected?"* |
| `list_pages` | Lists Facebook Pages your ad account can advertise on behalf of, with the task permissions your token has on each (ADVERTISE, MANAGE\_LEADS, etc.). The first page returned is the default used by lead form creation. | *"Which Facebook Pages can I run ads on for this account?"* |
| `list_campaigns` | Lists campaigns with objective, budget type, bid strategy, schedule, status, and special ad category (housing, employment, credit — which restricts what targeting is allowed). You can filter by name or status. | *"Show me all active campaigns in my account"* |
| `list_adsets` | Lists ad sets with targeting, budget, optimization goal, schedule, and destination — whether leads go to an instant form, your website, a messaging thread, or a phone call. You can filter by campaign. | *"What ad sets are running under my summer sale campaign?"* |
| `list_ads` | Lists ads with their creative reference, tracking specs, and parent campaign/ad set IDs. You can filter by campaign or ad set. To see what an ad actually runs, pass its creative ID to `list_creatives`. | *"Show me all the ads in my retargeting ad set"* |
| `list_creatives` | Lists ad creatives with type, copy, headline, call-to-action, asset info, and the lead form attached (if any). Look up specific creatives by ID to get the full untruncated copy — that's how you answer "which lead form does this ad use?". | *"What creatives do I have available in this account?"* |
| `list_custom_audiences` | Lists custom audiences with type (website visitors, lookalike, customer list, engagement), approximate size, and delivery status. | *"Show me all my custom audiences and their sizes"* |
| `list_media_assets` | Browses your Creatives Hub — every image and video AdAdvisor holds for your business, whether AI-generated, uploaded by you, or pulled in from a store connector. Assets here can be pushed to your ad account with `register_media_assets`. | *"What creative assets do I have in the hub?"* |
| `list_promotable_posts` | Lists organic Facebook Page posts and Instagram media you can turn into ads. Boosting an existing post keeps its likes, comments, and shares instead of starting from zero. | *"Show me my recent Instagram posts so I can boost one"* |

## Performance and analytics

Get aggregated metrics, daily trends, and pixel health diagnostics. Performance data refreshes every 30 minutes.

| Tool | What it does | Example prompt |
| - | - | - |
| `get_performance` | Aggregated KPIs (spend, revenue, ROAS, CPA, CPM, CTR, conversions, etc.) for campaigns, ad sets, or ads over any date range. For lead campaigns it can also break leads down by where they came from — instant form vs website pixel vs offline/CRM — which matters when you run more than one lead destination. | *"What's my ROAS across all campaigns for the last 30 days?"* |
| `get_timeseries` | Daily time-series metrics for a single campaign, ad set, or ad. One row per day with all KPIs. Good for spotting trends. | *"Show me the daily spend and ROAS trend for my top campaign over the last 2 weeks"* |
| `get_pixel_health` | Pixel diagnostics: event counts, source breakdown (browser vs Conversions API), host breakdown, and automatic matching status. Pulls fresh data from Meta. | *"Is my pixel firing correctly? Check for any tracking issues"* |

## Targeting and audiences

Find targeting options, estimate reach, and create custom or lookalike audiences. These tools call the Meta API directly.

| Tool | What it does | Example prompt |
| - | - | - |
| `search_targeting` | Searches Meta's targeting catalog by keyword. Covers interests, geolocation, behaviors, income, life events, industries, job titles, employers, and locales. Returns valid IDs you can use in ad sets. | *"Find targeting options related to golf"* |
| `estimate_audience_size` | Estimates how many people match a targeting spec (geo, demographics, interests, custom audiences) without creating anything. Returns upper and lower bounds. | *"How big is the audience for women 25-34 in the US interested in yoga?"* |
| `create_website_audience` | Creates a custom audience from pixel events (Purchase, AddToCart, ViewContent, etc.) with a retention window of 1 to 180 days. | *"Create an audience of everyone who purchased in the last 90 days"* |
| `create_lookalike_audience` | Creates a lookalike audience from an existing custom audience seed. You pick the country and how broad the match should be (1% = most similar, up to 20%). Takes 1-6 hours to populate. | *"Create a 1% US lookalike from my purchasers audience"* |
| `update_adset_targeting` | Replaces the targeting on an existing ad set. Covers geo, demographics, interests, behaviors, custom audiences, exclusions, and placements (which platforms and surfaces the ad set may run on). Validates against Meta's reach estimate before applying. Because it replaces the whole spec, anything you don't re-supply is cleared. | *"Update my prospecting ad set to target men 25-44 in California interested in fitness"* |

## Creative management

Browse, preview, and create ad creatives. This section includes interactive visual pickers, which are unique to AdAdvisor.

| Tool | What it does | Example prompt |
| - | - | - |
| `search_ad_images` | Searches images in your ad account's library and opens a **visual picker** where you click to select one. Returns the image hash for use in creative creation. | *"Show me the images I have for the green watch campaign"* |
| `search_ad_videos` | Searches videos in your ad account's library and opens a **visual picker** where you click to select one. Returns the video ID for use in creative creation. | *"Browse my video assets, I want to pick one for a new ad"* |
| `preview_existing_creatives` | Finds existing creatives that use the same image or video and shows a **visual preview** with engagement metrics (reactions, comments, shares). You can reuse a creative to keep its social proof instead of starting from zero. | *"Before making a new creative with this image, check if it's already being used somewhere with good engagement"* |
| `upload_creatives` | Opens an **upload widget** where you can drag and drop images (JPG, PNG, up to 30 MB) or paste URLs to images and videos (MP4, MOV). Supports multiple files at once with per-item progress. Uploaded assets are immediately available for use with create\_creative. | *"I want to upload some new images for my campaign"* |
| `register_media_assets` | Pushes assets from your Creatives Hub into a specific ad account so they can be used in ads. Inert — it copies files, it doesn't create or change any campaign. | *"Get that AI-generated hero image ready to use in this ad account"* |
| `create_creative` | Creates a new ad creative. Formats: **image ads**, **video ads**, **carousels** (2-10 swipeable cards, each with its own image or video, headline, and destination), and **existing post promotions** (Facebook or Instagram). Also builds **lead ads** (with an instant form attached) and **click-to-call ads**. Supports multi-variant copy (up to 5 headlines, messages, and descriptions) and serving a different aspect-ratio cut per placement from one creative. | *"Create a carousel with these three images, each linking to a different product"* |

> [!NOTE]
>
> **Interactive visual pickers** are unique to AdAdvisor. When you search for images or videos, a visual grid opens in your AI client where you can browse thumbnails and click to select. No copy-pasting IDs. This also works when previewing existing creatives with their engagement metrics.

## Campaign creation

Build new campaigns from scratch: campaign, ad sets, and ads. Everything gets created paused so you can review before going live.

| Tool | What it does | Example prompt |
| - | - | - |
| `create_campaign` | Creates one or more campaigns with a specified objective (OUTCOME\_SALES, OUTCOME\_TRAFFIC, OUTCOME\_LEADS, etc.), budget, and bid strategy. You can create multiple at once. | *"Create a new OUTCOME\_SALES campaign with a \$100 daily budget called 'Summer Collection 2026'"* |
| `create_adset` | Creates one or more ad sets with targeting, budget, optimization goal, schedule, and placements. Optimization goals cover conversions, traffic, reach, lead volume, lead *quality* (Conversion Leads), and call quality. Targeting gets validated against Meta's reach estimate before creation. | *"Create an ad set targeting US women 25-34 interested in yoga with a \$50 daily budget"* |
| `create_ad` | Creates one or more ads by attaching a creative to an ad set. You can attach multiple creatives to the same ad set for A/B testing. Warns you if a creative and its ad set disagree about lead generation — for example an instant-form ad set paired with a creative that has no form, which Meta accepts but which can never collect a lead. | *"Create an ad in my fitness ad set using the creative I just made"* |

> [!TIP]
>
> The typical creation flow is: **create\_campaign** > **create\_adset** > **create\_creative** > **create\_ad** > review > **change\_entity\_status** to go live.
>
> For lead generation, see the [dedicated section below](#lead-generation).

## Lead generation

Build and run native lead campaigns end to end — instant forms that open inside Facebook or Instagram, so people never leave the app.

| Tool | What it does | Example prompt |
| - | - | - |
| `check_lead_gen_readiness` | Checks whether the account can actually run lead gen *before* you build anything. Lead generation has several independent prerequisites — an advertisable Page, the right permissions, lead access on the Page, and Meta's Lead Ads terms accepted — and each one fails at a different point with a different unhelpful error. This reports all of them at once, with what to do about each. | *"Am I set up to run lead ads on this account?"* |
| `list_lead_forms` | Lists the instant forms on your Facebook Page with status, leads collected, locale, and the question types each one asks. Filter by status or search by name. | *"Show me all the active lead forms on my page"* |
| `get_lead_form` | Opens a single form in full: every question with its answer options, the intro screen, the thank-you screen, consent checkboxes, and lifetime lead counts. **A form's questions can never be edited after it's created**, so reading one back is the only way to judge whether it fits a campaign — or whether you need a new one. | *"What does my 'Free Consultation' form actually ask people?"* |
| `create_lead_form` | Creates an instant form on a Facebook Page. Standard fields (name, email, phone), custom multiple-choice questions, appointment scheduling, store locator, and country-specific national IDs. Plus an intro screen, a thank-you screen with a follow-up button, custom consent checkboxes for regulated industries, and quality filters like work-email-only or SMS verification. | *"Create a lead form called 'Free Consultation Request' asking for name, email, phone, and which service they want — paid ads, SEO, or web design"* |
| `set_lead_form_status` | Archives a form or brings it back. **Meta does not allow deleting lead forms** — archiving is the only way to retire one, and it's the only property of a form that can be changed after creation. | *"Archive the old intake form, we've replaced it"* |
| `create_lead_form_audience` | Builds a custom audience from how people interacted with a form: those who submitted it, those who opened it, or those who opened it and dropped off. Drop-offs are the warmest retargeting pool a lead campaign produces; submitters are usually worth *excluding* from prospecting so you stop paying to re-acquire them. | *"Create an audience of people who opened my form but didn't finish it"* |

> [!TIP]
>
> **The lead generation flow:** `check_lead_gen_readiness` > `create_lead_form` (or reuse one via `list_lead_forms` + `get_lead_form`) > `create_campaign` with objective `OUTCOME_LEADS` > `create_adset` with optimization `LEAD_GENERATION` and destination `ON_AD` > `create_creative` with the form attached > `create_ad` > review > `change_entity_status`.
>
> Your assistant handles the fiddly parts for you: the ad set needs a `promoted_object` naming the Page or Meta rejects it, and the creative needs a specific placeholder link and call-to-action shape.

> [!NOTE]
>
> **Reading the leads themselves is not available yet.** Downloading submitted lead data requires a separate Meta permission that is still under review. Until it's approved, collect your leads from Meta Ads Manager or your Page's Leads Center, or wire up a CRM integration in Meta. Everything else on this page — creating forms, running lead campaigns, building audiences from form activity — works today.

## Optimization and control

Pause, resume, and adjust budgets and settings on campaigns, ad sets, and ads. Changes take effect on Meta immediately.

| Tool | What it does | Example prompt |
| - | - | - |
| `change_entity_status` | Pauses or resumes a campaign, ad set, or ad. Safe to call multiple times (pausing something already paused won't error). Includes before/after state snapshots. | *"Pause all ad sets with a ROAS below 1.5x"* |
| `change_entity_budget` | Updates the daily or lifetime budget on a campaign or ad set. Values are in your account's currency (not cents). Rejects changes larger than 2x in either direction unless you confirm, so a misread number can't blow up your spend. | *"Increase the daily budget on my best campaign by 25%"* |
| `update_entity` | Edits the long-tail settings the dedicated tools don't cover: names, schedules, bid strategy, spend caps, special ad categories, ad set destination and conversion settings, and archiving or deleting. Includes before/after state snapshots. | *"Rename this campaign and set a \$5,000 lifetime spend cap"* |

## Duplication

Copy campaigns, ad sets, or ads to scale what's working. Duplicates are created paused so you can adjust before activating.

| Tool | What it does | Example prompt |
| - | - | - |
| `duplicate_campaign` | Copies a campaign with all its ad sets and ads (deep copy), or creates an empty shell you fill selectively. The copy can be named or auto-named with a reason tag (COPY, SCALE, TEST, ISOLATE). | *"Duplicate my best performing campaign for a scaling test"* |
| `duplicate_adset` | Copies an ad set into the same or a different campaign. Good for testing the same targeting under a different budget, or moving a proven ad set into a new campaign. | *"Duplicate this ad set into my new campaign"* |
| `duplicate_ad` | Copies an ad into the same or a different ad set. Good for A/B testing the same creative under different targeting. | *"Copy my top ad into the lookalike audience ad set"* |

## Resources

On top of tools, the MCP exposes resources that give your AI context about your business. These get read automatically when needed.

| Resource | What it provides |
| - | - |
| **Account Context** | Business thresholds (break-even ROAS, AOV, target CPL, daily budget cap), account metadata (currency, timezone), and the AI-generated business research report. This is how your AI knows what "good" looks like for your specific business. |
| **Visual Asset Picker** | An interactive widget that shows image or video thumbnails in a grid. You click to select, no need to copy-paste hashes or IDs. Opens automatically when you search for images or videos. |
| **Creative Preview** | An interactive widget that shows existing creatives with their engagement metrics (reactions, comments, shares). Click "Use This Creative" to reuse one and keep its social proof. Opens automatically when previewing creatives. |
| **Upload Widget** | An interactive widget for uploading images and videos to your ad account. Drag and drop files or paste URLs. Supports multiple uploads at once with progress tracking. Opens when you use upload\_creatives. |

## Tool count by category

| Category | Tools | Type |
| - | - | - |
| Reading your data | 9 | Read-only |
| Performance and analytics | 3 | Read-only |
| Targeting and audiences | 5 | Mixed (2 read, 3 write) |
| Creative management | 6 | Mixed (3 read, 3 write) |
| Campaign creation | 3 | Write |
| Lead generation | 6 | Mixed (3 read, 3 write) |
| Optimization and control | 3 | Write (idempotent) |
| Duplication | 3 | Write |
| Lead retrieval (built, switched off) | 4 | Read-only |
| **Total** | **42** | |

> [!NOTE]
>
> **A `tools/list` call will not match this number exactly, in either
> direction.** The 42 are every tool built for you to drive. Four of them
> (`list_leads`, `get_lead`, and the two test-lead helpers) are switched off
> until Meta approves the `leads_retrieval` permission, so today your client
> will list 38. Going the other way, the server also registers four internal
> upload helpers that sit behind the `upload_creatives` widget rather than
> being called by name; those are not counted here at all.

## What's coming next

We're actively adding to the MCP. Coming soon:

* **Lead retrieval** - downloading submitted lead data directly through your assistant, once Meta approves the permission it requires
* **More platforms** - Google Ads, TikTok, and others
* **Deeper analytics** - attribution modeling, cohort analysis, and automated reporting

> [card] [Set Up Your Client](https://adadvisor.ai/docs/ai/setting-up-your-mcp-client.md)
>
> Connect your AI tool to AdAdvisor in 5 minutes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.