Skip to main content
Glama

Get ads selection analytics

get_ads_analytics
Read-only

Get the bounded analytics overview for the current Meta /ads selection: total and display_total plus statuses, countries, AI categories, landing domains, advertisers and webmasters. This is a Pro-or-higher paid surface; every delivered breakdown row costs 1 MCP credit, pending/error responses refund the reservation. The default is 10 rows per section and the absolute maximum is 20; results are flattened in data with a dimension field and include section readiness/truncation metadata. Totals are nullable: null with pending/unavailable status is NOT zero; exact zero is numeric 0 with an exact status. Only the status section removes its own filter; every other section uses the full filtered universe. No pagination, sorting, source, scheduler, force-scrape, TikTok, raw SQL or storage coordinates are accepted. Auto-applied subscription categories are reported in auto_applied_verticals and scope_note. Re-issue the identical call after retry_after_seconds when pending; do not blindly retry paid calls. PRICING: price × number of filters set (min 1), on paid plans ×1 after 500 MCP credits/month; one-time consent via accept_pricing_terms; before calling, get the maximum debit from estimate_cost (free) and tell the user.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_ads_analytics"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNofree-text filter, at most 100 UTF-8 bytes
savedNosaved scope: all
dedupeNocollapse duplicate creative rows
channelNomessaging shortcut: whatsapp or telegram
countryNolegacy single ISO-2 include country; prefer countries
date_toNoFacebook launch upper bound YYYY-MM-DD
page_idNoFacebook page id or bounded facebook.com page URL
pixel_idNobounded Facebook pixel identifier
countriesNounique uppercase ISO-2 include countries, maximum 200
date_fromNoFacebook launch lower bound YYYY-MM-DD
folder_idNonon-zero favorite folder UUID
languagesNotarget language slugs, maximum 50
platformsNoMeta publisher placements, maximum 6
search_inNoquery scope: all, title, advertiser or text
categoriesNoAI category slugs, maximum 50
cta_buttonsNoCTA labels, maximum 50
hub_domainsNonormalized destination hostnames, maximum 50
media_typesNomedia types: image or video
parsing_geoNoone uppercase ISO-2 parser GEO
resolved_ipNoresolved IPv4/IPv6 address
search_termNohistorical search term, at most 100 UTF-8 bytes
domain_zonesNolowercase landing TLD/zone labels, maximum 50
hub_categoryNoclosed top-level hub category
status_todayNocurrent status: active, inactive or vanished
webmaster_idNonon-zero webmaster UUID
advertiser_idNonon-zero advertiser UUID
country_matchNocountry semantics: any or only
first_seen_toNoSpytrend discovery upper bound YYYY-MM-DD
max_countriesNomaximum additional/total GEOs, 0 disables, maximum 200
ai_subcategoryNotaxonomy-valid AI subcategory slugs
days_active_toNonon-negative active-days upper bound; null omits the filter, 0 is meaningful
favorites_onlyNorestrict to the MCP credit-derived user's favorite webmaster scope
impressions_toNonon-negative impressions bucket upper bound
landing_domainNonormalized landing hostname
max_page_likesNonon-negative page-like upper bound; null omits the filter, 0 is meaningful
media_count_toNonon-negative media-count upper bound
min_page_likesNonon-negative page-like lower bound
platforms_modeNoplacement semantics: any or all
first_seen_fromNoSpytrend discovery lower bound YYYY-MM-DD
min_days_activeNonon-negative active-days lower bound
ai_enriched_onlyNoonly AI-enriched ads
creative_formatsNocreative formats: video, carousel, single or dynamic
impressions_fromNonon-negative impressions bucket lower bound
media_count_fromNonon-negative media-count lower bound
ai_confidence_minNominimum AI confidence: low, middle or high
contains_in_linksNotracking-link fragment, at most 255 UTF-8 bytes
fan_page_categoriesNovalidated fan-page category groups
landing_domain_exactNorestrict landing domain to exact hostname
max_items_per_sectionNorows per breakdown section, default 10, maximum 20

Output Schema

