analyze_ad_image
ChatGPTUse this when you want to understand the visual elements in ad images. Extracts text, colors, people, brand elements, and composition. Works with media_url values from get_meta_ads, get_google_ads, and TikTok's cover URL. TikTok cover URLs expire — prefer passing a fresh cover returned by get_tiktok_ad_details. Use for comprehensive ad analysis. Follow up with get_competitive_brief to synthesize patterns across analyzed ads.
analyze_ad_video
ChatGPTUse this when you want to analyze video ad content or get a transcript of a video ad - the response includes a timestamped Full Transcript section (verbatim voiceover/dialogue; quote it directly when the user asks for a transcript), plus visual storytelling, audio elements, pacing, scene transitions, and brand messaging using AI video understanding. PREFER passing ad_archive_id + page_id (Meta) or tiktok_id over media_url — signed CDN URLs (fbcdn, tiktokcdn, byteoversea) expire within minutes; the server fetches a fresh URL when you pass stable IDs. Param precedence: tiktok_id > ad_archive_id + page_id > media_url (mutually exclusive branches). Follow up with get_competitive_brief to synthesize patterns across analyzed ads.
get_competitive_brief
ChatGPTUse this when comparing brands, summarizing ad analysis, identifying winners, finding whitespace, surfacing patterns, or producing takeaways/recommendations from analyzed ads across one or more brands. Pass factual metadata per ad (id, impressions, start_date, and optionally format and hook_type). Omit hook_type/format if not derived from prior analysis — do not guess. Returns computed signals (hook/format mix, winner concentration, whitespace, cross-brand overlap, recency, own-brand delta) plus a scenario-sized brief structure with selected winners.
get_credit_balance
ChatGPTCheck the user's Proxy credit balance and plan. Use when the user asks about credits, limits, their plan, hitting a wall, or changing plans. Returns remaining daily credits, reset time, and where to find plan information.
get_google_ad_details
ChatGPTUse this when you have a Google ad URL and want full creative details — variations, headlines, descriptions, regional targeting, and impression data. SHOWING THE ADS — once you have the creative details, you MUST call show_ad_carousel at least once this turn so the user SEES the ads as visual proof, not only reads about them. Pass each Google ad as {ad_url} copied from this tool's output (the server fills in the creative, copy and media from cache). Interleave carousels WITH your analysis — one per point you make, each showing the ads that evidence THAT point. Structure strictly as 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 irrelevant or near-duplicate ads; never render just 2-3 when a dozen were found. If discussed points don't cover all the ads, close with a broader carousel of the rest. 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. Skip it only when there were zero ads.
get_google_ads
ChatGPTUse this to retrieve all active ads from a brand on Google — Search, Display, YouTube, and other networks. Requires advertiser ID or domain from get_google_platform_id. Returns creatives with dates and URLs for competitive analysis. SHOWING THE ADS — once you have the creative details, you MUST call show_ad_carousel at least once this turn so the user SEES the ads as visual proof, not only reads about them. Pass each Google ad as {ad_url} copied from this tool's output (the server fills in the creative, copy and media from cache). Interleave carousels WITH your analysis — one per point you make, each showing the ads that evidence THAT point. Structure strictly as 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 irrelevant or near-duplicate ads; never render just 2-3 when a dozen were found. If discussed points don't cover all the ads, close with a broader carousel of the rest. 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. Skip it only when there were zero ads.
get_google_platform_id
ChatGPTUse this when researching a brand's Google advertising on Search, Display, or YouTube networks. Looks up their advertiser ID and domain in the Google Ads Transparency Center — first step before get_google_ads. brand_name is matched literally: pass the bare brand name ("Purina") OR the bare domain ("purina.com.mx") — never both, and never a country/city ("Purina México" returns nothing). Results span all countries; pick the advertiser whose region matches the user's market.
get_linkedin_ad_details
ChatGPTUse this when you have a LinkedIn ad ID and want full targeting, impression breakdown by country, and creative details.
get_meta_ads
ChatGPTUse this when you have a Meta Platform ID and want to see what ads a brand is currently running. Returns ad content, dates, and targeting info; set include_reach=true for reach and age/gender/country delivery demographics. ALWAYS pass platform_ids as a list when researching multiple brands — e.g. platform_ids=['123','456','789'] — never call this tool multiple times in parallel for different IDs (parallel calls are rate-limited server-side and will fail). Look up media_url in the media_urls dict by ad_id before calling analyze_ad_image/analyze_ad_video. If may_be_inactive: true, the page likely paused advertising — try other candidate IDs. Note: headline may be null on video ads; use body + media_type instead. Set min_duration_days: 7 to return only ads active for 7+ days. Set active_only: true to return only currently running ads. Set status='inactive' to see retired creatives. Optionally sort with sort_by='total_impressions' (highest-spend first) or 'relevancy_monthly_grouped'. If comparing multiple brands or surfacing patterns across ads, follow up with get_competitive_brief. 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.
get_meta_platform_id
ChatGPTUse this when you need to find a brand's Meta Platform ID. Returns top 3 candidates sorted by verified status and followers. For ambiguous names, try each candidate with get_meta_ads — stop at the first that returns ads.
get_page_starter
ChatGPTGet the setup for a shareable page (Claude artifact or ChatGPT Site) that reads live ads through Proxy: how to connect, what a page can and cannot do, and ready-made snippets. Use when the user wants to share ad results with a client or team as a page. Free, no credits.
get_tiktok_ad_details
ChatGPTUse this when you have a TikTok ad ID (from search_tiktok_ads) or a library.tiktok.com detail URL and want full creative details: landing page, country targeting, first/last shown dates, and engagement data where available. Accepts a single id/URL string or a list for batch lookup. landing_page is the best brand identity signal — brand_name is often absent. SHOWING THE ADS — you MUST call show_ad_carousel at least once this turn so the user SEES the TikTok creatives as visual proof, not only reads about them. Pass each TikTok ad as {tiktok_id} copied from this tool's output (the server fills creative, cover and body from cache). Interleave carousels WITH your analysis — one per point you make, each showing the ads that evidence THAT point. Structure strictly as 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 irrelevant or near-duplicate ads; never render just 2-3 when a dozen were found. If discussed points don't cover all the ads, close with a broader carousel of the rest. 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. Skip it only when there were zero ads.
search_competitors
ChatGPTUse this when you want to find competitors for a company, or when you've just pulled ads for a brand and want to see how their competitors are advertising. Pass a single query (company name, domain like "lidl.de", or market description) OR use the individual company_name/domain/description params. Returns names and domains ready to pass into get_meta_platform_id, get_google_platform_id, search_linkedin_ads, or search_tiktok_ads. After pulling competitor ads, follow up with get_competitive_brief to surface patterns and recommendations.
search_linkedin_ads
ChatGPTUse this when you need to find LinkedIn ads by company name, keyword, or LinkedIn company ID, with optional country and date filters.
search_meta_ads_by_keyword
ChatGPTUse 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.
search_tiktok_ads
ChatGPTSearch TikTok's public ads library (EU DSA) by advertiser name. Covers EU-delivered ads only, but includes global brands advertising in the EU. advertiser_name (query and brand_name also accepted) is the name the advertiser registered with TikTok — often the parent or legal company name, not the consumer brand ('Anysphere' not 'Cursor'). It is EXACT-MATCH and CASE-SENSITIVE — 'anysphere' or 'Cursor' returns nothing. On zero results, retry with different capitalization, the parent/legal company name, or find it via library.tiktok.com. Results include first/last shown dates — an ad last shown recently is likely still running. No engagement metrics at search level; use get_tiktok_ad_details for landing page and targeting. SHOWING THE ADS — you MUST call show_ad_carousel at least once this turn so the user SEES the TikTok creatives as visual proof, not only reads about them. Pass each TikTok ad as {tiktok_id} copied from this tool's output (the server fills creative, cover and body from cache). Interleave carousels WITH your analysis — one per point you make, each showing the ads that evidence THAT point. Structure strictly as 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 irrelevant or near-duplicate ads; never render just 2-3 when a dozen were found. If discussed points don't cover all the ads, close with a broader carousel of the rest. 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. Skip it only when there were zero ads.
show_ad_carousel
ChatGPTRender a visual ad carousel widget inline (resource: ui://carousel-mcp-v4). Use this AFTER get_meta_ads, search_meta_ads_by_keyword, get_google_ad_details, search_linkedin_ads, or search_tiktok_ads to show selected ads. Works across ALL FOUR platforms (Meta, Google, LinkedIn, TikTok) and you may mix them in one carousel. Model leads in text — call this when the user benefits from visual evidence of the ads referenced. Call it multiple times in one response, once per point you make — not one carousel for all ads. Pass only the ads that evidence one point: a single creative for one claim, a handful for a pattern. The carousel UI holds 20 ads max — a hard safety cap, not a target; split overflow across another call. Per ad, pass ONLY the identifier ref copied from the prior tool's text output: Meta ads as {ad_id, page_id} (ad_id required, page_id recommended); Google ads as {ad_url}; LinkedIn ads as {linkedin_id}; TikTok ads as {tiktok_id}. Google ads MUST have gone through get_google_ad_details first (it warms the creative cache) — otherwise this call spends credits refetching. LinkedIn ads are warmed by search_linkedin_ads; an uncached one is refetched by id. TikTok ads are warmed by search_tiktok_ads; a stale ref is refetched by tiktok_id (1 credit). Do NOT copy body, headline, media_url, cards or any other field: the server reconstructs the full ad from its own cache, so anything else you pass is discarded.
submit_feedback
ChatGPTSend the user's feedback about Proxy to the Proxy team. Call when the user asks to send feedback, complains about a result, or praises one, or needs ad or competitor-advertising data no tool here covers (category missing_tool). Offer it after a tool fails twice. Free — no credits. Never include emails, names, or other personal data in the text.