Spytrend

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 token, 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.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	No	free-text filter, at most 100 UTF-8 bytes
`saved`	No	saved scope: all
`dedupe`	No	collapse duplicate creative rows
`channel`	No	messaging shortcut: whatsapp or telegram
`country`	No	legacy single ISO-2 include country; prefer countries
`date_to`	No	Facebook launch upper bound YYYY-MM-DD
`page_id`	No	Facebook page id or bounded facebook.com page URL
`pixel_id`	No	bounded Facebook pixel identifier
`countries`	No	unique uppercase ISO-2 include countries, maximum 200
`date_from`	No	Facebook launch lower bound YYYY-MM-DD
`folder_id`	No	non-zero favorite folder UUID
`languages`	No	target language slugs, maximum 50
`platforms`	No	Meta publisher placements, maximum 6
`search_in`	No	query scope: all, title, advertiser or text
`categories`	No	AI category slugs, maximum 50
`cta_buttons`	No	CTA labels, maximum 50
`hub_domains`	No	normalized destination hostnames, maximum 50
`media_types`	No	media types: image or video
`parsing_geo`	No	one uppercase ISO-2 parser GEO
`resolved_ip`	No	resolved IPv4/IPv6 address
`search_term`	No	historical search term, at most 100 UTF-8 bytes
`domain_zones`	No	lowercase landing TLD/zone labels, maximum 50
`hub_category`	No	closed top-level hub category
`status_today`	No	current status: active, inactive or vanished
`webmaster_id`	No	non-zero webmaster UUID
`advertiser_id`	No	non-zero advertiser UUID
`country_match`	No	country semantics: any or only
`first_seen_to`	No	Spytrend discovery upper bound YYYY-MM-DD
`max_countries`	No	maximum additional/total GEOs, 0 disables, maximum 200
`ai_subcategory`	No	taxonomy-valid AI subcategory slugs
`days_active_to`	No	non-negative active-days upper bound; null omits the filter, 0 is meaningful
`favorites_only`	No	restrict to the token-derived user's favorite webmaster scope
`impressions_to`	No	non-negative impressions bucket upper bound
`landing_domain`	No	normalized landing hostname
`max_page_likes`	No	non-negative page-like upper bound; null omits the filter, 0 is meaningful
`media_count_to`	No	non-negative media-count upper bound
`min_page_likes`	No	non-negative page-like lower bound
`platforms_mode`	No	placement semantics: any or all
`first_seen_from`	No	Spytrend discovery lower bound YYYY-MM-DD
`min_days_active`	No	non-negative active-days lower bound
`ai_enriched_only`	No	only AI-enriched ads
`creative_formats`	No	creative formats: video, carousel, single or dynamic
`impressions_from`	No	non-negative impressions bucket lower bound
`media_count_from`	No	non-negative media-count lower bound
`ai_confidence_min`	No	minimum AI confidence: low, middle or high
`contains_in_links`	No	tracking-link fragment, at most 255 UTF-8 bytes
`fan_page_categories`	No	validated fan-page category groups
`landing_domain_exact`	No	restrict landing domain to exact hostname
`max_items_per_section`	No	rows per breakdown section, default 10, maximum 20

Output Schema

TableJSON Schema

Name	Required	Description
`win`	No
`data`	No
`tier`	No
`error`	No	Present only when isError is true: machine-readable failure. The human explanation stays in content.
`total`	No
`params`	No	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.
`domains`	No
`pending`	No
`statuses`	No
`countries`	No
`ai_labeled`	No
`from_cache`	No
`scope_note`	No
`webmasters`	No
`advertisers`	No
`computed_at`	No
`total_status`	No
`ai_categories`	No
`display_total`	No
`result_status`	No
`sections_ready`	No
`sections_total`	No
`display_total_basis`	No
`retry_after_seconds`	No
`display_total_status`	No
`auto_applied_verticals`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 25, 2026

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"
-]

Changed2 schema fields changedSep 21, 2026

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"

First observedSep 2, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, the description discloses substantial behavioral details: per-row token cost, refunds for pending/error, default and maximum row counts, null-vs-zero semantics for totals, status-section filter exclusivity, and the flat output shape with readiness/truncation metadata. It also lists unsupported features (pagination, sorting, TikTok, raw SQL, storage coordinates), giving the agent a full behavioral contract.

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

Conciseness5/5

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

Though long, the description is dense and front-loaded: purpose first, then cost, limits, output shape, null semantics, filter behavior, unsupported features, and retry policy. Each sentence contributes unique operational guidance, and none of it is redundant with the annotations or schema.

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 paid execution model, this description is remarkably complete. It covers purpose, cost, result structure, null handling, filter interactions, disallowed features, and retry behavior. An agent can invoke this tool correctly without needing external documentation or additional clarification.

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 value by explaining how parameters like max_items_per_section behave in context (default 10, max 20) and how filters interact across sections (only the status section removes its own filter). It also ties parameters to output semantics through the flattened data/dimension note, exceeding mere schema restatement.

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 description opens with a specific verb and resource: 'Get the bounded analytics overview for the current Meta /ads selection', then enumerates the exact breakdowns returned (statuses, countries, AI categories, landing domains, advertisers, webmasters). This clearly distinguishes it from sibling search/ad/get tools by focusing on aggregate analytics for a selection.

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 provides clear context that this is a paid, Pro-or-higher surface and gives explicit retry instructions ('Re-issue the identical call after retry_after_seconds when pending; do not blindly retry paid calls'). It does not explicitly name alternatives, so a score of 5 is not reached, but the usage context is unmistakable.

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

All Spytrend tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.