NameRequiredDescriptionDefault
winNo
dataNo
tierNo
errorNoPresent only when isError is true: machine-readable failure. The human explanation stays in content.
totalNo
paramsNoRequest parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason.
domainsNo
pendingNo
statusesNo
countriesNo
ai_labeledNo
from_cacheNo
scope_noteNo
webmastersNo
addon_hintsNoAdd-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about.
advertisersNo
computed_atNo
total_statusNo
ai_categoriesNo
display_totalNo
result_statusNo
sections_readyNo
sections_totalNo
creative_familiesNo
display_total_basisNo
retry_after_secondsNo
display_total_statusNo
auto_applied_verticalsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / creative_families
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "families": {
      +      "minimum": 0,
      +      "type": [
      +        "null",
      +        "integer"
      +      ]
      +    },
      +    "family_key": {
      +      "type": "string"
      +    },
      +    "linked_ads": {
      +      "minimum": 0,
      +      "type": [
      +        "null",
      +        "integer"
      +      ]
      +    },
      +    "reason": {
      +      "type": "string"
      +    },
      +    "status": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "family_key"
      +  ],
      +  "type": [
      +    "null",
      +    "object"
      +  ]
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / favorites_only / description
      Previous value: -"restrict to the token-derived user's favorite webmaster scope"New value: +"restrict to the MCP credit-derived user's favorite webmaster scope"
    • addedOutput schema / properties / addon_hints
      Added value: +{
      +  "description": "Add-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about.",
      +  "items": {
      +    "properties": {
      +      "available_data_types": {
      +        "description": "kinds of data the module confirmedly has for the object",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "info_url": {
      +        "description": "the object (or its limited breakdown) inside the module on spytrend.com",
      +        "type": "string"
      +      },
      +      "module": {
      +        "description": "nutra | crypto | web2app | search_arb | startups",
      +        "type": "string"
      +      },
      +      "object_id": {
      +        "description": "the ad id, or the site domain for site rows",
      +        "type": "string"
      +      },
      +      "preland_downloadable": {
      +        "description": "Nutra / Crypto: the saved pre-lander can be downloaded in the module",
      +        "type": "boolean"
      +      },
      +      "subscription_status": {
      +        "description": "active | not_connected",
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  3. Changed3 schema fields changed
    • addedOutput schema / properties / error
      Added value: +{
      +  "description": "Present only when isError is true: machine-readable failure. The human explanation stays in content.",
      +  "properties": {
      +    "code": {
      +      "description": "fine-grained, stable failure code (e.g. invalid_arguments, backend_busy)",
      +      "type": "string"
      +    },
      +    "kind": {
      +      "description": "failure class: invalid_argument, not_found, permission_denied, unauthenticated, quota_exceeded, rate_limited, temporarily_unavailable, unavailable_until_ready, unsupported, internal",
      +      "type": "string"
      +    },
      +    "message": {
      +      "description": "the same human text as content[0]",
      +      "type": "string"
      +    },
      +    "outcome": {
      +      "description": "activity-feed outcome class",
      +      "type": "string"
      +    },
      +    "param": {
      +      "description": "the request parameter the failure is about, when known",
      +      "type": "string"
      +    },
      +    "retry_after_seconds": {
      +      "description": "wait this long before retrying",
      +      "type": "integer"
      +    },
      +    "retryable": {
      +      "description": "true when repeating the SAME call can succeed (after retry_after_seconds when present)",
      +      "type": "boolean"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / params
      Added value: +{
      +  "description": "Request parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason.",
      +  "properties": {
      +    "applied": {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "ignored": {
      +      "items": {
      +        "properties": {
      +          "param": {
      +            "type": "string"
      +          },
      +          "reason": {
      +            "type": "string"
      +          },
      +          "to": {
      +            "description": "the parameter it was applied as, when renamed",
      +            "type": "string"
      +          },
      +          "value": {
      +            "description": "the value actually applied, when rewritten",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "normalized": {
      +      "items": {
      +        "properties": {
      +          "param": {
      +            "type": "string"
      +          },
      +          "reason": {
      +            "type": "string"
      +          },
      +          "to": {
      +            "description": "the parameter it was applied as, when renamed",
      +            "type": "string"
      +          },
      +          "value": {
      +            "description": "the value actually applied, when rewritten",
      +            "type": "string"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "tier",
      -  "result_status",
      -  "pending",
      -  "total",
      -  "total_status",
      -  "display_total",
      -  "display_total_status",
      -  "ai_labeled",
      -  "sections_ready",
      -  "sections_total",
      -  "statuses",
      -  "countries",
      -  "ai_categories",
      -  "domains",
      -  "advertisers",
      -  "webmasters",
      -  "data"
      -]
  4. Changed2 schema fields changed
    • changedInput schema / properties / first_seen_from / description
      Previous value: -"SpyTrend discovery lower bound YYYY-MM-DD"New value: +"Spytrend discovery lower bound YYYY-MM-DD"
    • changedInput schema / properties / first_seen_to / description
      Previous value: -"SpyTrend discovery upper bound YYYY-MM-DD"New value: +"Spytrend discovery upper bound YYYY-MM-DD"
  5. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds the expensive details an agent actually needs: 1 MCP credit per delivered breakdown row with refunds on pending/error, a Pro-or-higher gate, the 10-row default and hard 20-row cap, flattened results with a dimension field and readiness/truncation metadata, and the rule that only the status section drops its own filter while every other section uses the full filtered universe. The nullable-total semantics (null with pending/unavailable status is not zero; numeric 0 with an exact status is a real zero) are a genuinely non-obvious behavioral warning.

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

Conciseness4/5

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

Purpose is front-loaded in the first sentence and each subsequent sentence carries distinct payload (cost, limits, null semantics, retry, pricing, consent) with almost no filler. It is a single dense wall of text with no line breaks or grouping, so a reader must parse hard to find the retry and pricing instructions.

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?

Given 49 optional parameters, an output schema, and a credit-metered paid surface, the description covers everything an agent needs before calling: entitlement tier, per-row billing and refunds, row caps, result flattening, null-vs-zero semantics, pending retry protocol, and the required pre-call cost estimate and consent. Return-value shape is left to the output schema, appropriately.

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 adds real cross-parameter meaning: price is multiplied by the number of filters set (minimum 1), so adding filters raises cost, and max_items_per_section defaults to 10 with a ceiling of 20. It also clarifies filter interaction (status section only) and the auto_applied_verticals/scope_note reporting of subscription categories. Some of this repeats the schema (the 10/20 row limits), which keeps it below a 5.

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

Purpose4/5

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

The opening sentence names a specific verb and resource ('Get the bounded analytics overview for the current Meta /ads selection') and enumerates exactly what comes back: total/display_total plus statuses, countries, AI categories, landing domains, advertisers and webmasters. It clearly separates this aggregate/breakdown tool from ad-listing siblings like search_ads, though it never explicitly contrasts with budget_aggregates, the closest analytics-adjacent sibling.

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?

Strong operational guidance: call estimate_cost (free) first and tell the user the maximum debit, obtain one-time consent via accept_pricing_terms, and re-issue the identical call after retry_after_seconds when pending rather than blindly retrying paid calls. It also lists what is not accepted (pagination, sorting, source, scheduler, force-scrape, TikTok, raw SQL, storage coordinates). It does not say when to choose this over budget_aggregates or plain search_ads, which is the remaining gap.

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.