search_winners
Find winning e-commerce ads (Facebook / Instagram, Meta Ad Library) and show what's working. Use it FIRST when the user asks for winning ads, what's working or scaling in a niche or a country, the best hooks, the longest-running ads, or ads that reach a given age and gender. Examples: 'winning ads for weight loss in France', 'which hooks work for menopause in Germany' (has_script=true: each result carries its verbatim hook), 'longest-running video ads in Spain for bloating', 'ads launched last month with 1M+ EU reach' (started_after, min_eu_reach), 'ads that mostly reach women 45-54 in Germany' (age, gender, min_segment_share). Winner = live 21+ days (change with min_days_live). Each result: Ad Library link, shop link, format, days live, still running or stopped, versions, EU reach (Meta's total, with its read date), the country's or segment's share of Meta's breakdown, and the verbatim hook when the script is transcribed and fully in English or translated (sections_status 'served'; 'translation_pending' = no hook yet). Then call get_ad on the best ones for the full script. For medians or typical values across many ads, use get_weights instead. Values for niche, country and format: call filters (free). Coverage: e-commerce ads from Meta's Ad Library delivered in the EU and UK, read daily, with Meta's EU reach. Not covered: spend and impressions (Meta doesn't publish them for commercial ads), TikTok/Google ads. Creative types (UGC, VSL, demo…) and hook types are AI labels on part of the ads, served with their measured accuracy. Costs 5 credits (0 if nothing matches).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_winners"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | an age band of Meta's breakdown (with gender for a segment) | |
| sort | No | default: eu_reach when a country, age or gender is given, else days_live | |
| limit | No | default 10 | |
| niche | No | e.g. 'weight loss', 'menopause', 'bloating', 'cellulite', 'gut health' (exact list: filters). It is the niche of the search that found the brand. | |
| active | No | true = still running at the last read, false = stopped | |
| format | No | Meta's display format: VIDEO, IMAGE, DCO (dynamic creative), DPA, CAROUSEL. For UGC, VSL, demo… use creative_type (an AI label with its measured accuracy, on part of the ads), not format. | |
| gender | No | ||
| offset | No | offset + limit at most 100: the first 100 results of a query | |
| region | No | EU = ads with Meta's EU data; US data opens after its audit | |
| country | No | 2-letter code where the ad reached people, e.g. FR, DE, IT, ES, BE | |
| hook_type | No | AI label of the hook: in validation, not served for now (the verbatim hook text is in every result) | |
| has_script | No | true = only ads whose script is transcribed and cut into sections (use it for hooks and scripts) | |
| min_eu_reach | No | people reached in the EU (Meta's total) | |
| min_versions | No | Meta's count of ads sharing the creative | |
| creative_type | No | AI label of the creative: in validation, not served for now (Meta's format is in `format`) | |
| max_days_live | No | ||
| min_days_live | No | default 21 (the winner rule); 0 = all ads | |
| started_after | No | launched on or after, e.g. 2026-10-01 | |
| started_before | No | ||
| min_country_share | No | needs country: 0.5 = the country holds at least half of the ad's breakdown (its main country) | |
| min_segment_share | No | needs age or gender: minimum share of the ad's breakdown in that segment, e.g. 0.3 |