MCP tools reference

Plain-English map of every WinningHunter MCP tool.

• Most tools are read-only; track_brand, track_store, and save_ad write; get_ad_transcript can generate persisted transcripts
• Successful tools/call uses 1 API credit. A call that returns an error payload (invalid_argument, not_found, auth_required, …) is refunded and reports credit_charged: false

Quick list#

search_tiktok_products
search_tiktok_shops
search_tiktok_creators
search_tiktok_videos
browse_tiktok_categories
list_tiktok_category_top
autocomplete_tiktok
count_tiktok_entities
get_tiktok_product
get_tiktok_shop
get_tiktok_creator
get_tiktok_video
get_tiktok_trending_products
search_tiktok_ads
get_tiktok_ad
search_pinterest_ads
get_pinterest_ad
search_google_ads
get_google_advertiser
get_store_details
get_store_top_ads
search_facebook_ads
find_winning_products
creative_inspiration_pack
brief_competitor
scan_ad
get_ad_transcript
save_ad
list_saved_ad_boards
daily_radar
track_brand
analyze_tracked_brand
list_tracked_brands
track_store
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

43 tools total. count_tiktok_entities mirrors explore count endpoints (no row payload).

Response size#

search_facebook_ads / find_winning_products echo applied filters under mcp_filters (small). Full catalogs (allowed_niches, allowed_technologies, filter_reference, …) are opt-in: pass include_filter_reference=true. Without that flag, discover codes via an invalid filter value (returns allowed_values / allowed_niches without running the search).

search_tiktok_ads, search_pinterest_ads, and search_google_ads keep responses under the MCP client tool-result limit (~25k tokens) in three ways:

• Per-day chart series (*_history, *_timeseries — adspend_history, rank_history, like_count_history, …) are dropped. The names appear in omitted_series_fields.
• Fields that carry a byte-identical duplicate value are folded to one canonical name. The response lists field_aliases, e.g. {"poster": "image", "text": "description"} — read the canonical field instead.
• If the rows still exceed the budget, the lowest-ranked ads are dropped and the response sets truncated: true with a truncated_reason. Lower limit or narrow the filters to get complete pages.

Ad search filters are validated#

The three ad-platform search tools reject unknown values instead of silently ignoring them. An invalid sort_by, niches, format, or ad_score returns error: invalid_argument with the allowed list (allowed_sort_by, allowed_niches, …) and does not consume a credit. Every successful response echoes applied_filters so you can confirm what actually reached the query.

Niche taxonomies are per-platform#

Meta niche codes are not shared with the other platforms.

• TikTok has its own 15 keys: beauty, bags, car, romanticgifts, clothing, watches, jewelry, womenclothing, menclothing, toys, child, home, pet, gadgets, outdoor. Raw TikTok label_######## industry codes also work. Passing Meta codes returns invalid_argument with the valid keys.
• Pinterest and Google have no niche/category filter. Use keyword, domain, or promoter_name/advertiser_name.

Metric coverage by ad platform#

Not every metric exists on every platform. Sorting or filtering on an absent metric gives you noise, so pick a field the platform actually populates:

Two date fields are easy to confuse on Pinterest: created_at is when WinningHunter indexed the ad (nearly always today), while started is the ad's launch date. date_from / date_to filter started.

Saved ads and boards#

save_ad is board-backed for every platform: facebook, facebook_post, pinterest, google and tiktok. Omit board_id to land on the default "All Saved Ads" board, or call list_saved_ad_boards first and pass a specific board_id. Saving the same ad to the same board twice is a no-op and comes back as already_saved: true.

TikTok used to be the exception — saves went to a separate per-user list and board_id was ignored. That is no longer the case. TikTok saves now go to boards like everything else and are additionally mirrored into the legacy per-user list, which is what keeps the filled heart and the "saved only" toggle on the /tiktok-ads grid working. TikTok ads saved before this change stay visible under "All Saved Ads" but are not attached to a board until they are saved again.

Store technology codes#

technologies on the TikTok and Pinterest ad tools takes two-letter codes, not product names: SH Shopify, WC WooCommerce, WP WordPress, PP PayPal, KL Klaviyo, GO Google Analytics, CO Cookiebot, TP Trustpilot, SL ShopLazza, SI ShopLine, MG Magento.

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#

• 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 growth summary; set include_creative_signals=true for per-brand creative tabs — slower)
• track_brand (add a Meta page to Brand Tracker)
• analyze_tracked_brand (single-brand deep dive)
• track_store (add a Shopify store/domain to Store Tracker)
• list_shopify_store_filter_options (valid Store Explorer filter values, including dynamic themes/apps/taxonomy)
• save_ad (save a creative to Saved Ads)
• list_saved_ad_boards (board ids and folders for save_ad; covers every platform, TikTok included)
• get_ad_transcript (fetch or generate an ad transcript)
• check_credits (programmatic API pool — same shape as REST GET /api/v1/credits: used / limit / remaining / addon_remaining / total_remaining)

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. Deep pagination requires the opaque scroll cursor from the previous response (mcp_pagination.scroll_next) — incrementing page alone does not advance the result set (especially with sort_by=lastseen).

sort_order is asc or 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; most_recent / mostrecent / ad_started / ad_creation → mostrecent; 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): All (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 or 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 (Fashion & Clothing). Useful fashion-ad refinements are WC = Women's Clothing, MC = Men's Clothing, FW = Footwear / Shoes, BG = Bags, JY = Jewellery, WT = Watches, and SG = Sunglasses. The runtime also accepts dashboard names like Fashion & Clothing; 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, FB page likes, ad spend, reach, monthly visits, products on store, price, copy length, video length, days running), active-ads % growth (min_active_ads_growth / max_active_ads_growth + active_ads_growth_period — human percent, periods 1w | 1m | 3m only; dashboard 14d/2m and EU reach % growth are omitted from MCP), 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.

scan_ad (ad detail / angles)#

Use when the user is viewing one ad and wants hook, angle, landing page, days running, or a scaling read.

Do not pass context.ad.landing_url, brand domains, or product pages — those are storefront URLs, not ad ids. Use web_fetch separately only if you need on-page product copy from the landing URL.

Returns: hook, angle, landing_page, days_running, verdict (likely_scaling | early_or_testing | insufficient_data), plus full ad row.

TikTok Shop#

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

Pagination: TikTok explore tools use keyset cursors: omit after on the first call; pass meta.next_cursor (also echoed as mcp_pagination.after_next) as after on the next call with the same filters/sort. When after is set, the backend ignores page. Prefer after for deep downloads; page remains fine for shallow offset paging. Stop when next_cursor / after_next is null. (HTTP explore uses the same after cursor on /api/v1/tiktok-shop/{entity}/explore.)

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; reviews → 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#

track_store(store_url) adds a store/domain to Store Tracker. It uses the same validation, plan limit, store resolution, and bestseller scrape queue as the dashboard.

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 or niche = one of the Explore Shops verticals. For fashion/clothing/apparel, use Clothing. 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#

track_brand(page_id?, url?) adds a Facebook / Meta page to Brand Tracker. Provide either a page_id or a Facebook Ad Library URL containing view_all_page_id; it uses the same plan limit and global tracking queue as the dashboard.

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. fashion, 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 supports track_brand, track_store, save_ad, and Meta ad transcript generation via get_ad_transcript
   • Favorites, presets, TikTok 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).
Most MCP tools are read-only. `track_brand`, `track_store`, and `save_ad` write. `get_ad_transcript` can generate persisted transcripts.
Successful tools/call costs 1 API credit.
If user asks for other writes (favorites/presets/TikTok 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