Skip to main content
Glama

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 MCP credit 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 MCP credit per DELIVERED result from your plan balance (free starter: 500 MCP credits lifetime; paid plans: 40,000/month; short pages auto-refund — you pay only for results you receive). Default page is 20 results = 20 MCP credits; 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. 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": "search_hubs"
  }
}

Input Schema

NameRequiredDescriptionDefault
hubNohub 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).
sortNoprofiles 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)
limitNoprofiles only: max results (default 20; each delivered profile costs 1 MCP credit). The catalog call (no hub) is free.
queryNoprofiles only: free-text search by profile id/name within the hub (the same box as the profile search on the /hubs page). Requires hub.
windowNoprofiles 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
countryNoprofiles 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_toNoprofiles only: active on or before this date (YYYY-MM-DD)
date_fromNoprofiles only: active on or after this date (YYYY-MM-DD)
min_totalNoprofiles only: minimum total ads
min_activeNoprofiles only: minimum active ads
min_stickyNoprofiles only: minimum sticky (long-running) ads
ai_categoryNoprofiles only: AI category slug filter
exclude_cloakingNoprofiles 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

NameRequiredDescriptionDefault
dataNo
metaNo
errorNoPresent only when isError is true: machine-readable failure. The human explanation stays in content.
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.
paginationNo
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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedOutput schema / properties / pagination / additionalProperties
      Previous value: -falseNew value: +true
    • addedOutput schema / properties / pagination / properties / degraded
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / pagination / properties / degraded_reason
      Added value: +{
      +  "type": "string"
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"profiles only: max results (default 20; each delivered profile costs 1 token). The catalog call (no hub) is free."New value: +"profiles only: max results (default 20; each delivered profile costs 1 MCP credit). The catalog call (no hub) is free."
    • 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: -[
      -  "data",
      -  "pagination"
      -]
  4. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly/openWorld/non-destructive, and the description goes well beyond them: catalog is free, profile rows cost 1 credit each with short pages auto-refunded, plan-window truncation surfaces as pagination.total_status="restricted" with meta.plan_window_cutoff, and unlinked agents get a connect-account refusal rather than a server error. The gaps are that the concurrency paragraph names get_trends/search_ads/search_creatives as gated but never says whether search_hubs itself is admitted one-at-a-time, and much of the quota/pricing/auth prose reads as boilerplate shared across the toolset.

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 first sentence front-loads purpose well, but the remainder is one dense ~450-word block mixing tool-specific mechanics with account-wide policy (quota, rate limits, concurrency, pricing consent, agent linking) that likely repeats verbatim on every sibling. The tool-specific meat is buried mid-paragraph and would be clearer as separated catalog/drill-down/cost sections.

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 13-parameter, two-mode, credit-metered tool with an output schema and existing annotations, nothing an agent needs to call it correctly is missing: both modes, cost per mode, filter interactions, ordering semantics, truncation signalling, and pre-call requirements (estimate_cost, accept_pricing_terms) are all stated.

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% and the schema already carries most per-parameter meaning, including the hub nesting caveat and the snapshot-window no-op, so those repeats earn little. What is genuinely additive is the cross-parameter recipe — that country enables sort=relevance, that relevance ranks by ad volume *in* that country, and that ad_count_desc means lifetime volume while active_desc means "hot now" — which resolves real disambiguation the schema leaves to the reader.

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?

"Explore HUBS — where ads send traffic, grouped by destination" gives a specific verb, resource, and a plain-language gloss of an unfamiliar concept, then immediately splits the tool into its two distinct modes (catalog vs. drill-down). An agent can tell this apart from search_ads/search_advertisers without opening any schema.

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

Usage Guidelines5/5

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

Explicit when-to-use branches: "Call WITHOUT hub to get the catalog ... that is FREE" vs. "Call WITH hub set to a slug to drill into that hub's destination profiles." It also prescribes a concrete filter recipe ("combine country + sort=relevance + exclude_cloaking") for the per-geo storefront use case, which is real routing guidance rather than inference.

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.