Spytrend

Search domains and their traffic

search_shops

Read-only

Search domain-level traffic surfaces with commerce and advertising intelligence. A row is a DOMAIN/SUBDOMAIN surface, not necessarily a company or product. visits is a MONTHLY estimate for traffic_as_of (not live traffic); fetched_at is ingestion time. Judge every estimate using traffic_quality, traffic_confidence, traffic_is_small, traffic_is_data_from_ga, traffic_data_status and history. traffic_paid_share is display + paid-search + paid-social share; trust it only when traffic_sources_available=true. visits_growth_pct is latest-vs-previous month PERCENT; min_growth and sort_by=growth only return growth_qualified rows (current cohort, contiguous 3-month window, previous month >=10k, non-small estimate, confidence >=0.60). category is an estimated SITE category and may be missing/wrong; ai_category is SpyTrend's AD category and is preferred for ad-market discovery. created_from/to filter domain_created: best available registration date of the REGISTRABLE ROOT, not product/subdomain launch or SpyTrend first-seen. The ClickHouse row does not retain whether that date came from the preferred registry lookup or the legacy fallback. traffic_start_max compares the current estimate with the MAXIMUM of both preceding complete months and excludes stale/low-quality windows; combine with traffic_end_min. ads_monthly counts ads first observed by SpyTrend (first_parsed_date), and each point has is_complete=false for the open current month. fb_signal is correlation_only, not causal attribution; honest statuses are correlated_growth, ad_growth_ahead, ad_growth_flat_traffic, ad_growth_declining_traffic, traffic_growth_without_fb_growth, stable_or_mixed and insufficient_signal. sort_by=relevance REQUIRES ai_category and is rejected otherwise. Sorts: visits/revenue/growth/ads/rank/backlinks/ai_traffic/products/fb_score/per_ad/relevance. a separate legacy snapshot is kept alongside; never substitute its similarly named traffic fields for the primary visits/traffic_as_of contract. Returns total, has_more and offset. Use get_shop for the full source payload. Saving shops is free. 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
`q`	No	substring search on the normalized domain; URLs are normalized to their host
`limit`	No	max results (default 20; each delivered result costs 1 token).
`saved`	No	saved scope selector. Use saved=all to restrict results to shops saved in ANY favourites folder.
`offset`	No	pagination offset (0-based)
`pixels`	No	comma-separated pixel identifiers to filter by
`country`	No	ISO-2 country code — keep only shops with traffic in this country
`has_ads`	No	true = only shops with at least one ad in the database
`min_ads`	No	minimum number of ads
`socials`	No	comma-separated social-media handle filters
`sort_by`	No	order by: visits (default), revenue, growth, ads, rank, backlinks, ai_traffic, products, fb_score, per_ad or relevance; relevance REQUIRES ai_category and is rejected without it
`category`	No	estimated site-category filter; may be missing or misclassified, so prefer ai_category for ad-market discovery
`platform`	No	commerce platform the site runs on: Shopify, WooCommerce, WordPress, Wix, Squarespace, Magento, PrestaShop or BigCommerce
`fb_status`	No	observed ads/traffic relationship: correlated_growth, ad_growth_ahead, ad_growth_flat_traffic, ad_growth_declining_traffic, traffic_growth_without_fb_growth, stable_or_mixed or insufficient_signal; correlation only
`folder_id`	No	restrict results to shops saved in this favourites folder UUID. Mirrors the /shops folder view.
`created_to`	No	registrable-root registration date on/before YYYY-MM-DD; NOT product/subdomain launch; per-row RDAP/WHOIS-vs-legacy provenance is unavailable
`max_bounce`	No	maximum bounce rate in PERCENT (0-100) — max_bounce=30 keeps only sticky sites, the reason this control exists. The server converts it to the fraction the column stores.
`max_growth`	No	upper end of the traffic-growth range (percent). The /shops panel has BOTH ends; pair it with min_growth for a band such as 10..50.
`max_per_ad`	No	maximum visits-per-ad efficiency
`max_visits`	No	maximum monthly visits
`min_bounce`	No	minimum bounce rate in PERCENT (0-100), matching the visible /shops bounce slider — min_bounce=70 keeps only high-bounce sites. The server converts it to the fraction the column stores.
`min_growth`	No	minimum latest-vs-previous monthly visits growth PERCENT; only current-cohort growth_qualified rows pass (contiguous 3 months, previous >=10k, non-small, confidence >=0.60)
`min_per_ad`	No	minimum visits-per-ad efficiency (traffic / active ads)
`min_visits`	No	minimum monthly visits
`sort_order`	No	sort direction: asc or desc (default desc)
`ai_category`	No	AI category slug the shop's ads belong to (e.g. ecommerce_and_retail)
`min_revenue`	No	minimum estimated monthly revenue (USD)
`shopify_app`	No	Shopify app slug filter (shops using this app)
`created_from`	No	registrable-root registration date on/after YYYY-MM-DD; NOT product/subdomain launch or SpyTrend first-seen; per-row RDAP/WHOIS-vs-legacy provenance is unavailable
`has_products`	No	true = only shops with a product catalog in our database
`min_products`	No	minimum number of catalogued products
`shopify_plan`	No	Shopify plan name filter (e.g. Basic, Shopify, Advanced)
`min_backlinks`	No	minimum total backlinks
`shopify_theme`	No	Shopify theme slug filter
`has_ai_traffic`	No	true = only shops receiving AI-referred traffic (ai_traffic_share > 0)
`has_trustpilot`	No	true = only shops with Trustpilot reviews
`country_exclude`	No	ISO-2 country code to exclude from results
`traffic_end_min`	No	latest monthly estimate at traffic_as_of is at least this value; combine with traffic_start_max
`traffic_start_max`	No	maximum allowed baseline traffic, where baseline=max(two complete months before traffic_as_of); stale, low-quality, incomplete and non-contiguous windows are excluded; combine with traffic_end_min
`min_trustpilot_rating`	No	minimum Trustpilot rating (0-5)
`exclude_infrastructure`	No	drop rows that are transit rather than an offer — link shorteners / link-in-bio, app stores and marketplaces, social networks and messengers, ad servers. Every row also carries surface_role (destination \| redirect \| store \| social \| adserver; absent for an ordinary merchant site) so you can filter yourself instead. NOTE: rows are dropped after the page is fetched, so an excluded page can return fewer than limit rows — page on has_more/offset, not on row count.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	Yes
`meta`	No
`total`	Yes
`offset`	Yes
`has_more`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 2, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses many behavioral nuances: visits is a monthly estimate not live, traffic_paid_share is only trustworthy under a condition, growth filtering has precise qualification rules, created_from/to refer to registrable root not first-seen, fb_signal is correlation-only, sort_by=relevance requires ai_category, pagination total_status can be 'restricted', quota per delivered result, concurrency gating, and autonomous-agent linking requirements. This far exceeds the annotation baseline.

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 tightly packed with critical information. It is front-loaded with the core definition, then details, then operational constraints (quota, rate limits, concurrency). Every section earns its place; the length is justified by the tool's complexity (40 parameters, multiple data-quality caveats). Minor redundancy (e.g., some parameter semantics repeated in the schema) means it could be trimmed slightly, but it remains well-structured.

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 the tool's complexity, the description covers all essential aspects for correct invocation: output pagination (total, has_more, offset), free-plan behavior, quota accounting, rate limit details, concurrency admission, and relationship to related tools. The output schema presumably handles field-level documentation, and the description complements it with interpretive guidance. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% parameter description coverage, yet the description adds essential global semantics not fully captured by individual parameter descriptions: e.g., the interpretation of visits_growth_pct as percent and its qualification rules, the meaning of traffic_start_max as max of preceding two complete months, the caveat about category vs ai_category, and the trust condition for traffic_paid_share. It also explains the interaction between parameters (e.g., min_growth and sort_by=growth). This adds significant value beyond the schema.

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 states precisely that the tool searches domain-level traffic surfaces with commerce and advertising intelligence, and clarifies the unit of analysis (domain/subdomain, not necessarily company/product). It clearly distinguishes from siblings like get_shop (full payload) and search_ads/search_creatives. The core purpose is unmistakable.

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?

The description provides explicit guidance: use get_shop for the full source payload, and notes that heavy analytical tools (get_trends, search_ads, search_creatives) are concurrency-gated while this tool is not heavy. It also explains quota semantics, rate limits, and when free-plan restrictions apply. This gives clear selection and operational context.

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.