Search Meta Ad Library by Keyword
search_meta_ads_by_keywordUse this when you want to discover ads by keyword or topic without knowing a specific brand, OR to find partnership/influencer ads a brand is running via creators (get_meta_ads only returns ads from the brand's own page). Searches the full Meta Ad Library with optional country, status, media type, and date filters. SHOWING THE ADS — REQUIRED: don't just summarise in text — you MUST call show_ad_carousel at least once this turn so the user SEES the creatives as visual proof, not only reads about them. Interleave it WITH your analysis: each time you make a point about specific ads, call show_ad_carousel right after that sentence with only the ads that evidence THAT point (pass each as {ad_id, page_id} copied from this tool's output; the server fills in copy/media/cards). Make as many carousels as you have distinct points, strictly point → its carousel → next point → its carousel; NEVER stack carousels back-to-back or dump all points as a list after the carousels. Be generous: across your carousels, show MOST of the ads this tool returned (up to 20 per carousel) — skip only ads that are irrelevant or near-duplicates. Never render just 2-3 ads when a dozen were found; if discussed points don't cover all the ads, close with a broader carousel of the rest. Don't finish a turn that discusses specific ads without having rendered at least one. You may mix Meta {ad_id, page_id}, Google {ad_url}, LinkedIn {linkedin_id}, and TikTok {tiktok_id} refs in a single carousel when a point spans platforms. The only time to skip it entirely is when this tool returned zero ads.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| trim | No | True (default) returns trimmed ad fields. | |
| limit | No | Max ads to return (default 30 = one page at 1 credit; at most 10 pages). The response cursor fetches the next page. | |
| query | Yes | Keyword or phrase, e.g. "running shoes". | |
| cursor | No | Continuation token from a previous response. Present when more ads exist beyond what was scanned. | |
| status | No | "ALL", "ACTIVE" (default) or "INACTIVE". | |
| ad_type | No | "all" (default) or "political_and_issue_ads". | |
| context | No | One plain sentence, 8-20 words, starting with a verb, stating what the user is trying to accomplish in this conversation. Name the brand, competitor, industry, or topic involved. Reuse the exact same sentence on every tool call in this conversation. Never include people's names, emails, phone numbers, credentials, or internal company details. Never describe this tool or why it was chosen. Example: 'Compare Notion and Coda Meta ads to find hooks for a productivity app launch.' | |
| country | No | Two-letter country code. Default: all countries; set it when the user names a market. | |
| sort_by | No | "relevancy_monthly_grouped" (default, stays on-topic) or "total_impressions" (largest advertisers first, looser matches). | |
| end_date | No | Filter by impressions end date, YYYY-MM-DD. | |
| media_type | No | "all" (default), "image" (static creatives, including image carousels) or "video" (video only). | |
| start_date | No | Filter by impressions start date, YYYY-MM-DD. | |
| search_type | No | "keyword_unordered" (default) or "keyword_exact_phrase", better for multi-word product names. | |
| conversation_id | No | Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| _mcp_instructions | No | Server-issued metadata for this conversation. |