Reference
Meta Ads tools
Full campaign management for Facebook and Instagram advertising through 14 MCP tools, analyze, create, optimize, and duplicate ads.
On this page
Before you begin
Connect the relevant Meta Ads account through Accounts, then connect your AI assistant. Confirm the target account and date range before querying data or making changes.
This is the generated catalog. The tools shown in your AI assistant depend on your connected accounts, active workspace, role, write permissions, enabled features and the client's supported tool surface. A listed tool is not a promise that it is enabled in every workspace. See accounts, workspace access and troubleshooting.
Available tools
14 tools · API v24.0.
| Tool | Access | Purpose |
|---|---|---|
meta_list_ad_accounts | Read | List all ad accounts you have access to |
meta_query | Read | Query campaigns, adsets, or ads with flexible filtering |
meta_update | Write | Pause/resume campaigns, update budgets, rename entities |
meta_get_insights | Read | Get performance metrics at account, campaign, adset, or ad level |
meta_get_creatives | Read | Get creative details, text content, and performance data at single/campaign/account scope |
meta_create_ad | Write | Create new ads with image upload, copy, and CTA in existing ad sets |
meta_duplicate | Write | Duplicate ads with creative overrides for A/B testing |
meta_create | Write | Create campaigns and ad sets with targeting, budgets, and objectives |
meta_upload_image | Write | Upload an image via direct HTTPS URL, base64 or an available private Meta-image stage; returns image_hash for ad creation |
meta_upload_video | Write | Upload videos from a public URL to your ad account's media library |
meta_get_video_status | Read | Check processing status of uploaded videos before using them in ads |
meta_ad_execute | Write | Execute the plan the customer confirmed by giving this token back. |
meta_ad_plan | Read | Build one confirmable plan for a single paused Meta video ad. |
meta_wire_pages | Write | Discover + wire the Facebook Page and Instagram account onto a client's Meta-linked ad accounts, so meta_create_ad resolves them automatically. |
Write tools can change account settings, campaigns or workspace content. Confirm the target and proposed changes before running them.
Private local uploads support Meta, TikTok, LinkedIn and Google Ads. Your workspace needs upload access to the destination, and your AI client needs file access and HTTP upload. JPEG/PNG images up to 20 MB (20,000,000 bytes) and MP4 videos up to 500 MB (500,000,000 bytes) are supported by the upload flow; destination-specific restrictions still apply. Existing account-library IDs remain available. Read the upload guide before uploading.
Example questions
Show me my Meta ad accounts
What's the performance of my campaigns this month?
Compare my top 3 campaigns by ROAS
Which ad sets have the highest cost per conversion?
Show me the trend of my ad spend over the last 30 days
API capabilities
Available fields and combinations depend on the resource, account and campaign type. Adapt the examples to your selected account.
Metrics
| Category | Fields |
|---|---|
| Traffic | impressions, reach, frequency, clicks, unique_clicks, cpc, cpm, ctr, cpp, spend |
| Engagement | actions, action_values, cost_per_action_type, unique_actions, cost_per_unique_action_type, inline_link_clicks, inline_link_click_ctr, outbound_clicks, cost_per_outbound_click, social_spend |
| Video | video_play_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_avg_time_watched_actions |
| ROAS & Conversion | purchase_roas, website_purchase_roas, quality_ranking, engagement_rate_ranking, conversion_rate_ranking |
Dimensions
| Category | Fields |
|---|---|
| Demographics | age, gender, country, region, dma |
| Placement | publisher_platform, platform_position, device_platform, impression_device |
| Time | hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone |
| Product (Dynamic Ads) | product_id, dynamic_ad_id |
Query examples
Campaign Performance with Actions Breakdown
Get campaign metrics with detailed conversion actions breakdown
Tool: meta_get_insights.
{
"level": "campaign",
"fields": [
"campaign_name",
"impressions",
"clicks",
"spend",
"actions",
"action_values",
"purchase_roas"
],
"date_preset": "last_30d",
"filtering": [
{"field": "campaign.status", "operator": "IN", "value": ["ACTIVE"]}
]
}
Ad Set Performance by Age & Gender
Analyze performance across demographic segments
Tool: meta_get_insights.
{
"level": "adset",
"fields": [
"adset_name",
"impressions",
"clicks",
"spend",
"actions",
"cpc",
"ctr"
],
"breakdowns": ["age", "gender"],
"date_preset": "last_14d"
}
Video Ad Engagement Analysis
Track video view completion rates across your ads
Tool: meta_get_insights.
{
"level": "ad",
"fields": [
"ad_name",
"impressions",
"video_play_actions",
"video_p25_watched_actions",
"video_p50_watched_actions",
"video_p75_watched_actions",
"video_p100_watched_actions"
],
"date_preset": "last_7d"
}
Technical reference
API endpoint: graph.facebook.com/v24.0. Status: stable.
Major versions are stable for approximately 2 years
June 10, 2025 (minor): use_unified_attribution_setting and action_report_time parameters will be ignored. API responses will automatically follow Meta Ads Manager settings.
January 12, 2026 (breaking): 7d_view and 28d_view attribution windows will be removed from the API. Use 1d_view or click-based attribution windows (1d_click, 7d_click, 28d_click) instead.
Limitations and notes
- No 'conversions' field - use 'actions' array and filter by action_type
- Historical breakdown data limited to 13 months (effective June 2025)
- Frequency breakdowns limited to 6 months (effective January 2026)
- Rate limits apply for high-volume queries - use async jobs for large datasets
- Quality rankings (quality_ranking, engagement_rate_ranking, conversion_rate_ranking) require sufficient impression volume
