/meta-ads-library

name: meta-ads-library
description: Research competitor Facebook and Instagram ads from the Meta Ads Library via the Hyper MCP — search by keyword, pull full ad creative and metadata, enrich with page contact info for lead generation, and surface structured ad-intelligence summaries in chat. Use when the user wants to scrape the Meta Ads Library, spy on competitor ads, monitor new ads in a category, build a lead list from advertisers, or surface creative trends across an industry.
requires_toolkits:
  - meta_ads_library
icon: meta_ads_library
short_description: Search the Meta Ads Library for competitor ads and surface structured ad intelligence.

Meta Ads Library

Guide for searching the Meta Ads Library and producing structured competitor ad intelligence.

The skill's job is to turn raw scraped ads into useful summaries: top advertisers, common CTAs, recurring hooks, recently launched creatives, and (optionally) enriched lead lists. All output is presented inline in chat — there is no database or persistence layer.

Out of scope — defer to other skills

| Request | Send them to | | --- | --- | | Multi-source competitor research (site, social, search rank, etc., not just ads) | [`competitor-intel`](../competitor-intel) | | Generating *new* ad creative based on what you found | [`ad-creative-generation`](../ad-creative-generation) |

Requirements

• **Hyper MCP installed and connected.** [https://app.hyperfx.ai/mcp](https://app.hyperfx.ai/mcp)
• **Meta Ads Library toolkit enabled** at [https://app.hyperfx.ai/apps](https://app.hyperfx.ai/apps) — the Meta Ads Library tools run via Apify under the hood.

If `meta_ad_library_ads_search` is not found, the toolkit to enable is Meta Ads Library (`meta_ads_library`).

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

| Surface | Find a tool | Run it | | --- | --- | --- | | Hyper chat | Call the tool by its name; `search_tools(queries=["<provider> <action>"])` shows its parameters | `<name>(...)` | | MCP client (Claude, Cursor, Codex, ChatGPT) | `search("<what you want to do>")`, then `describe("<name>")` | `call_read("<name>", {...})`, `call_write` or `call_destructive`: the one that `describe` names in `call_with` | | Hyper CLI | `hyperai search "<what you want to do>"`, then `hyperai describe <name>` | `hyperai call <name> --json '{...}'` |

If a tool is not found: in Hyper chat, find its toolkit id with `discover_toolkits` and pass it to `enable_toolkit`. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Tool surface

| Tool | Purpose | | --- | --- | | `meta_ad_library_ads_search` | Search the Meta Ads Library by keyword. Returns compact results (title, body, CTA, link, page name, dates, platforms). Max 40 per call. | | `meta_ad_library_ads_get` | Get full details for a specific ad. Requires both `ad_archive_id` **and** `page_id` — both come from `meta_ad_library_ads_search` results. | | `meta_ad_library_ads_search_enriched` | Search + enrich each result with page contact info (email, phone, website). Slower (multiple API calls per result). Max 20 per call. | | `meta_ad_library_pages_search` | Search Facebook pages by category + location (not by keyword). Useful for building a lead list from a vertical. | | `meta_ad_library_pages_scrape` | Scrape detailed data from specific Facebook page URLs. |

Critical rules

1. **Public-only data.** The Meta Ads Library is public. Don't attempt to bypass any access control or scrape private content. 2. **Count limits differ between tools.** `meta_ad_library_ads_search` allows `count` up to 40. `meta_ad_library_ads_search_enriched` caps at 20 — exceeding this returns an error. 3. **`meta_ad_library_ads_get` needs two IDs.** Both `ad_archive_id` and `page_id` are required. Both are returned in every `meta_ad_library_ads_search` result row — pass them through together. 4. **Enriched search is slow.** It makes a Facebook page scrape per ad and optionally a website scrape. Only use it when contact info matters (lead-gen workflows). For pure ad intelligence, use the regular `meta_ad_library_ads_search`. 5. **Apify-backed tools fail intermittently.** Expect occasional `"fetch failed"` responses. Retry once after a short delay before reporting the source as missing. 6. **Don't over-interpret a single ad.** "Brand X is running a discount" is noise. "5 of the top 10 advertisers in this query are running discounts" is signal. Always aggregate before drawing conclusions.

Workflow

Phase 1 — Define the query

Before running anything, agree on:

1. **The search query** — keyword(s) competitors would target. Examples: `"meal kit delivery"`, `"AI marketing tools"`, `"skincare for sensitive skin"`. 2. **Country** — ISO code (e.g. `"US"`, `"GB"`, `"AU"`). Default to `"ALL"` only if the user explicitly wants global. 3. **Active vs all** — `active_status="active"` is usually what you want. Inactive ads are historical and noisier. 4. **Time window** — `period` accepts `"last24h"`, `"last7d"`, `"last14d"`, `"last30d"`, or `"all_time"`. Match the window to the user's intent (weekly digest → `"last7d"`, trend research → `"last30d"`). 5. **The job** — what is this for?

• **Creative trend report** → use `meta_ad_library_ads_search`, summarize patterns across hooks, CTAs, formats.
• **Top advertiser snapshot** → use `meta_ad_library_ads_search`, group by `page_name`.
• **Lead list** → use `meta_ad_library_ads_search_enriched`, filter for rows with `contact_email` or `contact_website`.

Phase 2 — Pull the ads

meta_ad_library_ads_search(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=40,                # max for this tool
    period="last30d"
)

Each result row includes: `ad_archive_id`, `page_id`, `page_name`, `is_active`, `start_date_formatted`, `end_date_formatted`, `title`, `body`, `cta_text`, `link_url`, `capt