Skip to main content
Glama

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

NameRequiredDescriptionDefault
ageNoan age band of Meta's breakdown (with gender for a segment)
sortNodefault: eu_reach when a country, age or gender is given, else days_live
limitNodefault 10
nicheNoe.g. 'weight loss', 'menopause', 'bloating', 'cellulite', 'gut health' (exact list: filters). It is the niche of the search that found the brand.
activeNotrue = still running at the last read, false = stopped
formatNoMeta'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.
genderNo
offsetNooffset + limit at most 100: the first 100 results of a query
regionNoEU = ads with Meta's EU data; US data opens after its audit
countryNo2-letter code where the ad reached people, e.g. FR, DE, IT, ES, BE
hook_typeNoAI label of the hook: in validation, not served for now (the verbatim hook text is in every result)
has_scriptNotrue = only ads whose script is transcribed and cut into sections (use it for hooks and scripts)
min_eu_reachNopeople reached in the EU (Meta's total)
min_versionsNoMeta's count of ads sharing the creative
creative_typeNoAI label of the creative: in validation, not served for now (Meta's format is in `format`)
max_days_liveNo
min_days_liveNodefault 21 (the winner rule); 0 = all ads
started_afterNolaunched on or after, e.g. 2026-10-01
started_beforeNo
min_country_shareNoneeds country: 0.5 = the country holds at least half of the ad's breakdown (its main country)
min_segment_shareNoneeds age or gender: minimum share of the ad's breakdown in that segment, e.g. 0.3

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"default 20"New value: +"default 10"
    • changedInput schema / properties / limit / maximum
      Previous value: -50New value: +20
    • addedInput schema / properties / offset / description
      Added value: +"offset + limit at most 100: the first 100 results of a query"
    • changedInput schema / properties / offset / maximum
      Previous value: -1000New value: +90
  2. Changed1 schema field changed
    • changedInput schema / properties / creative_type / description
      Previous value: -"AI label of the creative: UGC, VSL, Demo, Product photo… (see filters; served with its measured accuracy; not Meta's format)"New value: +"AI label of the creative: in validation, not served for now (Meta's format is in `format`)"
  3. Changed1 schema field changed
    • changedInput schema / properties / hook_type / description
      Previous value: -"AI label of the hook (see filters for values and accuracy)"New value: +"AI label of the hook: in validation, not served for now (the verbatim hook text is in every result)"
  4. Changed3 schema fields changed
    • addedInput schema / properties / creative_type
      Added value: +{
      +  "description": "AI label of the creative: UGC, VSL, Demo, Product photo… (see filters; served with its measured accuracy; not Meta's format)",
      +  "type": "string"
      +}
    • changedInput schema / properties / format / description
      Previous value: -"Meta's display format: VIDEO, IMAGE, DCO (dynamic creative), DPA, CAROUSEL. Creative types such as UGC are not labelled: for 'UGC' ask for VIDEO and read the scripts."New value: +"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."
    • changedInput schema / properties / hook_type / description
      Previous value: -"not measured yet: leave it out"New value: +"AI label of the hook (see filters for values and accuracy)"
  5. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so: it discloses cost (5 credits, 0 on no match), data freshness (read daily), coverage limits (EU/UK e-commerce only, no spend/impressions, no TikTok/Google), and the meaning of sections_status values. It also flags that creative_type and hook_type are AI labels with measured accuracy rather than hard facts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the 'use it first' directive, then examples, then coverage limits — a sensible order. It is dense and parenthetical-heavy, with some repeated explanation of hook/label caveats, but nearly every sentence carries call-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter, zero-annotation tool with no output schema, the description covers the missing pieces: the default winner threshold, cost model, data scope and freshness, and an enumeration of returned fields per result. Nothing an agent needs to invoke or interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 86%, so the baseline is 3, but the description adds real meaning by tying parameters to outcomes ('started_after, min_eu_reach', 'age, gender, min_segment_share') and explaining has_script=true yields the verbatim hook. It stops short of documenting booleans or the enum behavior of sort beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find winning e-commerce ads' from the Meta Ad Library) and operationalizes the key term by defining a winner as 'live 21+ days (change with min_days_live)'. An agent can distinguish this from get_weights or get_ad without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('Use it FIRST when the user asks for winning ads, what's working or scaling...') plus concrete query examples that map natural-language asks to parameters. It also names the alternatives and their conditions: get_ad for full scripts, get_weights for medians, filters for valid niche/country/format values.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources