Skip to main content
Glama

Find long-running ads in a category

find_long_running_ads
Read-onlyIdempotent

Samples a category or product type across the query and up to three related angles, returning up to 24 ads (default 12) with captions, hooks, run dates, delivery evidence, strength labels and cautions. For category inspiration; search_ads supports advertiser lookups and paging. One page, no cursor. Ranking uses observed delivery evidence with approximate ordering; matching is broad, and run_duration_days and still_running show each ad’s evidence. No library totals or complete coverage; run time is not proof of sales.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "find_long_running_ads"
  }
}

Input Schema

NameRequiredDescriptionDefault
angleNoExact angle filter from a row’s filters.angle, e.g. social_proof. Absent means no filter.
buyerNoWho pays: business_owners = owners/operators; consumers = end consumers; professionals = business buyers or practitioners; any = no buyer filter. With a buyer filter, exact matches come back in ads and unknown-profile or adjacent business buyers in a separate nearby group (at most 25% of the page); exact_count and nearby_count report each group.
queryYesCategory, product type or market in plain words, e.g. magnesium supplements. Up to 200 characters.
formatNostatic = image ads; video = video ads. Absent means both.
audienceNoWho it targets, e.g. restaurant owners or main street business owners. Ranks stored audience, buyer label, industry and ad-copy evidence. When supplied, industry_slug is a hard constraint; inferred categories can broaden.
brand_idNoOptional brand id from list_brands. Marks rows from that brand's competitors with your_rival; narrows nothing unless tracked_rivals_only is true.
hook_typeNoExact hook filter from a row’s hook_type_filter, e.g. urgency. Absent means no filter.
max_resultsNoAds per page, 1 to 24 (default 12).
min_run_daysNoOnly ads observed running for at least this many days (0 to 36500).
competitor_idNoRestricts results to one saved competitor: a competitor id from list_competitors.
industry_slugNoIndustry slug from a row’s filters.industry_slug, e.g. fitness-software. Parent categories include their child categories; a leaf category selects that exact category. Absence permits inferred related categories.
search_anglesNoUp to three related products, offers or advertiser names to sample alongside the query. Not format or hook labels.
has_spoken_hookNotrue: only ads with an extracted spoken (verbal) hook. false: only ads without one. Absent means all ads.
response_formatNoOutput format: text (default) is readable text with image previews and links; json returns the structured rows. table is refused by Ad Library tools.
facebook_page_idNoRestricts results to one advertiser: a facebook_page_id from search_advertisers.
tracked_rivals_onlyNotrue restricts results to ads from the brand's tracked competitors; needs brand_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already cover readOnly, idempotent and non-destructive, but the description goes well beyond them: one page with no cursor, approximate ordering from observed delivery evidence, broad matching, no library totals or complete coverage, and the caveat that run time is not proof of sales. Those are exactly the expectations an agent needs to avoid over-claiming results.

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?

It is front-loaded with the action and payload before the caveats, and almost every clause carries information. The middle sentences are dense and slightly run-on (ranking, matching, evidence caveats compressed together), which costs a little readability but nothing is padding.

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?

With 16 parameters and no output schema, the description does the heavy lifting: it summarizes the returned fields, explains paging limits, and warns about coverage and ranking reliability. For a sampling tool of this complexity, an agent has what it needs to call it and to interpret the result honestly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already carries per-parameter meaning and the baseline is 3. The description adds useful framing — up to three angles alongside the query, 24 max/default 12 — and names output fields run_duration_days and still_running, but it does not clarify the 16 parameters' interactions, so it stays at baseline.

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?

The description opens with a specific verb and resource ('Samples a category or product type'), states the scope (query plus up to three related angles), and names what comes back (up to 24 ads with captions, hooks, run dates, delivery evidence, strength labels, cautions). It also explicitly separates itself from search_ads, so an agent can pick between them without opening a schema.

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

Usage Guidelines4/5

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

'For category inspiration; search_ads supports advertiser lookups and paging' gives a real use case and routes the agent to the sibling for the two main alternatives. What is missing is an explicit statement of when not to use this tool (for example, when a specific advertiser or exhaustive list is the goal) — that exclusion is only implied by the sibling reference.

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.