Meta tools

Meta ad accounts reachable with the connected Meta token: id (act_…), name, currency, status, timezone, lifetime spend, business, and which one is selected. Read only; connected=false when Meta is not linked.

This tool takes no parameters.

Facebook + Instagram performance (Meta Insights) at campaign, ad set or ad level for a date range, optionally broken down by age, gender, placement or device: spend, impressions, reach, frequency, clicks, CTR, CPM, CPC, conversions, revenue, ROAS (purchase_roas) and CPA (cost_per_action_type). Sort by any metric and filter with thresholds (e.g. roas_below=3 sorted by spend, cpa_above=40). Real data only.

Best-performing Meta ads (creatives) in a placement such as Instagram Reels, ranked by ROAS, CPA, conversions or CTR, with creative details (thumbnail, video, Instagram permalink) and their ad set ids for duplication.

Custom and lookalike audiences of the Meta ad account: id, name, subtype, approximate size range, retention, delivery status.

Search Meta detailed targeting by keyword: interests (default) or behaviours, life events, industries, family statuses, income and demographics — id, name, path and audience size range. Use the ids in targeting.interest_ids / behavior_ids / life_event_ids …

Estimated audience size for a targeting set before spending (Meta delivery estimate, falling back to reach estimate): monthly active users range and daily users.

Meta ad sets with status, daily/lifetime budget (account currency), bid, optimisation goal, targeting and schedule.

Recent Instagram posts of the connected Instagram business account with likes, comments and engagement, sorted by engagement — to pick a post to boost.

Lead (instant) forms of the Facebook Page with status and lead counts. Create one with create_meta_lead_form.

Lead counts for one lead form over the last N days, by day, by ad and by platform. Counts only; personal answers are never returned.

Product catalogs owned by the user's Meta businesses (Commerce Manager): id, name, product count, vertical, business. Needs catalog_management; connected=false when Meta is not linked.

Products of a Meta catalog with retailer id, price, availability, condition, URL, image, review status and rejection reasons; filter by review status or Graph filter. Read only.

Product sets of a Meta catalog (id, name, product count, filter) for catalog sales ad sets, plus the catalog's product feeds with their latest upload result. Read only.

Facebook Pages the connected Meta user manages (id, name, category, tasks, linked Instagram account) or, with promotable_only, the Pages the ad account can advertise for. Read only.

Campaigns live in the Meta ad account (including ones made outside this app): id, name, status, objective, daily/lifetime budget in account currency, bid strategy, schedule. Read only.

Meta ads of the account, an ad set or a campaign: id, name, status, effective status, ad set, creative id and thumbnail. Read only.

Recent posts of a Facebook Page with text, picture and permalink, to reuse an organic post as an ad (object_story_id). Read only.

Meta pixels (datasets) of the ad account with name and last fired time. Read only.

Free-form read of the Meta Insights API for anything the ready reports don't cover: any field, breakdown, action breakdown, filter and time increment Meta supports. Returns raw rows. Read only.

Instagram accounts usable for ads: those attached to the ad account and those linked to the user's Facebook Pages (id, username, page). Read only.

This tool takes no parameters.

Saved audiences (reusable targeting presets from Ads Manager) with targeting and approximate size. Read only.

Custom conversions of the ad account: id, name, rule (URL / event), event type, pixel, last fired, default value. Read only.

Activity history of the Meta ad account: who changed what and when (budget, status, targeting, creative edits), with old/new values when Meta provides them. Read only.

Meta's delivery estimate for an existing ad set's current targeting: reachable monthly users, daily users and the expected-results curve, without spending. Read only.

Render a preview of a Meta creative or ad in a placement format (feed, story, reels …) without publishing; returns a temporary preview URL. Read only.

Read an ad's current creative: headline, primary text, description, image or video, button, destination link, Page / Instagram identity and which Advantage+ creative features are enrolled. Read only.

Resolve an Instagram post or Reel link to its media id (needed for boost_instagram_post) by scanning the selected Instagram business account's media. Read only.

Daily new followers of an Instagram business account over the last up to 30 days plus the current follower count, to measure follower and profile-visit campaigns. Read only.

Download the answers submitted through a Meta instant form (every question, plus the ad, ad set and campaign of each lead). Personal data: needs leads_retrieval; handle under the form's consent. Read only.

