MCP tools reference (simple)

This is the plain-English version of the MCP tools list.

• MCP URL: https://app.winninghunter.com/mcp
• Full setup guide: Connect MCP
• All tools are read-only
• Successful tools/call uses 1 API credit

Quick list (all 30 tools)#

search_tiktok_products
search_tiktok_shops
search_tiktok_creators
search_tiktok_videos
count_tiktok_entities
browse_tiktok_categories
list_tiktok_category_top
autocomplete_tiktok
get_tiktok_product
get_tiktok_shop
get_tiktok_creator
get_tiktok_video
get_tiktok_trending_products
search_facebook_ads
find_winning_products
creative_inspiration_pack
brief_competitor
scan_ad
daily_radar
analyze_tracked_brand
list_tracked_brands
list_shopify_store_filter_options
search_shopify_stores
search_shops
find_similar_shops
find_similar_stores_by_image
search_exploding_topics
get_exploding_topic_detail
autocomplete_exploding_topics
check_credits

How to think about the tools#

1) Find things#

Use these first:

• search_tiktok_products
• search_tiktok_shops
• search_tiktok_creators
• search_tiktok_videos
• search_facebook_ads
• find_winning_products
• creative_inspiration_pack
• brief_competitor
• scan_ad
• search_shopify_stores
• search_shops
• find_similar_shops
• find_similar_stores_by_image
• search_exploding_topics

2) Open details#

Use an ID from search results:

• get_tiktok_product
• get_tiktok_shop
• get_tiktok_creator
• get_tiktok_video
• get_exploding_topic_detail

3) Helpers#

• count_tiktok_entities (counts by entity)
• browse_tiktok_categories (category tree and views)
• list_tiktok_category_top (top items in one category)
• autocomplete_tiktok (typeahead suggestions)
• autocomplete_exploding_topics (topic suggestions)
• get_tiktok_trending_products (TikTok Shop trending)
• daily_radar (tracked-brand changes)
• analyze_tracked_brand (single-brand deep dive)
• list_shopify_store_filter_options (valid Store Explorer filter values, including dynamic themes/apps/taxonomy)
• check_credits (remaining API credits)

Most common arguments#

Most search tools use these:

• keyword
• country
• page
• size
• sort_by
• sort_order

For Meta ad tools, page is 1-based in MCP (1 = first page), even though the dashboard backend uses 0-based indexing internally.

sort_order is asc of desc (default desc) on every tool that accepts it.

Most detail tools use:

• id
• slice (which part you want)

Allowed sort_by per tool#

Pass any string from the table below. Common aliases are normalized automatically (case-insensitive). Anything else falls back to the default sort and the response includes a mcp_sorting block describing what was applied.

Meta ad library#

Aliases: created / created_at / date / recent / newest / latest → datefound; last_ad_started → lastseen; first_ad_started / oldest / earliest → datefound (ascending); active_ads → pageactiveads; monthly_visits → monthlyvisits. For within-brand ad_rank (“top ad from [brand]”), use toprank or aliases rank, ranking, ad_rank, top_ad, best_ranked, best_ad, adrank, topad, …; spaced phrases like top rank / top ad normalize to toprank. sort_order is ignored for toprank (always ascending rank).

searchkeyword (field scope for keyword on Meta tools): Alle (default), landingurl, pagename, adtext, productname. This is not a niche/category field; aliases like landing_url, page_name, ad_text, product are normalized too. If an agent mistakenly sends a niche/category term as searchkeyword with no keyword / niche (for example searchkeyword: "Fashion"), the MCP tool recovers it as the matching niche (CG) instead of failing schema validation.

For Meta vertical/category searches, use niche of niches instead of keyword-only filtering. Treat user wording like “category”, “niche”, “vertical”, “market”, or “product category” as a request for this Meta niche filter. The MCP input schema exposes the dashboard niche codes as an enum, so a fashion query should be sent as niche=CG (Mode & Kleding). Useful fashion-ad refinements are WC = Women's Clothing, MC = Herenkleding, FW = Schoeisel / Schoenen, BG = Tassen, JY = Sieraden, WT = Horloges, and SG = Sunglasses. The runtime also accepts dashboard names like Mode & Kleding; invalid values return allowed_niches instead of being passed through.

rank_growth_filter is also validated against the dashboard options: comma-separated rising, stable, declining.

Other Meta dashboard filters are exposed as MCP args and validated before calling /api/fb-ads: countries / exclude_countries, technology / technologies, language / languages / exclude_languages, apps / exclude_apps, theme / themes, scaling, media_type, page_type, ad_score, low_impressions, range filters (min_* / max_* for duplicates, active ads, ad spend, reach, monthly visits, products on store, price, copy length, video length, days running), and date ranges (ad_created_*, last_seen_*, product_created_*, page_created_*). Theme names must be exact dashboard Themes values; apps accept dashboard app ids or app names. Date ranges require both *_from and *_to in YYYY-MM-DD.

TikTok Shop#

All TikTok Shop search tools default to sort_by=revenue. Allowed values match the dashboard's sortable columns.

