Adsap

Search Meta Ad Library

adsap_search_ad_library

Search Meta's public Ad Library for ads (competitor research / ad transparency). Find the ads a competitor page is currently running, or ads matching a keyword, in given countries. Returns each ad's page, creative text, platforms, languages, delivery dates, days_running, eu_total_reach (people reached in the EU: with days_running, the public signal of which ads an advertiser is scaling), a public Ad Library permalink, and a pagination cursor. Filters: media_type (STATIC for image ads only, VIDEO for video only), exact-phrase matching, platform, language, delivery dates. A keyword search also returns data.pages, the distinct advertisers found, so you can re-run on one page_id. Read-only public data (not your own account's ads — use adsap_list_campaigns/adsap_get_insights for that). COVERAGE CEILING (Meta's rule, not ADSAP's): the public Ad Library API returns ordinary commercial ads ONLY where they reached the EU or UK. Ads that never reached the EU/UK are returned only when they are political or social-issue ads. So a US-only (or any non-EU/UK) commercial search returns zero results however it is phrased, and that empty result is NOT evidence the advertiser is inactive. Never promise non-EU/UK competitor research from this tool; point the user at the public Ad Library website for those markets.

Input Schema

TableJSON Schema

Name	Required	Description
`after`	No	Pagination cursor from a previous response's meta.paging_after, to fetch the next page. Re-send the SAME filters with it (a cursor from a media_type STATIC search only works with media_type STATIC).
`limit`	No	Max ads to return per page. Default 25, max 50 (Meta's cap). Meta can return fewer than asked even when more exist: trust meta.has_next, not the count.
`ad_type`	No	Category of ads. Default ALL (all commercial ads). Use POLITICAL_AND_ISSUE_ADS etc. for the special transparency categories. CREDIT_ADS is the old name of FINANCIAL_PRODUCTS_AND_SERVICES_ADS and is treated as the same thing.
`page_ids`	No	Facebook Page IDs to restrict the search to (returns only ads run by these pages; max 10, Meta's limit). Provide this and/or search_terms. No page ID yet? Search the brand name with search_terms first and read data.pages.
`countries`	Yes	ISO-2 country codes the ads reached, e.g. ["FR"], ["GB","DE"]. Required by Meta (ad_reached_countries). For ordinary commercial ads, only EU/UK countries can return results (see the coverage ceiling in the tool description); a non-EU/UK code returns only the ads that ALSO reached the EU/UK (usually none) unless ad_type is POLITICAL_AND_ISSUE_ADS.
`languages`	No	Only ads written in these languages, as ISO 639-1 codes, e.g. ["fr"], ["en","de"]. Default: every language.
`media_type`	No	Filter by the ad's media. STATIC = every still-image ad (use this whenever the user asks for static / image / non-video ads), VIDEO = video ads only. Default ALL. An unfiltered result carries NO per-ad media marker, so this filter is the ONLY way to separate static from video: never return an unfiltered list and call it static. Finer control: Meta splits still images into IMAGE (a plain picture) and MEME (a picture with text laid over it, which is most designed static ads); STATIC is both together, and each returned ad says which in its media_type. NONE = text-only ads. A rare ad with several versions can hold both an image and a video and then shows under both STATIC and VIDEO.
`search_type`	No	How search_terms is matched. KEYWORD_UNORDERED (default) matches the words in any order, which is broad. KEYWORD_EXACT_PHRASE matches the exact phrase only: use it for a brand or product name to cut unrelated ads.
`search_terms`	No	Keyword/phrase to match in ad creative text (max 100 characters, Meta's limit). Provide this and/or page_ids. Matching is broad by default: see search_type, and use data.pages in the result to find the advertiser you meant.
`ad_account_id`	Yes	Your ad account ID (act_xxx). Required — Meta only serves Ad Library results to callers with an active ad account; also anchors the workspace ownership check + Meta budget.
`ad_active_status`	No	Filter by whether the ad is currently running. Default ACTIVE (what a competitor is running now). Use ALL to include stopped ads.
`include_targeting`	No	Also return each ad's declared targeting (age range, gender, locations). Default false: it makes every row heavier, so ask for it only when the user wants to know WHO an advertiser targets.
`publisher_platforms`	No	Only ads that ran on these Meta platforms, e.g. ["INSTAGRAM"]. An ad that ran on Instagram AND elsewhere still matches: this means "appeared on", not "appeared only on". Default: every platform.
`ad_delivery_date_max`	No	Only ads delivered on or before this date (YYYY-MM-DD).
`ad_delivery_date_min`	No	Only ads delivered on or after this date (YYYY-MM-DD). Use for 'ads launched since ...'.

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedOct 6, 2026

addedInput schema / properties / ad_delivery_date_max

Added value: +{
+  "description": "Only ads delivered on or before this date (YYYY-MM-DD).",
+  "type": "string"
+}

addedInput schema / properties / ad_delivery_date_min

Added value: +{
+  "description": "Only ads delivered on or after this date (YYYY-MM-DD). Use for 'ads launched since ...'.",
+  "type": "string"
+}

changedInput schema / properties / ad_type / description

Previous value: -"Category of ads. Default ALL (all commercial ads). Use POLITICAL_AND_ISSUE_ADS etc. for the special transparency categories."New value: +"Category of ads. Default ALL (all commercial ads). Use POLITICAL_AND_ISSUE_ADS etc. for the special transparency categories. CREDIT_ADS is the old name of FINANCIAL_PRODUCTS_AND_SERVICES_ADS and is treated as the same thing."

changedInput schema / properties / ad_type / enum

Previous value: -[
-  "ALL",
-  "POLITICAL_AND_ISSUE_ADS",
-  "HOUSING_ADS",
-  "EMPLOYMENT_ADS",
-  "CREDIT_ADS"
-]New value: +[
+  "ALL",
+  "POLITICAL_AND_ISSUE_ADS",
+  "HOUSING_ADS",
+  "EMPLOYMENT_ADS",
+  "FINANCIAL_PRODUCTS_AND_SERVICES_ADS",
+  "CREDIT_ADS"
+]

changedInput schema / properties / after / description

Previous value: -"Pagination cursor from a previous response's meta.paging_after, to fetch the next page."New value: +"Pagination cursor from a previous response's meta.paging_after, to fetch the next page. Re-send the SAME filters with it (a cursor from a media_type STATIC search only works with media_type STATIC)."

changedInput schema / properties / countries / description

Previous value: -"ISO-2 country codes the ads reached, e.g. [\"FR\"], [\"GB\",\"DE\"]. Required by Meta (ad_reached_countries). For ordinary commercial ads, only EU/UK countries can return results (see the coverage ceiling in the tool description); non-EU/UK codes return zero unless ad_type is POLITICAL_AND_ISSUE_ADS."New value: +"ISO-2 country codes the ads reached, e.g. [\"FR\"], [\"GB\",\"DE\"]. Required by Meta (ad_reached_countries). For ordinary commercial ads, only EU/UK countries can return results (see the coverage ceiling in the tool description); a non-EU/UK code returns only the ads that ALSO reached the EU/UK (usually none) unless ad_type is POLITICAL_AND_ISSUE_ADS."

addedInput schema / properties / include_targeting

Added value: +{
+  "description": "Also return each ad's declared targeting (age range, gender, locations). Default false: it makes every row heavier, so ask for it only when the user wants to know WHO an advertiser targets.",
+  "type": "boolean"
+}

addedInput schema / properties / languages

Added value: +{
+  "description": "Only ads written in these languages, as ISO 639-1 codes, e.g. [\"fr\"], [\"en\",\"de\"]. Default: every language.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / limit / description

Previous value: -"Max ads to return per page. Default 25, max 50 (Meta's cap)."New value: +"Max ads to return per page. Default 25, max 50 (Meta's cap). Meta can return fewer than asked even when more exist: trust meta.has_next, not the count."

addedInput schema / properties / media_type

Added value: +{
+  "description": "Filter by the ad's media. STATIC = every still-image ad (use this whenever the user asks for static / image / non-video ads), VIDEO = video ads only. Default ALL. An unfiltered result carries NO per-ad media marker, so this filter is the ONLY way to separate static from video: never return an unfiltered list and call it static. Finer control: Meta splits still images into IMAGE (a plain picture) and MEME (a picture with text laid over it, which is most designed static ads); STATIC is both together, and each returned ad says which in its media_type. NONE = text-only ads. A rare ad with several versions can hold both an image and a video and then shows under both STATIC and VIDEO.",
+  "enum": [
+    "ALL",
+    "STATIC",
+    "IMAGE",
+    "MEME",
+    "VIDEO",
+    "NONE"
+  ],
+  "type": "string"
+}

changedInput schema / properties / page_ids / description

Previous value: -"Facebook Page IDs to restrict the search to (returns only ads run by these pages). Provide this and/or search_terms."New value: +"Facebook Page IDs to restrict the search to (returns only ads run by these pages; max 10, Meta's limit). Provide this and/or search_terms. No page ID yet? Search the brand name with search_terms first and read data.pages."

addedInput schema / properties / publisher_platforms

Added value: +{
+  "description": "Only ads that ran on these Meta platforms, e.g. [\"INSTAGRAM\"]. An ad that ran on Instagram AND elsewhere still matches: this means \"appeared on\", not \"appeared only on\". Default: every platform.",
+  "items": {
+    "enum": [
+      "FACEBOOK",
+      "INSTAGRAM",
+      "AUDIENCE_NETWORK",
+      "MESSENGER",
+      "WHATSAPP",
+      "OCULUS",
+      "THREADS",
+      "STREAMING_SERVICES"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / search_terms / description

Previous value: -"Keyword/phrase to match in ad creative text. Provide this and/or page_ids."New value: +"Keyword/phrase to match in ad creative text (max 100 characters, Meta's limit). Provide this and/or page_ids. Matching is broad by default: see search_type, and use data.pages in the result to find the advertiser you meant."

addedInput schema / properties / search_type

Added value: +{
+  "description": "How search_terms is matched. KEYWORD_UNORDERED (default) matches the words in any order, which is broad. KEYWORD_EXACT_PHRASE matches the exact phrase only: use it for a brand or product name to cut unrelated ads.",
+  "enum": [
+    "KEYWORD_UNORDERED",
+    "KEYWORD_EXACT_PHRASE"
+  ],
+  "type": "string"
+}

First observedSep 19, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations present the description carries the full behavioral burden, and it does: it declares the data is read-only public data, explains the pagination cursor must reuse identical filters, and — critically — discloses Meta's EU/UK coverage ceiling and warns that an empty result is NOT evidence the advertiser is inactive. It also interprets eu_total_reach/days_running as the scaling signal, which is behavioral context no structured field provides.

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, then filters, then the coverage-ceiling caveat, so the reader hits what matters first. It is long and dense, but the length is warranted by a 15-parameter tool with a genuinely counter-intuitive emptiness rule; only the parenthetical asides verge on excess.

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?

There is no output schema, so the description must cover returns — and it enumerates page, creative text, platforms, languages, delivery dates, days_running, eu_total_reach, permalink, pagination cursor, and data.pages. Combined with the coverage-ceiling warning, the read-only framing, and the sibling routing, nothing an agent needs to call this correctly 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 description coverage is 100%, so the baseline is 3, but the description adds meaning on top: it frames media_type as the ONLY way to separate static from video ('never return an unfiltered list and call it static'), characterizes exact-phrase matching as the way to cut unrelated ads, and notes that a keyword search populates data.pages that can be fed back as page_ids.

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 Meta's public Ad Library for ads') and immediately scopes it as competitor research / ad transparency. It explicitly excludes the caller's own account ('not your own account's ads — use adsap_list_campaigns/adsap_get_insights for that'), so an agent can distinguish it from the sibling list/insights tools 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 explicit when-to-use ('find the ads a competitor page is currently running, or ads matching a keyword'), names the alternatives for own-account data, and adds a hard when-not rule via the COVERAGE CEILING: non-EU/UK commercial searches return zero by design, and the agent is told never to promise such research and to route the user to the public website instead.

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

All Adsap tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?