Choose which Meta ad account all further Meta tools work in (agency / multi-account). Only accounts the user can access are accepted.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a website custom audience from the Meta pixel (e.g. added to cart in the last 30 days but did not purchase). Applied directly when the user asks; the audience populates within hours.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta lookalike audience (1–10%) of a custom audience in one or more countries. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta campaign end to end (campaign + ad set + ad when a page and creative exist) as a paused draft with objective, daily budget and targeting. Writes a ledger draft and sends it to Meta directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Change a Meta campaign's budget (daily/lifetime), status, name, bid strategy or spend cap. Applied directly when the user asks; the result shows before → after; budget increases above +50% per step are blocked.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Change a Meta ad set's budget, status, targeting (locations, age, gender, interests, audiences, placements), bid or schedule. Applied directly when the user asks; the budget guardrail applies.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Duplicate a winning Meta ad set (with its ads) as a paused copy and give it a new interest audience, targeting or budget for a test. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Find active Meta ad sets whose CPA is above a threshold (or that spent at least the threshold with zero results), pause them in one action and move their freed daily budget to the best-CPA ad set within the +50% guardrail. Shows the list first; applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta carousel ad (2–10 image cards, e.g. five product images) in an ad set for Facebook and Instagram. Studio images are uploaded to Meta (adimages). Created paused.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta video ad in an ad set from a video id already in the ad account or a public video URL that Meta fetches (thumbnail taken from the video when not given). Created paused.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Turn an existing Instagram post (source_instagram_media_id) or Facebook Page post (object_story_id) into an ad in an ad set; pick_best chooses the most engaging recent Instagram post. Applied directly when the user asks; created paused.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Add a product to a Meta catalog (POST /{catalog_id}/products; needs retailer_id, name, url, image_url, price, currency, availability) or update an existing one (POST /{product_id}). Applied directly when the user asks; applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta catalog sales campaign (objective OUTCOME_SALES with promoted_object.product_catalog_id) and an ad set promoting a product set (promoted_object.product_set_id, purchase optimisation) as a paused draft. Writes a ledger draft and sends it to Meta directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

PERMANENTLY delete a Meta campaign (reports stay readable in Meta). Only call it when the user explicitly asked for it; it is applied at once and cannot be undone; pause instead if unsure.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

PERMANENTLY delete a Meta ad set. Only call it when the user explicitly asked for it; it is applied at once and cannot be undone.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

PERMANENTLY delete a Meta ad. Only call it when the user explicitly asked for it; it is applied at once and cannot be undone.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

PERMANENTLY delete a Meta custom or lookalike audience (duplicates, mistakes, privacy requests). Only call it when the user explicitly asked for it; it is applied at once and cannot be undone.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a paused ad set in an existing Meta campaign with optimisation goal, budget, bid, schedule, promoted object and full targeting (locations, demographics, detailed targeting, audiences, placements). Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Duplicate a Meta campaign, ad set or ad (Ads Manager 'Duplicate'), optionally with its children and into another parent; the copy is always paused. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a single-image Meta link ad (creative + ad) in an ad set from an image URL, uploaded image hash or base64 image, with primary text, headline and button. Created paused.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a dynamic product ad that fills itself from a catalog product set ({{product.name}}, {{product.price}}) in a catalog sales ad set. Created paused.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Pause, resume, archive or rename one Meta ad. Applied directly when the user asks; the result shows before → after.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Replace a link ad's creative (image, text, link, button) without deleting the ad: a new creative is built from the current one plus your changes and swapped in, so the ad keeps its id and history. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta split test that runs two existing campaigns 50/50 on non-overlapping audiences for a period and reports a fair winner. Needs a Business Manager. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a custom conversion on a Meta pixel from a URL rule and/or an event (e.g. URL contains /thank-you). Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Rename a Meta custom conversion or change its description / default value. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a Meta retargeting audience from engagement with a Facebook Page, an Instagram business profile or a lead form (e.g. opened but didn't submit). Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create an instant (lead) form on a Facebook Page with standard and custom questions, intro, privacy policy and thank-you screen; returns the form id for a lead ad. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Upload an image to the Meta ad account image library and get its image_hash for reuse across ads. External URLs are fetched only from the public internet. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Add a video to the Meta ad account from a public URL (Meta fetches it) and get its video_id for create_meta_video_ad. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Send a server-side conversion event to Meta (Conversions API), e.g. an offline or CRM sale. Email, phone and external id are SHA-256 hashed before they are stored or sent. Use test_event_code to check in Events Manager first. Applied directly when the user asks.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.

Create a new Meta ad account under the user's Business Manager (for the user who has no ad account after OAuth). Needs a Business Manager (returns an honest note if none; lists them when there are several). Only call it when the user explicitly asked for it; the account is created at once and the connection is linked to it. Currency and time zone are permanent; a payment method must still be added in Business Manager.

Write tool: the call first produces a preview; the change reaches the platform only after you approve it.