MCP tools reference

Plain-English map of every WinningHunter MCP tool.

• De meeste tools zijn alleen-lezen; track_merk, track_store, en save_ad write; get_ad_transcript can generate persisted transcripts
• Succesvol tools/oproep uses 1 API credit. A call that returns an error payload (ongeldig_argument, not_found, auth_required, …) is refunded and reports credit_charged: false

Sneloverzicht#

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. aantal_tiktok-entiteiten mirrors explore count endpoints (no row payload).

Response size#

zoek_op_Facebook-advertenties / winnende producten vinden echo applied filters under mcp_filters (small). Full catalogs (toegestane 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 / toegestane niches without running the search).

search_tiktok_ads, search_pinterest_ads, en 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 sorteren op, nischen, format, or ad_score opbrengsten error: invalid_argument with the allowed list (allowed_sort_by, toegestane 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: schoonheid, bags, car, romanticgifts, clothing, watches, jewelry, womenclothing, menclothing, toys, child, home, pet, gadgets, buiten. Raw TikTok label_######## industry codes also work. Passing Meta codes returns ongeldig_argument with the valid keys.
• Pinterest en Google have no niche/category filter. Use trefwoord, 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: aangemaakt op 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 en 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#

technologieën 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.

Hoe moet je over de tools denken?#

1) Zoek dingen#

Gebruik deze eerst:

• zoek_tiktok_producten
• zoek_tiktok_shops
• zoek_tiktok_makers
• zoek_tiktok-video's
• zoek_op_Facebook-advertenties
• winnende producten vinden
• creatief_inspiratiepakket
• kort_overzicht_concurrenten
• scan_ad
• zoek_shopify_winkels
• winkels zoeken
• zoek_vergelijkbare_winkels
• zoek_vergelijkbare_winkels_op_afbeelding
• zoek_trending_onderwerpen

2) Details openen#

Gebruik een ID uit de zoekresultaten:

• get_tiktok_product
• get_tiktok_shop
• get_tiktok_creator
• get_tiktok_video
• get_exploding_topic_detail

3) Helpers#

• door TikTok-categorieën bladeren (categoriebomen en weergaven)
• lijst_tiktok_categorie_top (populairste artikelen in één categorie)
• automatisch aanvullen_tiktok (suggesties tijdens het typen)
• autocomplete_populaire_onderwerpen (onderwerpsuggesties)
• get_tiktok_trending_products ( trending op TikTok Shop)
• dagelijkse_radar (tracked-brand growth summary; set include_creative_signals=true for per-brand creative tabs — slower)
• track_merk (een metapagina toevoegen aan Brand Tracker)
• analyseer_gevolgd_merk (diepgaande analyse van één merk)
• track_store (een Shopify-winkel/domein toevoegen aan Store Tracker)
• lijst_shopify_winkel_filteropties (geldige filterwaarden voor Store Explorer, inclusief dynamische thema’s/apps/taxonomie)
• 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)
• Auteursvermelding (programmatic API pool — same shape as REST GET /api/v1/credits: used / limit / remaining / addon_remaining / total_remaining)

Meest voorkomende argumenten#

De meeste zoekmachines maken hiervan gebruik:

• trefwoord
• land
• pagina
• grootte
• sorteren op
• sorteervolgorde

Voor Meta-advertentietools, pagina is 1-gebaseerd 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 pagina alone does not advance the result set (especially with sort_by=lastseen).

sorteervolgorde is asc of beschrijving (standaard beschrijving) op elk gereedschap dat dit ondersteunt.

De meeste detailtools maken gebruik van:

• id
• plak (welk deel je wilt)

Toegestaan sorteren op per stuk#

Voer een willekeurige tekenreeks uit de onderstaande tabel in. Veelgebruikte aliassen worden automatisch genormaliseerd (hoofdlettergevoelig). Voor al het andere wordt de standaardsorteervolgorde gebruikt en bevat het antwoord een mcp_sorteren blok waarin wordt beschreven wat er is toegepast.

Meta-advertentiebibliotheek#

Aliassen: gemaakt / aangemaakt op / datum / recent / nieuwste / nieuwste → gevonden op; most_recent / mostrecent / ad_started / ad_creation → mostrecent; laatste_advertentie_gestart → laatst gezien; eerste_advertentie_gestart / oudste / vroegst → gevonden op (oplopend); actieve advertenties → pageactiveads; maandelijks_aantal_bezoeken → maandelijkse bezoeken. Voor binnen hetzelfde merk ad_rank (“topadvertentie van [merk]”), gebruik topklasse of aliassen rang, ranglijst, ad_rank, top_ad, hoogst genoteerd, beste_advertentie, drankje, topad, …; zinnen met spaties zoals toppositie / topadvertentie normaliseren naar topklasse. sorteervolgorde wordt genegeerd voor topklasse (altijd in oplopende volgorde).

