Skip to main content
Glama

Read Meta ads data

meta_ads_read
Read-onlyIdempotent

Reads Meta ad accounts. action "list_tools" lists every operation of every router with its field names, flags and the router that executes it (get_tool_schema returns the input schema); it does not call Meta and is free. action "execute" runs one read: {"action":"execute","tool_name":"list_campaigns","arguments":{}}. Reads:

  • account_summary: The connected ad account: name, currency, status, lifetime spend.

  • list_pages: Facebook Pages that ads can run under.

  • list_campaigns: Campaigns in the ad account: configured and effective status, objective, budget. Deleted campaigns are not shown, archived only on request.

  • campaign_details: One campaign in full: settings, budget and its ad sets with a targeting summary, optionally its ads.

  • list_adsets: Ad sets across the whole ad account or one campaign (except deleted and archived by default): configured and effective status, budgets. Join with campaigns on campaign_id.

  • list_ads: Ads in the ad account, or in one campaign or ad set: status, effective status, creative.

  • ad_statuses: Statuses for a batch of ads in one request, so you do not have to guess what is already off.

  • list_images: Images in the ad account library, with the hashes that create_ad_creative takes.

  • list_videos: Videos in the ad account library, with the ids that create_video_creative takes.

  • list_creatives: Creatives already built in this ad account: what each one says, where it links and which picture it uses.

  • preview_ad: See the ad as it looks in the feed, drawn by Meta. Answers with a link for a person; no impressions and no spend.

  • upload_link: A page where a person adds creatives and sees the ones already in the library. Nothing is sent to Meta by this call.

  • read_landing_page: What a landing page says — headline, sections, numbers, prices, buttons and its language — to write ad texts from. Nothing is sent to Meta.

  • list_instagram_accounts: Instagram accounts this ad account can run ads from.

  • list_custom_audiences: Custom and lookalike audiences that Meta lists for this ad account, with size and whether they can be used.

  • search_targeting: Search Meta targeting options by words: interests, behaviors, demographics, life events, employers, job titles, schools, majors, locations and languages.

  • list_pixels: Meta pixels (datasets) this ad account can use, and when each last fired.

  • list_custom_conversions: Custom conversions of the ad account: event type, pixel and whether they still fire.

  • pixel_stats: Event counts of one pixel, by event and by hour, for up to the last 28 days.

  • ad_issues: Ads Meta rejected or holds with a delivery issue in running campaigns, with Meta's reasons, and ad sets that are Learning limited.

  • dashboard_data: The numbers behind performance_dashboard: spend, results, cost per result, link CTR and CPM against the previous period, by day and by campaign.

  • account_playbook: A skill for the assistant made from this ad account: what it sells, how campaigns are named, which result counts, targets, house rules, pitfalls and questions with real names.

  • analyze_wasted_spend: Classify the campaigns that spent in a window: wasted, below target, lead campaigns, learning or too little data.

  • analyze_audiences: Which age and gender groups the money goes to, what each of them brings, and where a result costs more than it does across the ad account.

  • analyze_placements: Which placements the money goes to — Feed, Stories, Reels, Audience Network and the rest — what each brings and where a result costs more than across the ad account.

  • detect_creative_fatigue: Score the active ads for creative fatigue: frequency, link CTR decline and how long they have been running.

  • ad_copy_brief: Everything needed to write new Meta ad texts for a campaign: its primary texts and headlines with spend, link CTR, results and cost per result, which ones beat the other texts beyond chance, the money they brought when payments are sent in, the landing pages and Meta's recommended text lengths, overall and by placement. The assistant writes the texts.

  • explain_anomaly: Explain why a metric changed — cost per result (CPA, cost per lead or purchase), ROAS, CTR, CPC, CPM, conversions — against the 30, 60 and 90 day baselines: which campaigns and ad sets moved it, at which funnel step, whether it is beyond chance, and what was edited in the ad account in those days.

  • optimize_budget: Recommend how to split a monthly budget pool across campaigns or ad sets. It changes nothing.

  • diagnose_funnel: Walk the funnel in order — tracking, revenue, traffic, conversion, spend — and stop at the first broken step.

  • browse_targeting: Browse a whole Meta targeting category: interests, behaviors, demographics, life events, industries, income or family statuses.

  • select_campaign_type: The order of tools that builds a campaign of a given type, and what it needs before it can be built.

  • copy_status: Check an asynchronous campaign copy: whether Meta finished it and what it produced.

  • app_performance: App promotion campaigns of this ad account: spend, installs and cost per install by campaign, ad set or ad, with the in-app events Meta reports for them.

  • list_promotable_apps: Mobile apps this ad account may advertise, with their store links and the events they report.

  • list_monitors: Monitors of this ad account: their conditions, status, last check and how often they triggered.

  • get_monitor_history: When a monitor triggered, on which campaigns, ad sets or ads, with what numbers, and whether an email went out.

  • test_monitor: Dry-run a monitor now: which campaigns, ad sets or ads would trigger and which are skipped, without recording or emailing.

  • list_scheduled_tasks: Scheduled briefs of this account and monitors of this ad account, with status, schedule and last run.

  • list_signals: What the watchdog found in this ad account and has not seen resolved.

  • run_watch_now: Run the watchdog over this ad account right now instead of waiting for its next pass.

  • list_pending_actions: Changes the watchdog and monitors prepared for approval: pauses and budget changes, with what each would do.

  • get_signal_briefing: One finding of the watchdog or a monitor: what was seen, since when, and the changes prepared for it.

  • get_opportunity_score: Meta's opportunity score for this ad account (0–100) and the recommendations Meta gives to raise it.

  • audience_details: One custom or lookalike audience in full: what it is built from, its size, its status and whether it can be used.

  • audience_adsets: Which ad sets use a custom or lookalike audience, with how many of their ads do.

  • pixel_details: One pixel (dataset) in full: its settings, when it last fired, and the checks Meta runs on it.

  • pixel_quality: How well the customer information sent with a pixel's server-side events can be matched to people, per event.

  • list_creative_ads: Ads that use one creative: id, name, status and where they sit.

  • list_business_pages: Facebook Pages owned by the business behind this ad account, and Pages it manages for clients.

  • activity_log: What was changed in this ad account and when: budgets, targeting, bids, statuses, schedules and new campaigns and ad sets.

  • list_experiments: A/B tests and lift studies that involve this ad account: what each tests, its dates and whether it is running.

  • get_experiment: One A/B test: its cells and how each cell did over the test window — spend, results and cost per result.

  • get_business_profile: The business behind this ad account as its owner described it: what it sells, its goal, target cost per result or ROAS, markets and rules.

  • infer_business_profile: Suggest a business profile from this ad account and its website: main goal, markets, what it sells. Saves nothing.

  • client_report_file: Make a report file for a client: this ad account's results for a period, with the agency's name, logo and commentary.

  • why_did_this_fail: What failed lately and why: your recent failed calls and approved changes that failed, with Meta's real error and who fixes it.

  • explain_error: Explain an error message from Meta or from this server: the cause in plain words, what to do and who does it.

  • list_catalogs: Product catalogs the business behind this ad account can use.

  • list_product_sets: Product sets of one catalog: the saved rules ads can promote.

  • list_products: Products of a catalog or of one product set, one page at a time, optionally only those matching a rule.

  • check_catalog_readiness: Whether a catalog is ready for dynamic ads: products, event sources, matching and must-fix diagnostics.

  • analyze_catalog_performance: Break catalog spend down by product: what sells, what is below target, what spends without a purchase.

  • product_performance: One product across the catalog ad sets: spend, purchases, return and its funnel.

  • catalog_funnel: View, add to cart, checkout and purchase across the catalog ad sets, with the biggest drop.

  • catalog_waste: Catalog spend that is bringing nothing back, by product, with how much of it is recoverable.

  • compare_product_sets: Product sets side by side by return, and the products that spend inside more than one of them.

  • list_catalog_data_sources: Where the products of a catalog come from: its feeds with their schedules and last uploads, and other data sources.

  • list_product_sets_for_product: Which product sets of its catalog a product is in.

  • product_feed_details: One product feed in full: file, schedule, format, default currency and its last upload.

  • list_feed_uploads: Recent fetches of a product feed: when, how many products were found and kept, errors and warnings.

  • list_feed_rules: Rules a product feed applies to its file: renamed columns, mapped values, letter case, defaults.

  • list_event_source_catalogs: Which product catalogs of the business a pixel is connected to as an event source.

  • list_instagram_posts: Recent posts, reels and stories of an Instagram account linked to this ad account, with whether each can become an ad.

  • list_lead_forms: Instant forms of a Facebook Page: name, status, how many submissions each has and the keys of its questions. get_insights, audit_conversion_tracking, audit_account, revenue_report are their own tools, not behind this router. Read-only and free: changes nothing and does not count toward the monthly change limit. An identical read within 30 seconds may return the same data (see data_age_seconds).

