Spytrend

Search hubs (destinations)

search_hubs

Read-only

Explore HUBS — where ads send traffic, grouped by destination (Social Media: Facebook/Instagram/Telegram/WhatsApp; App Stores; Amazon; E-commerce; Popular; Platforms). Call WITHOUT hub to get the catalog (the list of hub slugs + labels) — that is FREE. Call WITH hub set to a slug to drill into that hub's destination profiles, filtered by query (free-text profile name/id search), ai_category, min_total/min_active/min_sticky ads, date_from/date_to, window (7d/30d/90d; NOTE: lifetime counters on the default snapshot path — window is a no-op there, prefer date_from/date_to or sort=active_desc for recency), country (ISO alpha-2 — keep only profiles with ads in that geo) and exclude_cloaking (drop multi-geo redirect/cloaking domains), ordered by sort (ad_count_desc default = LIFETIME volume, ad_count_asc, last_seen_desc, sticky_desc, sticky_asc, active_desc/active_asc = CURRENTLY-active 'hot now', or relevance = ad volume IN the selected country — needs country). For a per-geo ranking of real storefronts (e.g. top e-commerce in BR), combine country + sort=relevance + exclude_cloaking. The catalog call (no hub) is FREE; profile rows cost 1 token each. FREE PLAN COUNTS: when the plan's archive window narrows a request, pagination.total_status is "restricted" and meta.plan_window_cutoff names the boundary — the count then describes the window actually searched, NOT the one requested, so a zero means "nothing in the archive window" and never "nothing exists". QUOTA: 1 token per DELIVERED result from your plan balance (free starter: 500 tokens lifetime; paid plans: 40,000/month; short pages auto-refund — you pay only for results you receive). Default page is 20 results = 20 tokens; pass limit (1–200) to size it. get_usage is free. Autonomous agents must be linked to a spytrend account to access data — an unlinked agent gets an actionable connect-your-account refusal (create agent credentials at spytrend.com/settings?tab=ai, or a human claims it by client_id), NOT a server error. Calls are rate-limited per authenticated user (deployment defaults: 60/minute and 1000/hour); a rate-limit refusal is an MCP tool error with structured error.code=rate_limit_exceeded, scope, window and retry_after_seconds. CONCURRENCY: heavy analytical calls (get_trends, search_ads, search_creatives) are admitted ONE AT A TIME per account — fanning out 5-10 of them in parallel does not go faster, it returns admission refusals for all but one. Issue heavy calls sequentially; light lookups (get_ad, get_advertiser, get_usage) are not gated.

Input Schema

TableJSON Schema

Name	Required	Description
`hub`	No	hub slug to drill into. IT IS THE NESTED ONE: the catalog (returned when hub is omitted) is TWO levels — each row is a CATEGORY with its own slug (social_media, app_stores, …) and a hubs[] array whose entries carry the drill-in slugs (facebook, instagram, google_play, …). Pass hubs[].slug, NOT the category slug — a category slug is rejected. Leave empty to list the hub catalog (free).
`sort`	No	profiles only: ad_count_desc (default, LIFETIME volume), ad_count_asc, last_seen_desc, sticky_desc, sticky_asc, active_desc/active_asc (CURRENTLY-active ads — 'what's hot now', avoids the dead-domain top), or relevance (rank by ad volume in the selected country — REQUIRES country)
`limit`	No	profiles only: max results (default 20; each delivered profile costs 1 token). The catalog call (no hub) is free.
`query`	No	profiles only: free-text search by profile id/name within the hub (the same box as the profile search on the /hubs page). Requires hub.
`window`	No	profiles only: lookback window 7d, 30d (default) or 90d. NOTE: on the default snapshot read path counters are LIFETIME and window is a no-op — for recency use date_from/date_to (profile activity dates) or sort=active_desc instead
`country`	No	profiles only: ISO-3166 alpha-2 country code (e.g. US, BR). Keeps only profiles with ads in that country and enables sort=relevance (rank by ad volume IN that country) — turns the global lifetime top into a real per-geo ranking.
`date_to`	No	profiles only: active on or before this date (YYYY-MM-DD)
`date_from`	No	profiles only: active on or after this date (YYYY-MM-DD)
`min_total`	No	profiles only: minimum total ads
`min_active`	No	profiles only: minimum active ads
`min_sticky`	No	profiles only: minimum sticky (long-running) ads
`ai_category`	No	profiles only: AI category slug filter
`exclude_cloaking`	No	profiles only: drop multi-geo redirect / cloaking domains (a real storefront targets a few countries; a cloaking redirect runs in 90+). Use with country+relevance to surface genuine storefronts instead of infrastructure domains.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No
`meta`	No
`error`	No	Present only when isError is true: machine-readable failure. The human explanation stays in content.
`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.
`pagination`	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: -[
-  "data",
-  "pagination"
-]

First observedSep 2, 2026

TDQS

A4.6/5.0

Behavior5/5

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, destructiveHint) by disclosing quota/token costs, rate limits, concurrency admission rules, pagination restriction behavior, and the window no-op on the snapshot path. It also explains error handling for rate limits and unlinked agents, providing comprehensive behavioral context.

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?

The description is long but well-organized into sections (QUOTA, RATE LIMITS, CONCURRENCY). It front-loads the core purpose and provides necessary operational details. While some might argue it is verbose, every section addresses a critical aspect of correct usage, making it appropriately sized for a tool with 13 parameters and multiple behavioral constraints.

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?

The description is exceptionally complete. It covers all parameters, usage modes, quotas, rate limits, concurrency, error handling, and even mentions the output schema's pagination.total_status. Given the tool's complexity and the availability of an output schema, nothing an agent needs to call 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?

The schema descriptions already cover all 13 parameters with 100% coverage. The description adds value by explaining interactions and caveats, such as window being a no-op on the default snapshot path, country enabling relevance sort, and the distinction between category slugs and hub slugs. This exceeds the baseline for high schema coverage.

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 clearly states the tool's purpose: 'Explore HUBS — where ads send traffic, grouped by destination...' It specifies the resource (hubs) and action (explore/search), distinguishes between catalog and drill-in modes, and differentiates from sibling tools like search_ads and search_creatives by focusing on destinations rather than individual ads or creatives.

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?

The description provides clear usage instructions: call without hub for the catalog, with hub to drill into profiles. It explains parameter combinations (e.g., country+sort=relevance+exclude_cloaking for per-geo ranking). However, it does not explicitly mention alternatives or when NOT to use this tool, relying on the distinct purpose to implicitly separate it from siblings.

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.