zoekwoord (veldbereik voor trefwoord (over Meta-tools): Alle (standaard), landingspagina, paginanaam, advertentietekst, productnaam. Dit is niet een niche-/categorieveld; alternatieve namen zoals landingspagina, paginanaam, ad_text, product worden ook genormaliseerd. Als een agent per ongeluk een niche-/categorie-term verstuurt als zoekwoord zonder trefwoord / niche (bijvoorbeeld zoekwoord: "Mode"), herstelt de MCP-tool het als de overeenkomende niche (CG) in plaats van dat de schemavalidatie mislukt.

Gebruik voor zoekopdrachten in Meta-verticalen/categorieën niche of nischen in plaats van alleen op trefwoorden te filteren. Beschouw termen die gebruikers gebruiken, zoals „categorie“, „niche“, „verticaal“, „markt“ of „productcategorie“, als een verzoek om dit Meta-nichefilter. Het MCP-invoerschema geeft de nichecodes van het dashboard weer als een opsomming, dus een zoekopdracht voor mode moet worden verzonden als niche=CG (Mode & Kleding). Handige verfijningen voor modeadvertenties zijn WC = Dameskleding, MC = Herenkleding, FW = Schoeisel / Schoenen, BG = Tassen, JY = Sieraden, WT = Horloges, en SG = Zonnebrillen. De runtime accepteert ook dashboardnamen zoals Mode & Kleding; ongeldige waarden worden geretourneerd toegestane niches in plaats van erdoorheen te worden geleid.

filter_voor_groei_in_ranglijst wordt ook getoetst aan de opties in het dashboard: door komma’s gescheiden stijgend, stabiel, afnemend.

Andere filters van het Meta-dashboard worden als MCP-argumenten beschikbaar gesteld en gecontroleerd voordat ze worden aangeroepen /api/fb-ads: landen / uitsluitingslanden, technologie / technologieën, taal / talen / talen uitsluiten, apps / apps uitsluiten, thema / thema's, schaalbaarheid, mediatype, paginatype, ad_score, weinig vertoningen, bereikfilters (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_*, laatst_gezien_*, product_created_*, page_created_*). Themanamen moeten exact overeenkomen met de waarden voor dashboardthema’s; apps accepteren dashboard-app-id’s of app-namen. Bij datumbereiken zijn beide vereist *_van en *_naar in JJJJ-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#

Alle zoekfuncties van TikTok Shop zijn standaard ingesteld op sort_by=omzet. De toegestane waarden komen overeen met de sorteerbare kolommen van het dashboard.

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 pagina. Prefer after for deep downloads; pagina 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.)