For list_tiktok_category_top, get_tiktok_product (creators / videos slices), get_tiktok_shop (products / videos / creators slices), get_tiktok_creator (shops / products / videos slices), and get_tiktok_video (similar slice), the sort_field arg uses the matching entity's allow-list above.

Aliases auto-normalized across TikTok Shop tools: units_sold / units / sales / sold → sold_count; gmv → revenue; gmv_30d / revenue_30d → revenue_30_days; growth / revenue_growth / gmv_growth_rate → revenue_growth_rate; sales_growth → sales_growth_rate; price / avg_price → avg_unit_price; rating → shop_rating; recensies → product_review_cnt; followers_count → followers; views → views_30_days; likes → likes_30_days; roas → estimated_roas; duration → video_duration; date / published → publish_date.

Shopify Explore Shops#

Aliases: revenue / monthly_revenue / revenue_30d / 30d_revenue → 30d_rev_estimated_max; annual_revenue / yearly_revenue → revenue_1y; daily_revenue / revenue_1d → 1d_rev_estimated_max; traffic / visits / visitors / monthly_traffic → monthly_visits; avg_order_value / average_order_value / order_value → aov; traffic_growth_1m → visits_growth_pct_m1; traffic_growth_3m → visits_growth_pct_m3; revenue_change / revenue_momentum / store_revenue_change_30d → visits_growth_pct_m1 (same mapping as the live Explore Shops table when legacy revenue-delta sort was retired).

search_shopify_stores / search_shops filters (all optional unless noted). Names mirror MCP argument names:

Use list_shopify_store_filter_options before filtering by dynamic values (shopify_themes, store_apps, product_taxonomy_l1/l2/l3). Its section argument accepts all, static, themes, apps, product_taxonomy_l1, product_taxonomy_l2, product_taxonomy_l3; pass query to search dynamic option lists.

Intent playbook: “Stores in a niche” → category of niche = one of the Explore Shops verticals. For fashion/clothing/apparel, use Kleding. Avoid keyword-only niche queries. “Top / biggest by revenue” → sort_by=revenue_1y, sort_order=desc. “New in last N months” → store_created_from / store_created_to inclusive YYYY-MM-DD (both required).

Parity with POST https://app.winninghunter.com/api/shops/explore: MCP uses the same server-side POST keys (search, category, sortingKey, sortingDirection, page, pageSize, includeWlads, …). Argument mapping: keyword→search, sort_by→sortingKey, size→pageSize. Default include_wlads=false → includeWlads=0 (matches the dashboard table request that skips wlads previews).

find_similar_stores_by_image takes image_url (required) plus the same filters as above except keyword (similarity replaces text search).

Note: TikTok MCP tools also use a country argument — there it is marketplace/country context, not the same field as Shopify merchant country.

Brand tracker#

Aliases: recent / added / newest / latest / date → date_added; alphabetical / alpha / a-z → name; new / newads → new_ads; trending / momentum → growth.

Exploding Topics#

Aliases for sorting: volume → absolute_volume; exponential → exponent; recent / newest / latest → date_added; trending → growth. category accepts dashboard slugs (e.g. mode, beauty, skincare, fitness, technology, ai, …) or default for all categories.

mcp_sorting response block#

Every search/list tool that accepts sort_by (or sort/sorting) attaches an mcp_sorting object to the response payload:

{
  "mcp_sorting": {
    "requested_sort_by": "revenue_30d",
    "applied_sort_by": "revenue_30_days",
    "applied_sort_order": "desc",
    "allowed_sort_by": ["revenue", "name", "revenue_30_days", "..."],
    "normalized_from": "revenue_30d"
  }
}

If you pass an unknown sort key, mcp_sorting.warning says it fell back to the default — the tool does not error out.

Slice values for detail tools#

Use one of these slice values:

• get_tiktok_product: detail, history, metrics, creators, videos
• get_tiktok_shop: detail, history, metrics, products, videos, creators, strategy
• get_tiktok_creator: detail, history, metrics, shops, products, videos
• get_tiktok_video: detail, history, metrics, products, similar

Two easy mistakes#

1. Trending confusion

   • get_tiktok_trending_products is TikTok Shop product momentum
   • Exploding Topics is separate (search_exploding_topics + get_exploding_topic_detail)

2. Write actions

   • MCP is read-only
   • Favorites, presets, transcripts, and other writes must use REST API

Copy block for AI instructions#

Paste this into agent instructions:

Use WinningHunter MCP at https://app.winninghunter.com/mcp.
Auth can be either OAuth bearer token (connector flow) or X-API-Key (header-capable clients).
All MCP tools are read-only.
Successful tools/call costs 1 API credit.
If user asks for writes (favorites/presets/transcripts), use REST /api/v1/tiktok-shop/* instead.
When unsure about exact schema, call tools/list first.

Need the full technical detail?#

For full filter semantics and endpoint behavior:

• TikTok Shop filters
• Meta ad library
• Brands
• Shopify store explorer
• Trends