Input Schema

NameRequiredDescriptionDefault
actionYeslist_tools: every operation with its field names, flags and router. execute: run the read named by tool_name.
argumentsNoFor execute: the fields of the operation, plus "connection" when several ad accounts are connected. Omit or {} when it has none.
tool_nameNoFor execute: the operation name from list_tools, e.g. list_campaigns.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, yet the description still adds substantive context: list_tools 'does not call Meta and is free', several operations send 'nothing to Meta', the whole tool 'changes nothing and does not count toward the monthly change limit', and identical reads within 30 seconds may return cached data (data_age_seconds). These are real behavioral traits beyond the annotation set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The action semantics and cost/caching notes are correctly front-loaded, but the description then reproduces an enormous catalog of every operation even though it also tells the agent that list_tools exists precisely to return that catalog. That redundancy makes the block far longer than it needs to be for an agent deciding whether to call the router.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a router of this complexity, the description covers the actions, the call shape, the operation inventory, the free/read-only/no-change-limit guarantees and the caching caveat. No output schema exists, but the return behavior is adequately implied, and nothing essential for calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description genuinely extends the schema: it shows a worked execute payload, clarifies that arguments carry the operation's own fields plus 'connection' when multiple ad accounts exist, and the ~60-operation catalog effectively enumerates the otherwise opaque valid values of tool_name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Reads Meta ad accounts') and immediately defines the two actions, 'list_tools' and 'execute', with their distinct purposes. The operation catalog makes clear this is a read-only router and the closing note explicitly distinguishes it from get_insights, audit_conversion_tracking, audit_account and revenue_report, which are separate tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states when to use each action ('list_tools' to enumerate operations with field names and routers, 'execute' to run one named read) and gives a concrete call shape. It also names the sibling reads that are NOT behind this router. What's missing is guidance on when an agent should reach for this router versus the sibling read tools in the first place.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.