Voor lijst_tiktok_categorie_top, get_tiktok_product (makers / video's plakjes), get_tiktok_shop (producten / video's / makers plakjes), get_tiktok_creator (winkels / producten / video's plakjes), en get_tiktok_video (vergelijkbaar plak), de sorteerveld arg maakt gebruik van de bovenstaande lijst met toegestane entiteiten.

Aliassen worden automatisch genormaliseerd in alle TikTok Shop-tools: aantal verkochte eenheden / eenheden / verkoop / verkocht → aantal verkochte; gmv → omzet; gmv_30d / omzet_30d → omzet_30_dagen; groei / omzetgroei / gmv_groeipercentage → omzetgroei; omzetgroei → omzetgroei; prijs / gemiddelde prijs → gemiddelde eenheidsprijs; beoordeling → winkelbeoordeling; recensies → aantal_productrecensies; aantal volgers → volgers; weergaven → weergaven_in_de_afgelopen_30_dagen; vindt leuk → likes_30_dagen; roas → geschatte_ROAS; duur → videoduur; datum / gepubliceerd → publicatiedatum.

Shopify Ontdek winkels#

track_store(store_url) voegt een winkel/domein toe aan Store Tracker. Het maakt gebruik van dezelfde validatie, abonnementslimiet, winkelresolutie en wachtrij voor het verzamelen van bestsellers als het dashboard.

Aliassen: omzet / maandelijkse_omzet / omzet_30d / 30d_omzet → 30d_rev_geschatte_max; jaaromzet / jaaromzet → omzet_1j; dagelijkse_omzet / omzet_1d → 1d_rev_geschatte_max; verkeer / bezoeken / bezoekers / maandelijks_verkeer → maandelijks_aantal_bezoeken; gemiddelde orderwaarde / gemiddelde_orderwaarde / bestelwaarde → gemiddelde orderwaarde; verkeersgroei_1m → groei_bezoekers_pct_m1; verkeersgroei_3m → groei_bezoekers_pct_m3; omzetverandering / omzetgroei / omzetontwikkeling_winkel_30d → groei_bezoekers_pct_m1 (dezelfde indeling als de live-tabel ‘Explore Shops’ toen de oude sortering op omzetverschil werd afgeschaft).

zoek_shopify_winkels / winkels zoeken filters (allemaal optioneel, tenzij anders vermeld). De namen komen overeen met de namen van de MCP-argumenten:

Gebruik lijst_shopify_winkel_filteropties voordat er op dynamische waarden wordt gefilterd (Shopify-thema's, winkel_apps, product_taxonomie_l1/l2/l3). Zijn rubriek argument accepteert alle, statisch, thema's, apps, product_taxonomie_l1, product_taxonomie_l2, product_taxonomie_l3; doorgeven zoekopdracht om dynamische keuzelijsten te doorzoeken.

Handleiding voor intenties: “Nichewinkels” → categorie of niche = een van de categorieën van Explore Shops. Voor mode/kleding/kledingstukken gebruik je Kleding. Vermijd trefwoord-alleen nichezoekopdrachten. “Top / grootste qua omzet” → sort_by=omzet_1j, sort_order=desc. “Nieuw in de afgelopen N maanden” → aangemaakt_op_basis_van / aangemaakt_tot inclusief JJJJ-MM-DD (beide verplicht).

Gelijkwaardigheid met POST-https://app.winninghunter.com/api/shops/explore: MCP maakt gebruik van dezelfde POST-sleutels aan de serverzijde (zoeken, categorie, sorteersleutel, sorteerrichting, pagina, paginagrootte, inclusief Wlads, …). Argumenttoewijzing: trefwoord→zoeken, sorteren op→sorteersleutel, grootte→paginagrootte. Standaard include_wlads=false → includeWlads=0 (komt overeen met de aanvraag voor de dashboardtabel waarbij de voorbeelden van wlads worden overgeslagen).

zoek_vergelijkbare_winkels_op_afbeelding neemt afbeelding_url (verplicht) plus de dezelfde filters als hierboven, behalve trefwoord (overeenkomst vervangt het zoeken op tekst).

Opmerking: De MCP-tools van TikTok maken ook gebruik van een land argument — daar is het dan: de context van de markt/het land, niet in dezelfde branche als Shopify-verkopers land.

Merkvolger#

track_brand(pagina-id?, url?) voegt een Facebook-/Meta-pagina toe aan Brand Tracker. Voer een pagina-id of een URL naar de Facebook-advertentiebibliotheek die het volgende bevat alle_pagina’s_bekijken; het maakt gebruik van dezelfde limiet en algemene wachtrij als het dashboard.

Aliassen: recent / toegevoegd / nieuwste / nieuwste / datum → toevoegdatum; alfabetisch / alpha / a-z → naam; nieuw / nieuwe advertenties → nieuwe advertenties; trending / momentum → groei.

Actuele onderwerpen#

Aliassen voor sorteren: volume → absoluut_volume; exponentieel → exponent; recent / nieuwste / nieuwste → toevoegdatum; trending → groei. categorie ondersteunt dashboard-slugs (bijv. mode, schoonheid, huidverzorging, fitness, technologie, ai, …) of standaard voor alle categorieën.

mcp_sorteren reactieblok#

Elke zoek- of lijstfunctie die sorteren op (of sorteren/sorteren) voegt een mcp_sorteren bezwaar maken tegen de inhoud van het antwoord:

{
  "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"
  }
}

Als je een onbekende sorteersleutel doorgeeft, mcp_sorting.waarschuwing zegt dat het terugviel op de standaardinstelling — het programma geeft geen foutmelding.

Waarden voor detailgereedschappen#

Gebruik een van deze plak waarden:

• get_tiktok_product: detail, geschiedenis, statistieken, makers, video's
• get_tiktok_shop: detail, geschiedenis, statistieken, producten, video's, makers, strategie
• get_tiktok_creator: detail, geschiedenis, statistieken, winkels, producten, video's
• get_tiktok_video: detail, geschiedenis, statistieken, producten, vergelijkbaar

Twee veelgemaakte fouten#

1. Trending

   • get_tiktok_trending_products is de groei van TikTok Shop-producten
   • Exploding Topics is een apart (zoek_trending_onderwerpen + get_exploding_topic_detail)

2. Acties schrijven

   • MCP ondersteunt track_merk, track_store, save_ad, and Meta ad transcript generation via get_ad_transcript
   • Favorites, presets, TikTok transcripts, and other writes must use REST API

Tekstblok voor AI-instructies#

Kopieer dit en plak het in de instructies voor de agent:

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.

Wil je alle technische details weten?#

Voor de volledige filtersemantiek en het gedrag van eindpunten:

• Filters in TikTok Shop
• Meta-advertentiebibliotheek
• Merken
• Shopify-winkelverkenner
• Trends