Skip to main content
Glama
ScrapeAdLibrary

ScrapeAdLibrary

Official

search_ads

Search the public Meta Ad Library for ads by keyword or advertiser across Facebook, Instagram, Messenger, Threads and Audience Network, with filters for country, status, dates and media type.

Instructions

Search the public Meta Ad Library (Facebook, Instagram, Messenger, Audience Network, Threads) for ads by keyword and/or advertiser.

Cost: 1 credit per 10 ads returned, rounded up (limit=10 → 1 credit, limit=50 → 5); an empty result or an error costs 0. Keep limit small unless the user needs more.

Args: query: Keyword or phrase (1-100 chars). Required unless page_id is given. page_id: Restrict to one advertiser (numeric page ID, see search_pages). country: ISO-3166 alpha-2 country where the ads ran (e.g. 'IT', 'US') or 'ALL'. status: 'active' (default), 'inactive' or 'all'. ad_type: 'all' or 'political' (political & issue ads, with spend/impressions). media_type: 'all', 'image', 'video', 'meme' or 'none'. platforms: Subset of facebook, instagram, messenger, audience_network, threads. languages: ISO-639-1 language codes of the ad text (e.g. ['it', 'en']). active_from: YYYY-MM-DD; ads running at some point from this date. active_to: YYYY-MM-DD; ads running at some point up to this date. match: 'any' (all words, default) or 'exact' (exact phrase). sort: 'relevance' (default) or 'impressions' (most impressions first). limit: Ads per page, 1-50 (default 10). cursor: next_cursor from a previous call, to get the next page (same filters).

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

Input Schema

NameRequiredDescriptionDefault
sortNorelevance
limitNo
matchNoany
queryNo
cursorNo
statusNoactive
ad_typeNoall
countryNoALL
page_idNo
active_toNo
languagesNo
platformsNo
media_typeNoall
active_fromNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden, and it discloses a non-obvious cost model (1 credit per 10 ads, rounded up, empty result or error costs 0) and pagination behavior via cursor reuse with the same filters. It leaves out any statement about read-only nature, authentication, or result caps, so it is strong but not exhaustive for a no-annotation tool.

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?

Purpose and cost model are front-loaded, then a compact one-line-per-parameter list that is dense but justified given zero schema descriptions. Some phrasing, such as "match: 'any' (all words, default)", reads awkwardly and requires a second pass to parse.

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 14-parameter search tool with no annotations, the definition covers what to search, how to filter, how to paginate, and what it costs; return values are handled by the existing output schema, so nothing needed for a correct call is missing.

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

Parameters5/5

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

Schema coverage is 0% with 14 parameters, so the description must carry all semantics, and its Args block defines every one: ISO-3166 alpha-2 country codes, ISO-639-1 language lists, date formats, and the counter-intuitive default that match='any' actually means all words. It even clarifies that cursor is the next_cursor from a previous call and must reuse the same filters.

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 ('Search the public Meta Ad Library ... for ads') plus the two-axis scope (keyword and/or advertiser) and the covered surfaces (Facebook, Instagram, Messenger, Audience Network, Threads). It also points to the sibling search_pages for page ID resolution, so an agent can distinguish it from get_page_ads/get_ad without opening schemas.

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?

Gives a clear selection rule ('query ... required unless page_id is given') and routes ID lookup to search_pages, plus practical guidance to keep limit small. It does not explicitly contrast with get_page_ads or get_ad, so alternatives are only partially covered.

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

Deploy Server

Other Tools