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 ferramentas/chamada 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
• pesquisar_anúncios_no_Facebook
• descobrir produtos vencedores
• pacote_de_inspiração_criativa
• resumo_da_concorrência
• 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)
• verificar créditos (remaining API credits)

Most common arguments#

Most search tools use these:

• palavra-chave
• país
• página
• size
• ordenar por
• sort_order

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

sort_order is asc ou desc (padrão desc) on every tool that accepts it.

Most detail tools use:

• id
• slice (which part you want)

Permitido ordenar por 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: criado / created_at / data / recente / newest / latest → data encontrada; início do último anúncio → visto pela última vez; primeiro_anúncio_iniciado / oldest / earliest → data encontrada (ascending); active_ads → pageactiveads; monthly_visits → visitas mensais. 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).

palavra-chave de pesquisa (field scope for palavra-chave on Meta tools): Todos (default), URL de destino, nome da página, texto do anúncio, nome do produto. This is não a niche/category field; aliases like landing_url, page_name, ad_text, produto are normalized too. If an agent mistakenly sends a niche/category term as palavra-chave de pesquisa with no palavra-chave / 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 ou nichos 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 (Moda e vestuário). Useful fashion-ad refinements are WC = Women's Clothing, MC = Roupas masculinas, FW = Calçados, BG = Bolsas, JY = Joias, WT = Relógios, e SG = Sunglasses. The runtime also accepts dashboard names like Moda e vestuário; 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: países / exclude_countries, technology / technologies, language / idiomas / exclude_languages, aplicativos / exclude_apps, tema / temas, dimensionamento, 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 e *_to em YYYY-MM-DD.

TikTok Shop#

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

Para list_tiktok_category_top, get_tiktok_product (criadores / vídeos slices), get_tiktok_shop (produtos / vídeos / criadores slices), get_tiktok_creator (lojas / produtos / vídeos 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 → receita; 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; revisões → product_review_cnt; followers_count → followers; views → views_30_days; likes → likes_30_days; roas → estimated_roas; duration → video_duration; data / published → data_de_publicação.

Shopify Explore Shops#

Aliases: receita / 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 filtros (all optional unless noted). Names mirror MCP argument names:

Utilização list_shopify_store_filter_options before filtering by dynamic values (shopify_themes, store_apps, product_taxonomy_l1/l2/l3). Its section argument accepts todos, static, temas, aplicativos, product_taxonomy_l1, product_taxonomy_l2, product_taxonomy_l3; pass query to search dynamic option lists.

Intent playbook: “Stores in a niche” → categoria ou niche = one of the Explore Shops verticals. For fashion/clothing/apparel, use Vestuário. Avoid palavra-chave-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 (pesquisar, categoria, sortingKey, sortingDirection, página, pageSize, includeWlads, …). Argument mapping: palavra-chave→pesquisar, ordenar por→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 palavra-chave (similarity replaces text search).

Nota: TikTok MCP tools also use a país argument — there it is marketplace/country context, não the same field as Shopify merchant país.

Brand tracker#

Aliases: recente / added / newest / latest / data → date_added; alphabetical / alpha / a-z → nome; new / newads → new_ads; trending / momentum → growth.

Exploding Topics#

Aliases for classificação: volume → absolute_volume; exponential → exponent; recente / newest / latest → date_added; trending → growth. categoria 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 ordenar por (ou classificar/classificação) 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: detalhe, history, metrics, criadores, vídeos
• get_tiktok_shop: detalhe, history, metrics, produtos, vídeos, criadores, strategy
• get_tiktok_creator: detalhe, history, metrics, lojas, produtos, vídeos
• get_tiktok_video: detalhe, history, metrics, produtos, 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:

• Filtros da TikTok Shop
• Biblioteca de anúncios do Meta
• Marcas
• Shopify store explorer
• Tendências