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

Input 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 MCP credit-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

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
`addon_hints`	No	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.
`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.

Changed2 schema fields changedOct 23, 2026

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"
+}

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.3/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing the credit cost per breakdown row, reservation-and-refund behavior, the row cap, flattened-with-dimension result shape, nullable totals semantics (null pending vs numeric 0), the status-section filter exception, and the retry protocol. This is unusually full behavioral disclosure for a paid read surface.

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?

Front-loads the core purpose, then cost, then retry/pricing, so an agent can decide early. It is dense and abbreviation-heavy (Pro-or-higher, PRICING block), and the 20-row cap is stated twice, but nearly every sentence carries operative information.

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?

Output schema exists, yet the description still supplies what matters for correct invocation: pricing model, credit reservation, nullability rules, truncation metadata, and the retry path. Nothing an agent needs to call this correctly and warn the user about cost appears 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 already 100%, so the baseline is 3; the description earns above that by clarifying max_items_per_section bounds and default, and by stating which parameters are deliberately rejected. It still leaves the 49 filter params to the schema rather than explaining filter interactions or date semantics.

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?

Names a specific verb and resource (analytics overview for the current Meta /ads selection) and enumerates exactly which breakdown dimensions come back. It implicitly separates itself from search_* siblings by scoping to an already-made selection, but never names those alternatives explicitly.

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?

Gives concrete operational guidance: check estimate_cost first, obtain consent via accept_pricing_terms, re-issue the identical call after retry_after_seconds on pending, and don't blindly retry paid calls. It also lists what is not accepted (pagination, sorting, TikTok, raw SQL, etc.), but never explicitly contrasts when to choose this over search_ads or get_trends.

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.