tool_update_campaign
Update an existing campaign.
Args:
campaign_id: Meta Ads campaign ID
name: New campaign name
status: New status (ACTIVE, PAUSED)
daily_budget: New daily budget in cents
lifetime_budget: New lifetime budget in cents
bid_strategy: New bid strategy
spend_cap: New spending limit in cents
tool_duplicate_campaign
Duplicate a campaign with all its settings.
Args:
campaign_id: Meta Ads campaign ID to duplicate
name_suffix: Suffix for the new campaign name
new_status: Status for the new campaign (ACTIVE or PAUSED)
new_daily_budget: Override daily budget in cents
tool_get_adsets
Get ad sets for a Meta Ads account, optionally filtered by campaign.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
limit: Maximum number of ad sets to return (default: 10)
campaign_id: Optional campaign ID to filter by
tool_get_adset_details
Get detailed information about a specific ad set.
Args:
adset_id: Meta Ads ad set ID
tool_create_adset
Create a new ad set in a Meta Ads account.
Budget is controlled at the campaign level (CBO). Any daily_budget or
lifetime_budget passed here will be ignored to avoid Meta API errors.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
campaign_id: Campaign ID this ad set belongs to
name: Ad set name
optimization_goal: e.g. LINK_CLICKS, REACH, CONVERSIONS, VALUE
billing_event: e.g. IMPRESSIONS, LINK_CLICKS
status: Initial status (default: PAUSED)
daily_budget: IGNORED — budget is set on the campaign, not the ad set
lifetime_budget: IGNORED — budget is set on the campaign, not the ad set
targeting: JSON string of targeting specs
bid_amount: Bid amount in CENTS
bid_strategy: LOWEST_COST_WITHOUT_CAP, COST_CAP, etc.
bid_constraints: JSON string e.g. {"roas_average_floor": 20000}
start_time: ISO 8601 format
end_time: ISO 8601 format
destination_type: WEBSITE, WHATSAPP, MESSENGER, etc.
is_dynamic_creative: "true" or "false"
promoted_object: JSON string for APP_INSTALLS
tool_update_adset
Update an ad set with new settings.
Args:
adset_id: Meta Ads ad set ID
name: New name
status: ACTIVE, PAUSED
daily_budget: In cents
lifetime_budget: In cents
bid_amount: In cents
bid_strategy: LOWEST_COST_WITHOUT_CAP, COST_CAP, etc.
bid_constraints: JSON string
targeting: JSON string of targeting specs
optimization_goal: LINK_CLICKS, CONVERSIONS, etc.
frequency_control_specs: JSON array
is_dynamic_creative: "true" or "false"
tool_duplicate_adset
Duplicate an ad set with its settings.
Args:
adset_id: Ad set ID to duplicate
target_campaign_id: Optional campaign to place the copy in
name_suffix: Suffix for the new name
new_status: ACTIVE or PAUSED
new_daily_budget: Override daily budget in cents
new_targeting: Override targeting as JSON string
tool_get_ads
Get ads for a Meta Ads account with optional filtering.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
limit: Maximum number of ads to return (default: 10)
campaign_id: Optional campaign ID to filter by
adset_id: Optional ad set ID to filter by
tool_get_ad_details
Get detailed information about a specific ad.
Args:
ad_id: Meta Ads ad ID
tool_create_ad
Create a new ad with an existing creative.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
name: Ad name
adset_id: Ad set ID where this ad will be placed
creative_id: ID of an existing creative to use
status: Initial status (default: PAUSED)
bid_amount: Optional bid amount in cents
tracking_specs: Optional JSON array of tracking specs
tool_update_ad
Update an ad with new settings.
Args:
ad_id: Meta Ads ad ID
status: ACTIVE, PAUSED
bid_amount: In cents
creative_id: New creative to associate
tracking_specs: JSON array of tracking specs
tool_duplicate_ad
Duplicate an ad, optionally changing the destination URL.
When link_url is provided, the creative is also duplicated with the new
URL so the new ad points to a different destination.
Args:
ad_id: Ad ID to duplicate
target_adset_id: Optional ad set to place the copy in
name_suffix: Suffix for the new name
new_status: ACTIVE or PAUSED
link_url: Optional new destination URL (duplicates creative with new URL)
tool_get_ad_creatives
Get creative details for a specific ad. Requires an ad_id.
Args:
ad_id: Meta Ads ad ID
tool_get_creative_details
Get detailed information about a specific ad creative by its ID.
Args:
creative_id: Meta Ads creative ID
tool_create_ad_creative
Create a new ad creative using an uploaded image hash or video ID.
Supports simple, dynamic creative, and FLEX (Advantage+) modes.
Video thumbnail is auto-fetched from Meta if not provided.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
page_id: Facebook Page ID
name: Creative name
image_hash: Single image hash
image_hashes: JSON array of image hashes for FLEX
video_id: Video ID for video creatives
thumbnail_url: Thumbnail URL for video creatives (auto-fetched if omitted)
link_url: Destination URL
message: Single primary text
messages: JSON array of text variants
headline: Single headline
headlines: JSON array of headline variants
description: Single description
descriptions: JSON array of description variants
call_to_action_type: LEARN_MORE, SHOP_NOW, SIGN_UP, etc.
lead_gen_form_id: Lead gen form ID
instagram_user_id: Instagram user ID (the 17841... format from your Page's linked Instagram account)
optimization_type: DEGREES_OF_FREEDOM for Advantage+
ad_formats: JSON array of ad formats
url_tags: UTM tracking params as query string (e.g. "utm_source=meta&utm_medium=paid_social&utm_campaign=my_campaign"). Supports Meta macros like {{campaign.name}}, {{adset.name}}, {{ad.name}}, {{ad.id}}.
tool_update_ad_creative
Update an existing ad creative's name or optimization settings.
IMPORTANT: Meta's API does NOT allow updating content (text, images, video,
URLs, CTA) on existing creatives. Only the name and optimization_type can
be changed. To modify content, use tool_duplicate_creative instead — it
creates a new creative from the original with your overrides applied.
Args:
creative_id: Meta Ads creative ID
name: New creative name
optimization_type: DEGREES_OF_FREEDOM for Advantage+
tool_duplicate_creative
Duplicate a creative, optionally overriding content fields.
Args:
creative_id: Creative ID to duplicate
name_suffix: Suffix for the new name
new_primary_text: Override primary text
new_headline: Override headline
new_description: Override description
new_cta_type: Override CTA type
new_destination_url: Override destination URL
tool_create_carousel_ad_creative
Create a carousel ad creative with 2-10 cards.
Args:
account_id: Meta Ads account ID
page_id: Facebook Page ID
child_attachments: JSON array of cards, each with link, image_hash/video_id, name, description
message: Primary text above the carousel
link: Default destination URL
call_to_action_type: SHOP_NOW, LEARN_MORE, etc.
instagram_user_id: Instagram user ID (the 17841... format from your Page's linked Instagram account)
tool_get_insights
Get performance insights for a campaign, ad set, ad, or account.
Args:
object_id: ID of the campaign, ad set, ad, or account
time_range: Preset (e.g. "last_7d", "last_30d") or JSON {"since":"2025-01-01","until":"2025-01-31"}
time_breakdown: Optional: "day", "week", or "month"
breakdown: Optional: age, gender, country, device_platform, etc.
level: Aggregation level: ad, adset, campaign, account
limit: Max results per page (default: 25)
after: Pagination cursor for next page
tool_bulk_get_insights
Fetch performance insights for multiple ad accounts in parallel.
Args:
level: Aggregation level: account, campaign, adset, ad
account_ids: JSON array of account IDs (empty = all accounts)
time_range: Preset string or JSON {"since":"...", "until":"..."}
time_breakdown: Optional: day, week, month
breakdown: Optional: age, gender, country, device_platform
fields: JSON array of metrics (default: spend, impressions, clicks, etc.)
limit: Max accounts to return (default: 20)
offset: Accounts to skip for pagination
compact: Strip derived metrics for smaller responses
campaign_name_contains: JSON array of name filter strings
campaign_ids: JSON array of campaign IDs to filter
adset_ids: JSON array of ad set IDs to filter
ad_name_contains: JSON array of ad name filter strings
tool_search_interests
Search for interest targeting options by keyword.
Args:
query: Search term (e.g. "baseball", "cooking", "travel")
limit: Max results (default: 25)
tool_search_geo_locations
Search for geographic targeting locations.
Args:
query: Search term (e.g. "New York", "California", "Japan")
location_types: JSON array of types: country, region, city, zip, geo_market
limit: Max results (default: 25)
tool_search_demographics
Get demographic targeting options.
Args:
demographic_class: demographics, life_events, industries, income,
family_statuses, user_device, user_os
limit: Max results (default: 50)
tool_search_behaviors
Get all available behavior targeting options.
Args:
limit: Max results (default: 50)
tool_get_interest_suggestions
Get interest suggestions based on existing interests.
Args:
interest_list: JSON array of interest names (e.g. ["Basketball", "Soccer"])
limit: Max suggestions (default: 25)
tool_estimate_audience_size
Estimate audience size for targeting specifications.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
targeting: JSON string of targeting specs
optimization_goal: REACH, LINK_CLICKS, IMPRESSIONS, CONVERSIONS
tool_upload_ad_image
Upload an image to use in Meta Ads creatives. Returns an image_hash.
Accepts EITHER:
• image_url — any publicly-accessible URL (e.g. from an image-generation
API like DALL-E, Flux, a CDN link, or an AdWeave creative URL). The
image is downloaded and uploaded to Meta.
• file_path — absolute path to a local image file on disk (e.g.
"/Users/me/images/ad.jpg"). The file is read directly, staged to
Supabase Storage, and uploaded to Meta.
You only need ONE tool call. Pass whichever format you have.
Args:
account_id: Meta Ads account ID (e.g. "act_123456")
image_url: URL to fetch the image from
file_path: Absolute path to a local image file
name: Optional filename
tool_upload_ad_video
Upload a video to a Meta Ads account.
Accepts EITHER:
• video_url — publicly accessible URL. Meta fetches it directly.
• file_path — absolute path to a local video file on disk. The file
is staged to Supabase Storage first, then uploaded to Meta.
Args:
account_id: Meta Ads account ID
video_url: Publicly accessible URL to the video file
file_path: Absolute path to a local video file
name: Optional filename
title: Optional video title
description: Optional video description
tool_get_ad_image
Get the image URL for a specific ad.
Args:
ad_id: Meta Ads ad ID
tool_bulk_upload_ad_images
Upload multiple images to Meta Ads accounts.
Args:
items: JSON array, each: {"account_id": "act_XXX", "image_url": "https://...", "name": "optional"}
OR: {"account_id": "act_XXX", "file_path": "/path/to/image.jpg", "name": "optional"}
tool_bulk_upload_ad_videos
Upload multiple videos to Meta Ads accounts.
Args:
items: JSON array, each: {"account_id": "act_XXX", "video_url": "https://...", "title": "optional"}
OR: {"account_id": "act_XXX", "file_path": "/path/to/video.mp4", "title": "optional"}
tool_bulk_update_campaigns
Update multiple campaigns with individual or uniform parameters.
Mode 1 (explicit): Provide campaign_updates JSON array.
Mode 2 (filter): Provide filter_criteria + updates JSON objects.
Args:
account_id: Meta Ads account ID
campaign_updates: JSON array of per-campaign update specs
filter_criteria: JSON object with status, name_contains, objective, campaign_ids
updates: JSON object with uniform updates to apply
dry_run: If true, preview without making changes
limit: Max campaigns to update (default: 20)
tool_bulk_update_adsets
Update multiple ad sets with individual or uniform parameters.
Args:
account_id: Meta Ads account ID
adset_updates: JSON array of per-adset update specs
filter_criteria: JSON object with status, campaign_id, name_contains, adset_ids
updates: JSON object with uniform updates to apply
dry_run: If true, preview without making changes
limit: Max ad sets to update (default: 20)
tool_bulk_update_ads
Update multiple ads with individual or uniform parameters.
Args:
account_id: Meta Ads account ID
ad_updates: JSON array of per-ad update specs
filter_criteria: JSON object with status, campaign_id, adset_id, name_contains, ad_ids
updates: JSON object with uniform updates to apply
dry_run: If true, preview without making changes
limit: Max ads to update (default: 20)
tool_search
Search through Meta Ads data and return matching records.
Args:
query: Search query string
tool_fetch
Fetch complete record data by ID.
Args:
record_id: Format "type:id" (e.g. "account:act_123", "campaign:12345")
tool_search_pages_by_name
Search for pages by name within an account.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
search_term: Optional name filter
tool_get_instagram_accounts
Get Instagram business accounts associated with an ad account.
Args:
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
tool_create_budget_schedule
Create a budget schedule for a campaign.
Args:
campaign_id: Meta Ads campaign ID
budget_value: Amount of budget increase
budget_value_type: ABSOLUTE or MULTIPLIER
time_start: Unix timestamp for start
time_end: Unix timestamp for end
tool_create_email_report
Create an email report for ad performance.
Args:
account_id: Meta Ads account ID
cadence: once, daily, or weekly
emails: JSON array of recipient emails
time_range: Time period for the report
tool_get_partnership_accounts
List all creators with partnership ad access for a brand IG account.
Returns approved, pending, and revoked partnerships with creator usernames.
Args:
brand_ig_id: The brand's Instagram Business Account ID
tool_get_creator_media
Fetch posts/reels from a creator's Instagram account.
Requires approved partnership ad access to the creator's account.
Args:
creator_ig_id: The creator's Instagram user ID
limit: Max number of posts to return (default 25)
media_type: Filter by type: IMAGE, VIDEO, CAROUSEL_ALBUM, or empty for all
tool_get_creator_media_insights
Get engagement stats for a specific creator post.
Returns impressions, reach, likes, comments, shares, saves, plays.
Args:
media_id: The Instagram media/post ID
tool_create_ad_from_partnership_code
Create a partnership ad from a creator's ad code string (e.g. adcode-Q9jTBB...).
Use this when a creator has shared an ad code. The code encodes the
creator's content and permissions, so no creator IG ID or media ID is needed.
Args:
account_id: Ad account ID
name: Ad name (e.g. "Whitelist Creative 1")
adset_id: Ad set ID to place the ad in
partnership_ad_code: The ad code from the creator (starts with "adcode-")
page_id: Brand's Facebook Page ID
status: PAUSED (default) or ACTIVE