meta_ads_* tool family wraps the same Meta Marketing API surface as Meta’s official Ads MCP, with additions for multi-tenant scoping, attribution policy storage, and currency enrichment. This page lists the differences a developer or LLM author needs to know when switching between the two.
Tool-name mapping
Most Meta Ads MCP tools have an Outfox counterpart with themeta_ads_ prefix instead of ads_ (the exceptions are listed in Tools Outfox does not expose below). One Meta tool, ads_get_ad_entities, is split into two Outfox tools: meta_ads_get_insights (performance metrics over a date range) and meta_ads_get_metadata (entity attributes — name, objective, budget, schedule). The base 52 response fields otherwise match Meta’s specification; Outfox’s meta_ads_get_insights adds 18 fields beyond that base, and meta_ads_get_ad_accounts appends the account’s reporting currency — see Field surface for the full catalog. Parameter-level differences (most notably the required ad_account_id on entity writes) are documented in the Behavioral differences section below.
Discovery & account
| Meta official | Outfox |
|---|---|
ads_get_ad_accounts | meta_ads_get_ad_accounts |
ads_get_pages_for_business | meta_ads_get_pages_for_business |
ads_get_user_pages | meta_ads_get_user_pages |
ads_get_ad_account_pages | meta_ads_get_ad_account_pages |
ads_get_field_context | meta_ads_get_field_context |
Entity reads & writes
| Meta official | Outfox |
|---|---|
ads_get_ad_entities (metrics) | meta_ads_get_insights |
ads_get_ad_entities (entity attributes) | meta_ads_get_metadata |
ads_create_campaign | meta_ads_create_campaign |
ads_create_ad_set | meta_ads_create_ad_set |
ads_create_ad | meta_ads_create_ad |
ads_update_entity | meta_ads_update_entity |
ads_activate_entity | meta_ads_activate_entity |
ads_get_errors | meta_ads_get_errors |
Creative & assets
| Meta official | Outfox |
|---|---|
ads_get_ad_images | meta_ads_get_ad_images |
ads_get_ad_videos | meta_ads_get_ad_videos |
ads_get_creatives | meta_ads_get_creatives |
ads_get_creative_ads | meta_ads_get_creative_ads |
ads_create_creative | meta_ads_create_creative (Outfox also accepts object_story_id to promote an existing post — see meta_ads_create_creative supports promoting existing posts) |
Custom audiences
| Meta official | Outfox |
|---|---|
ads_get_ad_account_custom_audiences | meta_ads_get_ad_account_custom_audiences |
ads_get_custom_audience | meta_ads_get_custom_audience |
ads_create_custom_audience | deferred — see Tools Outfox does not expose |
ads_update_custom_audience_users | deferred — see Tools Outfox does not expose |
Catalog & commerce
| Meta official | Outfox |
|---|---|
ads_catalog_create | meta_ads_catalog_create |
ads_catalog_get_catalogs | meta_ads_catalog_get_catalogs |
ads_catalog_get_details | meta_ads_catalog_get_details |
ads_catalog_get_diagnostics | meta_ads_catalog_get_diagnostics |
ads_catalog_get_feed_rules | meta_ads_catalog_get_feed_rules |
ads_catalog_get_product_details | meta_ads_catalog_get_product_details |
ads_catalog_get_product_feed_details | meta_ads_catalog_get_product_feed_details |
ads_catalog_get_product_set_products | meta_ads_catalog_get_product_set_products |
ads_catalog_get_product_sets | meta_ads_catalog_get_product_sets |
ads_catalog_get_products | meta_ads_catalog_get_products |
ads_catalog_search_product | meta_ads_catalog_search_product |
ads_catalog_create_product_set | meta_ads_catalog_create_product_set |
Datasets & pixels
| Meta official | Outfox |
|---|---|
ads_get_datasets | meta_ads_get_datasets |
ads_get_dataset_details | meta_ads_get_dataset_details |
ads_get_dataset_quality | meta_ads_get_dataset_quality |
ads_get_dataset_stats | meta_ads_get_dataset_stats |
Help & insights
| Meta official | Outfox |
|---|---|
ads_get_help_article | meta_ads_get_help_article |
ads_insights_auction_ranking_benchmarks | meta_ads_insights_auction_ranking_benchmarks |
ads_insights_performance_trend | meta_ads_insights_performance_trend |
Tools Outfox does not expose
Six tools from Meta’s surface are intentionally not registered. Four depend on proprietary ML pipelines or aggregations that aren’t part of the public Marketing API. Two are customer-list write tools deferred until the PII redactor + privacy/compliance review ship.| Meta tool | Why we skip it |
|---|---|
ads_get_opportunity_score | Internal recommendation score; no public endpoint |
ads_insights_advertiser_context | Internal advertiser-context model |
ads_insights_anomaly_signal | Internal anomaly-detection model |
ads_insights_industry_benchmark | Internal industry-benchmark aggregation |
ads_create_custom_audience | Deferred — paired with the user-upload tool below; ships together once the PII redactor lands |
ads_update_custom_audience_users | Deferred — uploads PII rows; needs the redactor for data / schema / debug_identifier and a privacy/compliance review before going live |
tools/list from https://app.outfox.ai/api/mcp, that’s a regression — please file an issue. The two deferred custom-audience tools will be added in a follow-up release; their counterpart read tools (meta_ads_get_ad_account_custom_audiences, meta_ads_get_custom_audience) are already available.
Outfox-only Meta tools
The following tools fill gaps that exist in Meta’s official MCP. They use the same authentication and ad-account scoping as the parity tools.meta_ads_audit_attribution
Scans an ad account’s recent ad sets and reports whether any use non-standard attribution windows. By default persists a fresh audit result to the Outfox adAccounts row (pass persist: false to probe without writing). Returns the account’s current attribution mode, the pinned window if set, and per-ad-set attribution samples with a human-readable notice. Meta’s official MCP has no equivalent; the LLM must track attribution context manually.
meta_ads_set_attribution_mode
Sets the ad account’s attribution mode (default or custom) and optionally pins a preferred window. In default mode reporting tools issue a plain Graph call and each row reflects its own ad set’s attribution_spec. In custom mode a single window is injected per call from the priority stack (explicit override → preferred window → slice probe). Useful when a user wants consistent cross-ad-set attribution for reporting.
meta_ads_list_custom_conversions
Lists the custom conversions configured on an ad account. Meta’s MCP doesn’t expose this directly; the only path in their surface is to query actions:custom_conversion_id on insights, which requires knowing the ID up-front.
Named briefs
Fivemeta_brief_* tools package a recurring analyst task — pacing risk, budget allocation, pre-flight QA, reporting discrepancy, and a weekly summary — into a single call that orchestrates the meta_ads_* tools and returns a rendered summary. Meta’s official MCP has no equivalent. See Meta analytics tools for what each one answers.
Behavioral differences
Authentication
| Meta official | Outfox |
|---|---|
| Direct OAuth handshake against the user’s Meta account | Clerk-issued session ↦ resolved organization ↦ Meta access token loaded from the Clerk OAuth provider |
| Session is tied to a single Facebook user | Session is tied to a Clerk principal that may belong to multiple Outfox organizations |
| Tokens cached at the MCP layer | Per-request token cache that evicts on rejection so a transient Clerk failure on one tool call doesn’t poison the rest of the conversation |
Multi-tenant ad-account scoping
Every read and write is gated against the brand-organization membership of the authenticated user. If a Meta token grants access toact_X but act_X belongs to a different Outfox organization’s brand, the Outfox layer returns a not-found-or-not-connected error rather than forwarding the Graph response.
Meta’s official MCP has no equivalent: any token that can call the Marketing API can read whatever it can reach via Meta. The Outfox layer is what makes the platform safe to share between organizations on a single Clerk workspace.
Attribution policy stored server-side
Meta’s MCP requires the LLM to specify the attribution window on every insights call. Outfox stores a per-account attribution policy on theadAccounts row and applies it automatically in meta_ads_get_insights calls. Use meta_ads_audit_attribution (persists by default; pass persist: false to probe without writing) or meta_ads_set_attribution_mode to configure it.
Currency enrichment
meta_ads_get_ad_accounts returns the same shape as Meta’s official tool plus the ad account’s reporting currency, pulled from the Outfox adAccounts row. Foxley uses this to label monetary axes correctly when the LLM hands the data to render_ui.
Error vocabulary
Outfox normalizes Meta Graph errors to a single prefix:meta_ads_* tool. The catalog tool’s nested sub-step catch (for createFeed / batchUpsertProducts failures during meta_ads_catalog_create) reproduces the same prefix so the surface error vocabulary stays consistent across the Outfox surface area. Meta’s MCP returns the raw Marketing API error payload.
meta_ads_update_entity and meta_ads_activate_entity require ad_account_id
Meta’s official MCP allows the entity-write tools to accept entity_id alone and infer the parent account. Outfox makes ad_account_id a required parameter so the per-account scope check always runs on writes. Calls that omit it are rejected at the schema boundary.
meta_ads_create_creative supports promoting existing posts
Meta’s hosted ads_create_creative only accepts the inline-spec path: pass image_hash + link_url and a fresh unpublished page post gets created under the hood. Outfox accepts that plus a second path — pass object_story_id (pageID_postID) to wrap an existing post instead. The creative inherits the post’s accumulated likes, comments, and shares, so paid amplification doesn’t reset the social proof on an organic winner.
| Field | Inline-spec path | Existing-post path |
|---|---|---|
image_hash | required | omit |
link_url | required | omit (the wrapped post carries its own destination) |
object_story_id | omit | required (pageID_postID form) |
message, headline, description, call_to_action_type | optional | omit (inherited from the wrapped post) |
image_hash / object_story_id must be provided.
Outfox-native tools with no Meta equivalent
search_inspiration is global by design
The Outfox search_inspiration tool reads from a shared, cross-tenant catalog of public ad creative. Every authenticated principal sees the same library; there is no per-organization scoping. This is a documented product decision, not a missing gate. (Worth flagging here because the multi-tenant scoping section above might give the impression every Outfox tool is org-gated — search_inspiration is the deliberate exception.)
Field surface
Outfox exposes 70 curated fields onmeta_ads_get_insights — the 52 base fields Meta’s official MCP exposes via ads_get_ad_entities, plus 18 extensions covering additional cost, conversion, and creative-engagement metrics for cross-platform reporting. Each field carries the same metadata Meta publishes (levels, is_filterable, is_sortable, filter_operators, filter_value_options, etc.) and you can introspect the catalog at runtime with meta_ads_get_field_context.
The colon-syntax field flattening (actions:like, actions:link_click, cost_per_action_type:offsite_conversion.fb_pixel_purchase) works identically on both surfaces.
When to use which surface
- Use Meta’s official MCP when you need a single-tenant Facebook account integration, are working in a context that already has a Meta OAuth session, or when one of the Outfox-skipped tier-3 tools is critical to your workflow.
- Use Outfox’s
meta_ads_*surface when you want multi-organization scoping, server-side attribution policy storage, currency-aware insights, or when you’re already inside Outfox via Foxley or the MCP suite.