List Meta Ad Accounts accessible to the current access token. Returns id (act_XXX), name, account_status, currency, business_name, spend_cap, timezone_name. Use this first to discover what you can work with.

Get detailed info for a single Ad Account: status, spend cap, balance, funding source, business, timezone, disable_reason. Returns the full configuration record — use this for deep inspection of one account.

PRE-FLIGHT CHECK: Get per-Page ads-running-or-in-review counts and limits for an ad account. Meta caps active ads per Page (default 250) and this limit is SHARED across every account using the same Page. Always call this before a bulk activation to avoid silent review failures. Returns one row per Page actor.

List campaigns in an ad account. Returns id, name, status, objective, daily_budget, lifetime_budget, bid_strategy, created_time. Paginated via limit + after cursor.

Get a single campaign by ID. Returns all default fields plus anything in fields. Use this for deep inspection of one campaign.

WRITE: Create a new campaign. Default status is PAUSED (recommended — set ACTIVE only after creating ad sets and ads). For CBO, pass daily_budget or lifetime_budget at this level; for ABO leave budget off and set it on the ad set. special_ad_categories is required (empty array [] is fine for normal advertising).

WRITE: Update any mutable field on a campaign (name, status, daily_budget, lifetime_budget, bid_strategy). Pass only the fields you want to change.

WRITE: Hard-delete a campaign (and its ad sets / ads). Prefer update_campaign with status=ARCHIVED if you want to keep historical data.

List ad sets. Pass either ad_account_id (lists all adsets in account) OR campaign_id (lists adsets of one campaign). Returns id, name, campaign_id, status, daily_budget, bid_amount, billing_event, optimization_goal, targeting, is_dynamic_creative.

Get a single ad set by ID. Returns default fields plus anything in fields.

WRITE: Create an ad set under a campaign. Default status is PAUSED. targeting is a Meta targeting spec object (geo_locations, age_min, age_max, interests, etc.). bid_amount is in account currency minor units (cents). For multi-text / dynamic creative ads you MUST set is_dynamic_creative=true — otherwise asset_feed_spec ads will be rejected.

WRITE: Update any mutable field on an ad set (status, bid_amount, daily_budget, targeting, name, etc.). Pass only the fields you want to change.

WRITE: Hard-delete an ad set (and its ads). Prefer update_adset status=ARCHIVED to keep history.

List ads. Pass either ad_account_id (all ads in account), adset_id (ads in one ad set), or campaign_id (ads in a campaign). Returns id, name, adset_id, creative, status.

Get a single ad by ID. Returns full creative + issues + preview link.

WRITE: Update an ad's name, status, or swap its creative. To replace the creative pass creative: {creative_id: 'XXX'}.

WRITE: Hard-delete an ad. Prefer update_ad status=ARCHIVED to keep history.

List ad creatives in an account. Returns id, name, object_story_spec, asset_feed_spec, thumbnail_url, video_id, image_hash, body/title.

Get a single ad creative by ID.

WRITE: Create a single-text ad creative from an object_story_spec. Pass page_id plus ONE of: video_data (for video ads — needs video_id from upload_video), link_data (for image / link ads — needs image_hash from upload_image + link + message). If the Page is not linked to Instagram, pass instagram_user_id from get_pbia() to enable IG placements.

Note: image hashes are per-ad-account in Meta — a hash uploaded on account A is NOT valid on account B. Re-upload to each target account.

WRITE: Create a DYNAMIC (multi-text) creative using asset_feed_spec. Meta will auto-combine the bodies/titles/descriptions and optimize the best mix. The parent ad set MUST have is_dynamic_creative=true. Pass arrays of texts plus either video_id(s) or image_hash(es).

WRITE: Upload a video to an ad account. Returns {id, title}. Prefer file_url (remote URL Meta fetches server-side) — streaming a local file over MCP stdio is awkward and rarely needed when videos live in S3 / Dropbox / a CDN. Local file_path is accepted for completeness but may be blocked on Windows / sandboxed MCP hosts.

WRITE: Upload an image to an ad account. Returns {images: {filename: {hash}}}. The hash is what you pass to create_ad_creative as image_hash.

IMPORTANT: Meta image hashes are SCOPED TO THE AD ACCOUNT — a hash uploaded on account A cannot be used on account B. If you need the same image across multiple accounts, call this once per account. (ScaleForge's backend caches hashes per account to avoid re-uploads within the same account.)

Pull performance metrics for ONE campaign. Default fields: spend, impressions, clicks, cpc, cpm, ctr, reach, frequency, actions, conversions, purchase_roas. Default range: last_7d. Use breakdowns for cuts (age, gender, country, placement). Use time_increment=1 for day-by-day rows.

Pull performance metrics for ONE ad set. Same fields/breakdowns as get_campaign_insights.

Pull performance metrics for ONE ad. Same fields/breakdowns as get_campaign_insights. Use this to compare creative performance at the individual-ad level.

WRITE (BULK): Pause many campaigns in a single Meta Batch API call (up to 50/request; arrays bigger than 50 are chunked automatically with a 2s delay between chunks to sidestep rate-limit code 17). Returns {results: Array<{code, body}>} — one entry per campaign. code: 200 = success.

WRITE (BULK): Activate many campaigns in one Batch API call. BEFORE activation we run a per-Page ads_volume pre-flight for every distinct ad account — warnings are returned in the response so the agent / user can abort if a Page is over capacity. Agents MUST confirm with the user before calling this (activation starts spend immediately).

WRITE (BULK): Update bid_amount on many ad sets in one Batch API call. Input is an array of {adset_id, bid_amount_cents} pairs. Bid values are in minor currency units (cents). Chunks of 50 automatically.

List Facebook Pages the current user/System User manages. Each row has id, name, access_token (Page Access Token — needed for PBIA provisioning), category, tasks (what this token can do on the Page, e.g. 'MANAGE', 'CREATE_CONTENT', 'ADVERTISE').

Get (or auto-create) a Page-Backed Instagram Account for a Facebook Page. Use this when the Page has no linked Instagram account but you want to run ads with IG placements — Meta lets a Page act as its own IG presence via PBIA (same option as 'Use Facebook Page for Instagram' in Ads Manager).

Flow: GET the Page's access_token, list existing PBIAs, create one if none exists. Returns {page_backed_instagram_account_id, created (bool)}.

Search Meta's public Ad Library for competitive research. Returns active and inactive ads matching search_terms OR search_page_ids in the selected countries. Default country = ['US']. Returns ad_snapshot_url (preview), creative bodies/titles, page_id, delivery times, publisher_platforms.

Note: only ads in categories subject to public transparency (political / housing / employment / credit) return full metadata; other categories return lighter data.