The AutoAdy MCP server

run_full_audit

Run a comprehensive audit of the entire ad account. This fetches account-level insights, all active campaigns with their metrics, and ad-level data for the top 5 campaigns by spend. USE THIS FIRST when the user asks for an audit, analysis, or account review. The returned payload contains everything needed for structured recommendations. Sales/e-commerce campaigns include result_type:'purchases' with purchases, cost_per_purchase, roas, and revenue — judge those on ROAS and cost per purchase, NOT leads/CPL.

diagnose_drop

Diagnose WHY account performance broke (CPL spiked, leads dried up, results collapsed). Runs 4-5 independent blind investigators over 35 days of daily data — creative fatigue, delivery/budget shifts (with the account's confirmed budget-change log as facts), traffic quality, offer/seasonality, and conversion tracking — then an adversarial pass tries to kill each theory. Returns a ranked cause-vs-symptom diagnosis with evidence for/against and the single most important action this week. USE THIS when the user asks why performance dropped or what broke; it prevents the default wrong guess (killing a winning creative for 'fatigue'). Takes 30-60 seconds.

get_account_insights

Get high-level KPI metrics for the ad account: spend, impressions, reach, clicks, CTR, CPM, CPC, frequency, leads, CPL. For Sales/e-commerce accounts the payload also includes result_type:'purchases' with purchases, cost_per_purchase, roas, and revenue — for those, ROAS is the primary metric, not leads/CPL. Use this first to understand overall account health.

list_campaigns

List all campaigns with their name, status, objective, and budget. Returns campaign IDs needed for deeper analysis.

get_campaign_insights

Get per-campaign performance: spend, impressions, CTR, CPM, CPC, reach, leads, CPL. Sales/e-commerce campaigns additionally return result_type:'purchases' with purchases, cost_per_purchase, roas, and revenue — compare those campaigns on ROAS/cost per purchase, never on leads (a Sales campaign showing 0 leads is NOT broken if it's driving purchases). Defaults to ACTIVE campaigns only. Use this to compare campaign performance and find winners/losers.

get_campaign_ad_insights

Get ad-level performance breakdown for a SPECIFIC campaign. Returns each ad's spend, CTR, CPM, CPC, frequency, leads, CPL, and current status. For ads in a Sales/e-commerce campaign, each ad also carries result_type:'purchases' with purchases, cost_per_purchase, roas, and revenue — rank those ads by ROAS/cost per purchase, not leads. Use this when the user asks about a specific campaign's ads, creative performance, or wants to drill into one campaign.

get_adsets

Get all ad sets inside a campaign, with their status, daily budget, and targeting info.

get_adset_insights

Get performance metrics broken down by ad set within a campaign. Ad sets in a Sales/e-commerce campaign also include result_type:'purchases' with purchases, cost_per_purchase, roas, and revenue — judge those on ROAS, not leads/CPL.

get_ads

Get individual ads inside an ad set with full creative copy: name, status, primary text, headline, description, CTA, link URL, thumbnail, and creative type. For dynamic creatives, returns all body/headline/description variations.

get_top_performing_ads

Find the best-performing ads in the account by spend and conversions. Good for identifying winning creatives. Ads from Sales/e-commerce campaigns also carry result_type:'purchases' with purchases, cost_per_purchase, roas, and revenue — for those, the 'best' ad is the one with the strongest ROAS, not the most leads. 'today' is a PARTIAL day and 'yesterday'/'today' are tiny samples — report them as snapshots, never declare winners or losers from them; prefer last_30d for decisions.

get_strategic_synthesis

Get a strategic synthesis of all pre-computed intelligence: alerts, forecasts, recommendations, benchmarks, budget allocation, and priorities. Use this when the user asks 'what should I do?', 'give me a strategy', 'what's the plan?', or any high-level strategic question. This does NOT call Meta API — it reads from our intelligence engine's cache.

analyze_creative_performance

Analyze creative performance by visual style, messaging angle, or hook tactic. Returns top and bottom performers with scores, strengths, weaknesses, and improvement suggestions. Use when the user asks 'what creative styles work best?', 'which hooks convert?', or anything about creative tag performance.

get_winning_frameworks

Cross-account winning frameworks: across ALL of the user's attached ad accounts (not just the active one), which ICP/audience (from real adset targeting), body-copy length (from real ad copy), hook, messaging angle, and creative style produce the best blended CPL — only counting patterns proven across multiple accounts with enough volume. Use when the user asks 'across all my accounts/clients, what hook/angle/ICP/copy/creative works best?', 'what's our winning playbook?', or wants a reusable framework from their whole portfolio. This is the multi-account rollup; use analyze_creative_performance for a single account.

list_lead_forms

List the Instant Lead Forms that already exist on the account's Facebook Page, with their ids, names and status. Use this to REUSE an existing form (pass its id as lead_gen_form_id to create_lead_ad / create_lead_ads) instead of creating a duplicate — matching a client's proven form matters because leads from a new form land in a separate Meta form export.

get_fatigue_forecast

Get creative fatigue predictions from the survival analysis engine. Shows which ads are fatiguing, how many days remain, and which need replacement. Reads from the intelligence cache.

backtest_rule

Replay a draft rule over the account's last 30 days of real data BEFORE creating it: how many times it would have fired, which ads it would have hit, and (for pause rules) the spend it would have avoided. ALWAYS run this before create_rule and show the user the result — 'this rule would have fired 3× last month on: …' — so they confirm on evidence, not on a description. Read-only, changes nothing.

get_account_health

Compute the account health score (0-100) with 5 components: creative diversity, fatigue risk, budget efficiency, testing velocity, waste level. Returns overall score plus component breakdowns.

audit_tracking

Audit the account's conversion tracking health (read-only): Meta Pixel presence + freshness (last fired), server-side/Conversions-API event detection (via pixel stats by source), and UTM hygiene on ad URLs. Returns a 0-100 score with prioritized findings. USE THIS as part of an account audit, or BEFORE trusting a performance drop — a tracking break looks exactly like a real drop. Pairs with the Audit and Diagnose skills.

list_pixels

List the Meta Pixels (datasets) on the ad account: id, name, and when each last fired (read-only). USE THIS to find the pixel_id for create_adset with OFFSITE_CONVERSIONS — e.g. building a website-conversion Leads campaign — so the user never has to dig it out of Events Manager. A pixel that has NEVER fired, or not fired recently, is a warning: Meta optimizes poorly against an event it hasn't seen — verify the installation (audit_tracking) before launching on it.

list_custom_audiences

List the account's custom + lookalike audiences: id, name, subtype, approximate size, delivery status (read-only). USE THIS before creating audiences (avoid duplicates) and to get the ids for create_adset targeting (custom_audience_ids / excluded_custom_audience_ids) or the seed for create_lookalike_audience.

plan_scale_axis

Plan HOW to scale a winner — vertical (raise budget), horizontal (duplicate to a new audience), bid-cap (Tichenor), or target-ROAS (Faris) — and return the exact execution parameters (budget step, bid amount, duplication method). Pass axis='auto' to let it pick vertical vs horizontal from frequency/CPA-inflation. This is advisory: it returns the plan; execute vertical via scale_budget_relative and horizontal via duplicate_adset. Use with the Scale skill.

get_playbook_template

Get a multi-week tactical playbook (dated week-by-week checklist) for a campaign window. Call with no slug to list available templates: bfcm, product-launch, lead-gen-ramp, recovery, scale-ladder. Use with the Playbooks skill when the user wants a BFCM/launch/recovery/scaling plan.

get_roi_metrics

Calculate AutoAdy's ROI for this account: money saved from pausing bleeders, time saved from automation, performance improvement, and ROI multiplier vs subscription cost.

get_daily_briefing

Get the account's daily briefing: AI narrative + headline, mood, week-over-week deltas, current winners and bleeders, budget recommendations, and alert/fatigue summary. Numbers come from a SETTLED 7-day-vs-7-day window (ends yesterday — today's partial day is excluded so attribution lag can't fake a decline), and results count each ad set's real optimization event (custom conversions included), never name-guessed leads. Purchase-optimized accounts read as purchases/cost-per-purchase. Served from a 30-minute cache when fresh; pass force:true to regenerate. USE THIS for 'morning briefing', 'how are we doing', or any daily status question.

get_findings

List the open findings from AutoAdy's continuous account scan — the same actionable to-do queue shown on the dashboard (bleeders to kill, winners to scale, anomalies, tracking issues). Each finding has a severity, plain-English rationale, a proposed action, and an expected impact measured over the finding's own data window (NOT a monthly projection). Findings auto-resolve when the underlying entity recovers, so this list is live, not a stale report. Use resolve_finding to mark one handled.

resolve_finding

Mark one scan finding as resolved/handled so it leaves the findings queue (on the dashboard and in get_findings). This changes AutoAdy app state only — it never touches the Meta account. Use after the user has acted on a finding (or explicitly dismisses it). Pass the finding id from get_findings.

get_top_performers

Statistically proven winners, grouped by creative dimension: which primary text (copy), headline, landing page, or video hook actually performs best. Unlike get_top_performing_ads (individual ads ranked by spend), this aggregates every ad sharing the same copy/headline/page/hook and ranks groups by real cost per result — with a 95% z-test confidence flag vs the account average, a minimum-results trust floor so 1-lead flukes can never rank as winners, and a settled-window CPL trend (improving/worsening). Purchase-optimized accounts rank on ROAS/cost-per-purchase automatically. USE THIS for 'what copy/headline/hook is winning', 'what should we make more of', or creative strategy questions.

get_decision_history

The account's decision ledger (proof of work): every action AutoAdy or the agent executed — pauses, budget changes, launches — with when, why (source), the before-snapshot, and the MEASURED impact where computed (CPL/leads/spend before vs after, and a verdict). USE THIS for 'what did AutoAdy do', 'did that budget change work', accountability questions, or before repeating an action that was recently tried. Every write tool logs here automatically.

pause_ad

Pause a specific ad by setting its status to PAUSED. Use this when an ad has high frequency, poor CTR, or excessive CPL. Every pause is logged to the decision ledger with a before-snapshot (auditable via get_decision_history) and is reversible with enable_ad.

enable_ad

Re-enable a paused ad by setting its status to ACTIVE. Use this to reactivate ads that were previously paused.

adjust_campaign_budget

Adjust the daily budget of a campaign. The budget value must be in cents (e.g. 2000 = €20.00/day). Use this to scale winning campaigns or reduce spend on underperformers. Returns a before→after receipt and logs to the decision ledger (auditable via get_decision_history).

bulk_pause_ads

Pause multiple ads at once. Use when you need to pause all bleeders in a campaign or a list of specific ads. More efficient than calling pause_ad multiple times. Each pause is individually logged to the decision ledger with a before-snapshot; one ad failing never aborts the rest.

bulk_enable_ads

Re-enable multiple paused ads at once. Use to reactivate a batch of ads.

scale_budget_relative

Scale a campaign's daily budget by a percentage. Example: +20% increase or -15% decrease. Automatically fetches the current budget, computes the new value, and applies it. Returns the old→new budget and logs to the decision ledger (auditable via get_decision_history).

pause_adset

Pause an ad set. All ads within it will stop delivering.

enable_adset

Re-enable a paused ad set.

duplicate_ad

Duplicate an ad to a different ad set. Use to copy winning creatives into new audiences or test campaigns.

duplicate_adset

Duplicate an ad set to the same or different campaign, preserving its EXACT targeting (city/radius geo, exclusions), bid strategy and bid cap — things create_adset cannot always reproduce. New ad set is created PAUSED. By default the ads come too; pass include_ads: false to copy the ad set SHELL ONLY and then load your own creatives with create_lead_ads. Use include_ads: false when the source has several ads — Meta rejects a deep copy of more than a couple of objects ('fewer than 3 objects per copy'), and a shell copy has no such limit.

update_adset_targeting

Update specific targeting fields on a LIVE ad set without touching the rest: countries (narrow a broad/Europe-wide set to an exact country list), location_types (['home'] = residents only — removes travelers/visitors; ['home','recent'] = Meta's default), Advantage+ audience expansion on/off, age range, and placements. Read-modify-write: the current targeting is fetched first and ONLY the passed fields change — everything else is preserved exactly. The previous targeting is saved to the decision ledger for rollback. Placement notes: Meta re-validates the WHOLE targeting object on any edit, so a legacy manual placement set it now considers invalid (e.g. 'Instagram Explore home without Instagram Explore') blocks EVERY update — fix it in the same call by passing instagram_positions with the missing position added, or advantage_placements: true to switch to automatic. Note: editing targeting on a delivering ad set resets its learning phase.

create_campaign

Create a NEW Meta campaign — the top-level container an ad set and ads live in. Created PAUSED (never spends until you launch it). Default objective is OUTCOME_LEADS (lead-gen / instant-form). This is the top of the build chain: create_campaign → create_adset (copy a proven ad set's targeting via target_campaign_id) → create_lead_ads (load creatives). Budget: OMIT daily_budget for ABO (budget set per ad set — the common lead-gen case), or PASS daily_budget for CBO (one budget shared across the campaign's ad sets).

set_campaign_status

Set a campaign's status to ACTIVE (launch it) or PAUSED (stop it). This is the final step of an MCP build chain: create_campaign → create_adset → create_lead_ads → enable_adset + bulk_enable_ads → set_campaign_status ACTIVE. Without this a campaign created through the MCP stays PAUSED forever. Verified by a post-write read-back. Note ACTIVE on the campaign alone does not deliver — the ad set and ads must be ACTIVE too.

create_adset

Create a NEW EMPTY ad set (no ads) in two possible ways. (A) COPY MODE — pass source_adset_id to clone a proven ad set's targeting, optimization goal, budget and promoted object; best when you want to reuse exact existing targeting such as a verified city/radius setup. (B) BUILD MODE — omit source_adset_id and pass campaign_id + targeting params to build one from scratch: countries and/or cities with radius, age, genders, locales, placements, optimization goal, and an ABO daily_budget with an optional bid cap. Created PAUSED. Follow with create_lead_ads (instant-form ad sets) or create_website_ads (OFFSITE_CONVERSIONS/website ad sets) to load creatives. If copy mode fails because the source uses a bid cap or hits Meta's copy limits, use build mode, or duplicate_adset with include_ads: false.

create_lead_form

Create a NEW Instant Lead Form — the form that opens when someone taps a lead ad. Returns a form_id you then attach with create_lead_ad / create_lead_ads (lead_gen_form_id). Use CUSTOM multiple-choice questions to gate for intent (a 'hard-gate' qualifying form) and higher_intent:true to add Meta's extra review step before submit. Without this tool a new ad set can only inherit an OLD form from an existing ad — this is how you launch with a fresh, purpose-built form.

create_lead_ad

Create a lead-form (instant form) ad from a CUSTOM image URL in an existing ad set. Uploads the image and attaches the lead form + page so it is a real instant-form ad (not a link ad). Created PAUSED. If lead_gen_form_id is omitted it inherits the form from an existing ad in the ad set. Use after create_adset to load your own creatives with matched copy.

create_lead_ads

Batch of create_lead_ad — create MANY lead-form ads (each a custom image + its matched copy) in ONE existing ad set in a single call. Up to 15. Created PAUSED, throttled to protect the account from Meta rate limits, and resilient: one ad failing never kills the rest. Returns which succeeded/failed. Use to load a whole creative batch at once.

create_website_ad

Create a WEBSITE (link) ad in an existing ad set — it clicks through to a landing page URL instead of opening an instant form. This is the ad type for pixel/conversion ad sets (create_adset with OFFSITE_CONVERSIONS + pixel_id). The creative comes from EITHER image_url (uploads a new image) OR source_ad_id (reuses a winning ad's EXACT image by hash, no re-upload, and inherits its primary text/headline/description/CTA unless you override them — the way to carry proven creatives into a new website campaign). Created PAUSED. Instant-form ad sets (LEAD_GENERATION) are refused with guidance instead of a cryptic Meta error — use create_lead_ad for those.

create_website_ads

Batch of create_website_ad — create MANY website (link) ads in ONE existing ad set in a single call. Up to 15. Each ad brings its own creative: image_url to upload, or source_ad_id to reuse a winning ad's exact image + copy (override any field per ad). The top-level link_url and url_tags apply to every ad unless overridden per ad. Created PAUSED, throttled against Meta rate limits, and resilient — one ad failing never kills the rest. This is the tool for 'rebuild the winners as a website-conversion campaign'.

apply_all_kills

Execute ALL kill recommendations from the intelligence engine at once. Reads the recommendations cache and pauses every ad flagged for kill. Use when the user says 'apply all recommendations' or 'pause all bleeders'.

apply_budget_allocation

Apply the Thompson Sampling budget rebalance. Reads the budget_allocation from the intelligence cache and adjusts all campaign budgets to their recommended values. Use when the user says 'rebalance budgets' or 'apply budget allocation'.

create_rule

Create an automation rule from natural language. Converts the user's intent into a structured rule with conditions and actions. Example: 'pause any ad with CTR below 0.3% after spending €10' → rule with metric=ctr, operator=<, value=0.3, action=pause_ad. WORKFLOW: (1) compile the user's intent, (2) run backtest_rule with the same condition and SHOW the user what it would have done over the last 30 days, (3) create only after they confirm. Default mode is 'suggest' — the rule proposes and the user approves each action; only set mode='auto' when the user explicitly asks for automatic execution.

trigger_creative_generation

Start AI creative generation. Generates a brand-aware ad image. BEFORE calling this tool, you MUST confirm with the user: (1) what language the ad text should be in, (2) any specific message or hook to use. Only call this tool ONCE per user request — never retry.

rotate_fatigued_ad

Rotate a fatigued ad: pause it AND switch on the newest replacement already staged paused in the same ad set. Does nothing if no replacement is staged — a pause with no successor is lost delivery, not a rotation.

create_custom_audience

Create a WEBSITE custom audience from a pixel rule — entirely via API, no Business Manager. Two rule kinds: url_contains ("/booking" → retargeting audience of page visitors) or event_name ("Lead" or a custom name like "lead_booked" → CONVERTERS audience, the ideal lookalike seed and exclusion list). Default: all website visitors. If Meta requires the one-time Custom Audience Terms acceptance, the error returns the exact one-click link — the only step the API can't do. The audience fills as the pixel fires (needs ~100+ people to serve or seed a lookalike).

create_lookalike_audience

Create a LOOKALIKE audience from an existing custom audience — Meta finds people similar to the seed (e.g. a converters audience from create_custom_audience). ratio 0.01–0.10 (1% = tightest match, start there), one 2-letter country per call. The source must belong to this account and hold 100+ people in the target country; Meta populates the lookalike over ~1–24h. Target it with create_adset (custom_audience_ids).

send_pixel_event

Send ONE server-side conversion event to a pixel via the Conversions API. USE THIS to (a) verify CAPI plumbing with a test_event_code (shows in Events Manager → Test Events, does NOT enter optimization/reporting), or (b) make an event EXIST on the pixel — Meta won't optimize cleanly toward an event it has never seen, so a brand-new "Lead"/custom event needs one real fire before launching an ad set on it. A provided email is SHA-256 hashed before sending, never sent raw. Real events (no test code) enter reporting — send them only for genuine conversions or a deliberate one-off unblock the user approved.

analyze_competitor

Analyze a competitor's ad strategy using the Meta Ad Library. Provide a competitor name or page ID to see their messaging themes, creative styles, CTA patterns, and opportunities to differentiate. Agency plan only.

apply_playbook

Apply a pre-built optimization playbook to a campaign. Available playbooks: bleeder-killer, winner-scaler, creative-refresher, budget-optimizer, ab-auto-graduate, full-autopilot.

enable_autopilot

Enable autopilot for a campaign with smart defaults calibrated to this account's performance history. Pro plan required.

url_to_ads

Full pipeline: extract brand DNA from a URL and generate up to 50 ad creative variants across multiple angles, hooks, and visual styles. Returns task IDs for image generation. Best for: new brands, product launches, initial creative library. Pro plan required.

multiply_winner

Take a winning ad and generate 10+ variations preserving the winning DNA but rotating visual style, hook, and messaging angle. Provide ad_id or image_url. Best for: scaling proven creatives, creative refresh.

competitor_creatives

Analyze competitor Meta ads, reverse-engineer their best creatives into templates, then generate your own branded versions using your brand DNA. Agency plan required.

creative_matrix

Scientific A/B test: specify angles × hooks × visual styles to generate all combinations (max 27). Each combo produces a unique ad creative for testing.

emergency_recovery

Emergency performance recovery: detects fatigued/bleeding ads, pauses underperformers, and generates rapid replacement creatives. Use when account performance drops.

enable_creative_loop

Enable the autonomous creative loop: auto-detects fatiguing ads, generates replacements, optionally auto-launches winners. Pro plan required.

extract_creative_dna

Extract brand DNA from a website URL: visual identity, voice profile, target avatar, winning patterns, unique mechanism. Foundation for all creative generation. Pro plan required.

audience_mirror

Analyze which demographics convert best and suggest matching avatar descriptions + settings for creative generation. Saves audience demographics to brand memory.

placement_optimize

Generate placement-specific creatives: Feed (4:5), Reels (9:16), Stories (9:16), Right Column (1:1). Each gets content designed for its consumption pattern.

retargeting_ladder

Generate funnel-stage-specific creatives: Cold (awareness), Warm (consideration), Hot (conversion), Buyer (retention). Each stage gets psychologically matched content.

creative_autopsy

Analyze recently failed/paused ads to extract anti-patterns. Learns what NOT to do and saves patterns to Creative DNA for future avoidance.

testimonial_mine

Turn customer testimonial quotes into social proof ad creatives. Provide an array of quote strings and get branded testimonial ads.

content_calendar

Create a multi-week content calendar with themed weeks and angle rotations. Saves the calendar to brand memory for scheduled execution.

product_launch_blitz

Maximum-scale product launch: generates 50 ads across 6 messaging angles from a single URL. Uses all available angles for maximum coverage.

cross_platform_cascade

Generate creatives optimized for multiple platforms: Meta Feed, Meta Reels, TikTok, Pinterest, Website. Each platform gets native aspect ratios and style.

analyze_winning_ad

Deep analysis of a single ad: returns the actual creative image/video URL, full ad copy (primary text, headline, description, CTA, link), adset targeting (age, gender, locations, interests, behaviors, custom audiences, placements), adset budget + optimization goal, and campaign objective + budget type. Use after get_top_performing_ads to understand WHY a winner works before multiplying it. If it's a video ad, returns the video source URL.

get_workflow_status

Check the status of a running workflow (url_to_ads, multiply_winner, etc.).