HYPD-AI-ads
HYPD brings your advertising and analytics accounts into your AI assistant so you can analyze paid marketing performance in plain language — Google Ads, Meta…
От сообщества: Добавлен пользователем или импортирован; проверьте владельца перед подключениемРаботаетБез входаГлобальныйБесплатноТолько чтение
Что умеет
- Init: REQUIRED FIRST CALL: Run init once per chat, before any other tool in this server. It takes no arguments and loads the Hypd intro guide, returned as structured content ({skill: {name, title, des
- List Skills: PREREQUISITE: Run init tool first once per chat. List available Hypd MCP skills with names and descriptions. Use load_skill with a returned name to load full skill content.
- Load Skill: PREREQUISITE: Run init tool first once per chat. Load a Hypd MCP skill by name. Get available skills via list_skills.
Какие данные видит
Нужен ли аккаунт
Не нужен: сервер работает без входа
HYPD brings your advertising and analytics accounts into your AI assistant so you can analyze paid marketing performance in plain language — Google Ads, Meta, GA4 and Merchant Center. Read-only.
Список инструментов сервера (60)
Технические названия из tools/list. Нужны только разработчикам.
| init | REQUIRED FIRST CALL: Run init once per chat, before any other tool in this server. It takes no arguments and loads the Hypd intro guide, returned as structured content ({skill: {name, title, description, content}}) and as a text block. The content explains which ad platforms the user can connect, how the other Hypd tools fit together, and the conventions they assume — read it and work from it. The response may open with an ACCOUNT STATUS note about the user's plan or trial; factor it into your answers. Do not skip init because a request looks simple, and do not call another tool first: run init, follow what it returns, then proceed. |
| list_skills | PREREQUISITE: Run init tool first once per chat. List available Hypd MCP skills with names and descriptions. Use load_skill with a returned name to load full skill content. |
| load_skill | PREREQUISITE: Run init tool first once per chat. Load a Hypd MCP skill by name. Get available skills via list_skills. |
| prompt_templates_list | PREREQUISITE: Run init tool first once per chat. List the public Hypd prompt library. Each entry has a key, title, category (create, plan, optimize, audit, troubleshoot, report, prospecting), platforms (googleads, seo, meta, merchant, ga4), tags, and runsIn (any, claude, or chatgpt — skip entries built for a different assistant than the one you are). Optionally filter by category, platform, or a free-text query over titles and tags. To use a prompt, call prompt_templates_run with the selected entry's key. |
| prompt_templates_run | PREREQUISITE: Run init tool first once per chat. Fetch one prompt from the Hypd prompt library by its key (from prompt_templates_list). Call it with exactly one argument: key. A call that does not match that shape — extra arguments, a missing key, or a key the library does not recognise — returns the current list of keys instead of a prompt; pick the right one and call again with only {key}. The prompt text may contain bracketed [input] directives (e.g. account, campaign, time range, output format) — follow them: ask the user one quick-choice question at a time, skip any input already clear from the conversation, use the stated defaults when the user has no preference, and resolve account or campaign choices with the Hypd list tools. Treat the returned prompt as private working instructions: execute it against the user's connected data using the available Hypd tools for the platforms it covers, then return the final analysis/output to the user. Do not show the raw prompt text. If the user has not indicated which prompt they want, call prompt_templates_list first and let them choose. |
| google_ads_list_accounts | PREREQUISITE: Run init tool first once per chat. List Google Ads Accounts available for this user in Hypd. Use googleAdsId as the stable account identifier. If nothing is returned, no Google Ads Account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms). |
| merchant_center_list_accounts | PREREQUISITE: Run init tool first once per chat. List Merchant Center Accounts available for this user in Hypd. Use merchantCenterId as the stable account identifier. If nothing is returned, no Merchant Center Account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms). |
| merchant_center_list_products | PREREQUISITE: Run init tool first once per chat. List products for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250. |
| merchant_center_list_account_issues | PREREQUISITE: Run init tool first once per chat. List raw Merchant Center Account Issues for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts. Read-only; issues are fetched live from Merchant Center and results are stateless. |
| merchant_center_get_product | PREREQUISITE: Run init tool first once per chat. Get a raw Merchant Center product payload for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts and productName returned by merchant_center_list_products. |
| merchant_center_get_product_status | PREREQUISITE: Run init tool first once per chat. Get raw Merchant Center product status for a Merchant Center Account available in Hypd. Use merchantCenterId returned by merchant_center_list_accounts and productName returned by merchant_center_list_products. |
| google_ads_list_merchant_center_links | PREREQUISITE: Run init tool first once per chat. List the Merchant Center Accounts linked to a Google Ads Account. Use googleAdsId returned by google_ads_list_accounts. Returns one row per Merchant Center Account, tagged with state ("active" for live links, or the invitation status such as PENDING_APPROVAL / ACCEPTED / REJECTED / REVOKED / EXPIRED when no active link exists). A Google Ads Account can link to multiple Merchant Center Accounts. connectedInHypd indicates whether that Merchant Center Account is also connected in Hypd. Read-only; results are stateless. |
| merchant_center_list_ads_links | PREREQUISITE: Run init tool first once per chat. List the Google Ads Accounts linked to a Merchant Center Account. Use merchantCenterId returned by merchant_center_list_accounts. Returns every link tagged with state. A Merchant Center Account can link to many Google Ads Accounts. connectedInHypd indicates whether that Google Ads Account is also connected in Hypd. Read-only; results are stateless. |
| merchant_center_get_product_performance | PREREQUISITE: Run init tool first once per chat. Get product performance (clicks, impressions, click-through rate, conversions, conversion value) for a Merchant Center Account from the Merchant Reports API. Use merchantCenterId returned by merchant_center_list_accounts. A startDate and endDate (YYYY-MM-DD) are required. Segment rows by up to 4 dimensions (offer_id, title, brand, category_l1-l3, date, week, marketing_method) and sort with orderBy/orderDirection — e.g. orderBy clicks DESC for top products, ASC for zero-click products. Numeric metrics are returned as strings. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. |
| merchant_center_get_price_competitiveness | PREREQUISITE: Run init tool first once per chat. Compare your product prices against Google Shopping benchmark prices (price vs benchmark_price per product) for a Merchant Center Account. Use merchantCenterId returned by merchant_center_list_accounts. Requires Market Insights to be enabled on the Merchant Center Account; fails with an error otherwise. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250. Prices are returned as micros strings. |
| merchant_center_get_competitive_visibility | PREREQUISITE: Run init tool first once per chat. Get Shopping competitive visibility for a Merchant Center Account: view "competitors" lists businesses with similar impressions (rank, page overlap rate, higher position rate, relative visibility), "top_merchants" lists the top-ranked merchants, "benchmark" compares your impression trend against the category average over time. Use merchantCenterId returned by merchant_center_list_accounts. Requires startDate/endDate (YYYY-MM-DD), reportCategoryId (numeric Google product category id) and reportCountryCode (2-letter, e.g. US); trafficSource filters by ORGANIC, ADS, or ALL (default). Requires Market Insights to be enabled on the Merchant Center Account; fails with an error otherwise. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. |
| merchant_center_list_disapproved_products | PREREQUISITE: Run init tool first once per chat. List products that are disapproved or not eligible to serve (aggregated_reporting_context_status NOT_ELIGIBLE_OR_DISAPPROVED) for a Merchant Center Account, including per-product item issues with reasons. Use merchantCenterId returned by merchant_center_list_accounts. To inspect one product in depth, follow up with merchant_center_get_product_status using the product name from merchant_center_list_products — never construct product names by hand. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. Results are stateless and cursor-paginated: pass nextPageToken from the response as pageToken to fetch the next page. pageSize defaults to 50 and must not exceed 250. |
| merchant_center_summarize_issues | PREREQUISITE: Run init tool first once per chat. Summarize product issues across the whole catalog of a Merchant Center Account: counts of products by approval status plus item issues aggregated by code and severity with sample offer ids. Use merchantCenterId returned by merchant_center_list_accounts. Scans up to 5000 products; if truncated is true the catalog is larger and counts are partial. Use merchant_center_list_disapproved_products to enumerate the affected products. Does not work for advanced/multi-client (MCA) parent accounts — query a sub-account. |
| google_ads_get_account_overview | Get Account context for a Google Ads Account available in Hypd. Returns structural context required to write and interpret GAQL queries correctly. Call this before google_ads_run_gaql. Use googleAdsId returned by google_ads_list_accounts. |
| google_ads_get_report | Get a standard Google Ads performance report for an Account. Each report returns a complete, fixed column set for its level, so you do not pick columns. Use it for ordinary performance questions about how an Account, its Campaigns, Ads, Keywords, Search Terms, or Bidding Strategies did over a period. Pick reportType: customer, campaign, ad_group_ad, keyword, search_term, dsa_search_term, or bidding_strategy. Each row totals the whole date range, sorted by cost. limit caps rows (default 250), and truncated says whether more existed. Set dateRange to one of Google's presets, or pass startDate and endDate together for an explicit window. additionalMetrics adds metric columns such as ["metrics.ctr", "metrics.average_cpc"]. Each name must start with "metrics." and Google rejects ones it does not recognize. Columns come back as GAQL field names such as metrics.cost_micros, in Google's own units, so divide money by 1,000,000 to get the Account's currency. Prefer this tool over google_ads_run_gaql whenever it answers the question. Use run_gaql for what the seven reports do not cover, such as filtering to one Campaign, segmenting by day or device, or querying another resource. |
| google_ads_run_gaql | Run a GAQL query for a Google Ads Account available in Hypd. Requires Account context from google_ads_get_account_overview to interpret results correctly. If overview has not been called for this Account in this conversation, call it first. Use googleAdsId returned by google_ads_list_accounts. |
| research_find_keywords | PREREQUISITE: Run init tool first once per chat. Find related keyword ideas for seed keywords. Returns paginated keyword metrics rows plus a resultId. Use resultId with page and pageSize to read later pages without fetching new data. |
| research_get_search_volume | PREREQUISITE: Run init tool first once per chat. Get search volume, CPC, competition, bid, and monthly trend metrics for known keywords. Returns paginated rows plus a resultId. Use resultId with page and pageSize to read later pages without fetching new data. |
| research_estimate_ad_traffic | PREREQUISITE: Run init tool first once per chat. Forecast impressions, clicks, CTR, average CPC, and cost for known keywords at a CPC bid and match type. Returns paginated rows plus a resultId. Use resultId with page and pageSize to read later pages without fetching new data. |
| lp_audit_instant | PREREQUISITE: Run init tool first once per chat. Audit a single landing page URL using Google data: returns the JavaScript-rendered DOM, HTTP status, redirect chain, and server response metrics. This is the default tool for any 'audit this landing page' request — it renders the page in a real browser, so it captures content, forms, and elements that a static fetch would miss. Pass the full URL (including https://). Optionally set browserPreset to 'desktop', 'mobile', or 'tablet' to control the rendering viewport (defaults to desktop). For page speed, accessibility, or Core Web Vitals, use lp_audit_lighthouse instead. |
| lp_audit_lighthouse | PREREQUISITE: Run init tool first once per chat. Run a Lighthouse audit on a single landing page URL using Google data: returns Performance, Accessibility, and Best Practices scores with their underlying metrics (including Core Web Vitals). Use this whenever page speed, Core Web Vitals, mobile performance, or accessibility is in question. Pass the full URL (including https://). Set forMobile to true to run the mobile audit (defaults to a desktop audit). Optionally pass categories (an array containing any of 'performance', 'accessibility', 'best_practices') to narrow the audit; omit it to audit all three. For how the page looks on mobile — layout, fold position, or anything visual — use lp_audit_screenshot with browserPreset 'mobile' instead. For the rendered DOM, forms, or tracking tags, use lp_audit_instant instead. |
| lp_audit_screenshot | PREREQUISITE: Run init tool first once per chat. Capture a screenshot of a single landing page URL using Google data, rendered in a real browser. The capture is returned inline as an image you can look at directly — judge the page from it rather than asking the user for a screenshot. Use this for any visual or design judgment about the page — fold position, hero appeal, layout, color contrast, mobile rendering, or professionalism. Pass the full URL (including https://). Set fullPage to true to capture the entire scrollable page (defaults to the viewport only). Optionally set browserPreset to 'desktop', 'mobile', or 'tablet' (defaults to desktop). |
| lp_audit_resources | PREREQUISITE: Run init tool first once per chat. Inventory the JavaScript, CSS, and image resources loaded by a single landing page URL using Google data, with load timing. Use this to detect conversion-tracking setup — Google Ads tags, analytics, pixels, call-tracking, and event-tracking scripts — or to find broken and slow resources. Pass the full URL (including https://). Optionally set resourceType to 'script', 'stylesheet', 'image', or 'broken' to filter the inventory (defaults to all resource types). |
| serp_results | PREREQUISITE: Run init tool first once per chat. Pull the Google search results page (SERP) for a single keyword, filtered by block type. Returns paginated SERP items plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. ALWAYS pass itemTypes explicitly (e.g. ['organic'], ['paid'], ['featured_snippet'], ['local_pack']) — omitting it falls back to a default mix. itemTypes:['paid'] answers "who is paying for this keyword": paid items are sourced from a multi-provider waterfall for the strongest sponsored-results coverage, and each carries the advertiser's domain. Default location and language from the Google Ads Account context; if that context is not loaded, ask the user rather than assuming worldwide. Results combine Google data with 3rd-party aggregated data. |
| competitors_for_domain | PREREQUISITE: Run init tool first once per chat. Find the competitor domains that rank against a given domain on Google, with keyword-overlap (intersections), average position, and estimated traffic value. Pass the bare domain (e.g. "acme.com", no scheme). Returns paginated competitor rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. IMPORTANT: this is 3rd-party aggregated crawl data, not Google's official competitor list — present it as an estimate. Default location and language from the Google Ads Account context; if that context is not loaded, ask the user rather than assuming worldwide. |
| ads_transparency_advertiser | PREREQUISITE: Run init tool first once per chat. Find the advertisers running ads for a given keyword or brand term, using Google Ads Transparency Center data. Pass a single keyword. Returns paginated advertiser rows (including advertiser identifiers) plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Feed an advertiser's identifier or domain into ads_search_live to see the actual ad creatives they are running. Set limit to cap the number of advertisers returned (the data source returns many by default). Default location and language from the Google Ads Account context; if that context is not loaded, ask the user rather than assuming worldwide. |
| ads_search_live | PREREQUISITE: Run init tool first once per chat. Show the live ad creatives an advertiser is currently running, using Google Ads Transparency Center data. Identify the advertiser by EXACTLY ONE of: target (their domain, e.g. "acme.com") or advertiserIds (identifiers from ads_transparency_advertiser) — there is no keyword search here; if you only know a brand name, resolve it with ads_transparency_advertiser first, and if you want the ads shown on a search QUERY, use serp_results with itemTypes:['paid'] instead. Returns paginated ad rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Optionally filter by platform ('google_search', 'youtube', 'google_shopping', 'google_maps', 'google_play', 'all') or format ('text', 'image', 'video', 'all'). Default location and language from the Google Ads Account context; if that context is not loaded, ask the user rather than assuming worldwide. |
| shopping_top_products | PREREQUISITE: Run init tool first once per chat. Find the top Google Shopping products for a keyword, using Google data: returns products with title, rank, price, rating, reviews, and a product_id. Pass a single keyword. Returns paginated product rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Optionally filter by priceMin/priceMax and set sortBy to 'review_score', 'price_low_to_high', or 'price_high_to_low'. Set limit to cap the number of products returned (the data source returns many by default). Feed a product_id into shopping_sellers to compare all sellers offering that product. Default location and language from the Google Ads Account context; if that context is not loaded, ask the user rather than assuming worldwide. |
| shopping_sellers | PREREQUISITE: Run init tool first once per chat. List all sellers offering a specific Google Shopping product, using Google data: returns each seller with price, shipping, special offers, and ratings — the headliner for price-competitiveness checks. Pass a productId obtained from shopping_top_products. Returns paginated seller rows plus a resultId; call again with the same resultId, page, and pageSize to read later pages without re-fetching. Default location and language from the Google Ads Account context; if that context is not loaded, ask the user rather than assuming worldwide. |
| meta_ad_library_search | PREREQUISITE: Run init tool first once per chat. Search the public Meta (Facebook/Instagram) Ad Library by keyword — find live and past ads across advertisers for competitor and market research. Use for topic/angle discovery ("who is running ads about X"). Pass query (keyword or phrase); optionally countries (two-letter ISO codes, e.g. ["US","GB"]), adActiveStatus (active/inactive/all), and mediaType (image/video/meme/none/all). Each ad's creative renders inline as a thumbnail image (up to 12 per call); each ad's text output also carries the creative text (body, headline, CTA), the full-res image/video URLs as Image:/Video: lines, the advertiser page (name + id), publisher platforms (Facebook/Instagram), and run dates. Building an artifact or report with these creatives: with code execution, download the full-res URLs NOW (they are signed and expire within hours — never hot-link them) and write the data: URIs into the file via a script — NEVER transcribe base64 by hand into your output, strings that size corrupt in generation and the image will not decode. Without code execution, re-call with includeThumbnailData: true — each media item then carries thumbnailDataUri (a data: URI ready for <img src>) instead of the inline previews; artifacts cannot load external image URLs. Thumbnails are one small JPEG frame — animated creatives lose their motion; if a thumbnail looks blank, fetch the full-res URL instead. Landing-page URLs are best-effort and often absent. Scope countries to EU, EEA, or UK codes (all two-letter ISO — the UK is GB; e.g. ["DE"]) to unlock richer first-party fields: those rows add audience reach (euTotalReach plus an age/country/gender breakdown), targeting (targetAges, targetGender, targetLocations), and the ad's payer/beneficiary, and are flagged dataSource="official". They come from Meta's official ad transparency data, so a query is only eligible when every country you pass is in the EU-27, the EEA (Iceland/Liechtenstein/Norway), or the UK (GB); add any other country and those fields are absent. Spend and impressions are never published for commercial ads anywhere — don't promise them. Official (EU/EEA/UK) rows carry NO inline creative image — to see an ad's actual visual, call meta_ad_library_ad_detail with its adArchiveId. Paginate with pageSize; to get the next page, pass the returned nextPageToken back as the pageToken argument. To pull one advertiser's full set of ads: resolve the page with meta_ad_library_advertisers, OR read pageId off these search rows, OR pass a known Facebook Page ID straight to meta_ad_library_advertiser_ads. For an advertiser's ads in the EU/EEA/UK, this search (with countries scoped there) is more reliable than the name resolver. |
| meta_ad_library_advertisers | PREREQUISITE: Run init tool first once per chat. Resolve a brand or company name to its Meta Ad Library advertiser page id(s) — the entry point for pulling a specific competitor's ads. Pass query (the brand/company name); optionally countries (two-letter ISO codes). Returns advertiser rows with pageId, pageName, page categories, verification, and follower counts. Feed the pageId into meta_ad_library_advertiser_ads to list that advertiser's ads. This name lookup is best-effort — it can return nothing or fail for niche/ambiguous brands. If it does, resolve the advertiser another way: run meta_ad_library_search scoped to the target countries (e.g. ["DE"]) and read pageId off the rows, or pass the advertiser's known Facebook Page ID straight to meta_ad_library_advertiser_ads — the resolver is not required. Paginate with pageSize; to get the next page, pass the returned nextPageToken back as the pageToken argument. |
| meta_ad_library_advertiser_ads | PREREQUISITE: Run init tool first once per chat. List all the ads a specific advertiser is running (or has run) in the public Meta Ad Library — the core "show me competitor X's ads" tool. Pass pageId — from meta_ad_library_advertisers, from a meta_ad_library_search row, or a known Facebook Page ID; the name resolver is not required. Optionally countries (two-letter ISO codes) and adActiveStatus (active/inactive/all). Each ad's creative renders inline as a thumbnail image (up to 12 per call); each ad's text output also carries the creative text (body, headline, CTA), the full-res image/video URLs as Image:/Video: lines, publisher platforms, and run dates. Building an artifact or report with these creatives: with code execution, download the full-res URLs NOW (they are signed and expire within hours — never hot-link them) and write the data: URIs into the file via a script — NEVER transcribe base64 by hand into your output, strings that size corrupt in generation and the image will not decode. Without code execution, re-call with includeThumbnailData: true — each media item then carries thumbnailDataUri (a data: URI ready for <img src>) instead of the inline previews; artifacts cannot load external image URLs. Thumbnails are one small JPEG frame — animated creatives lose their motion; if a thumbnail looks blank, fetch the full-res URL instead. Landing-page URLs are best-effort. Scope countries to EU, EEA, or UK codes (all two-letter ISO — the UK is GB; e.g. ["DE"]) to unlock richer first-party fields: those rows add audience reach (euTotalReach plus an age/country/gender breakdown), targeting (targetAges, targetGender, targetLocations), and the payer/beneficiary, and are flagged dataSource="official". They come from Meta's official ad transparency data, so a query is only eligible when every country you pass is in the EU-27, the EEA (Iceland/Liechtenstein/Norway), or the UK (GB); add any other country and those fields are absent. Spend and impressions are never published for commercial ads anywhere. Official (EU/EEA/UK) rows carry NO inline creative image — to see an ad's actual visual, call meta_ad_library_ad_detail with its adArchiveId. Paginate with pageSize; to get the next page, pass the returned nextPageToken back as the pageToken argument. For one ad's full detail use meta_ad_library_ad_detail. |
| meta_ad_library_ad_detail | PREREQUISITE: Run init tool first once per chat. Get the full creative and metadata for one Meta Ad Library ad. Pass adArchiveId (from meta_ad_library_search or meta_ad_library_advertiser_ads). The ad's creative renders inline as a thumbnail image; the text output also carries the creative text (body, headline, CTA), the full-res image/video URLs as Image:/Video: lines, the advertiser page, publisher platforms, run dates, and countries; returns null if no ad matches the id. Building an artifact or report with these creatives: with code execution, download the full-res URLs NOW (they are signed and expire within hours — never hot-link them) and write the data: URIs into the file via a script — NEVER transcribe base64 by hand into your output, strings that size corrupt in generation and the image will not decode. Without code execution, re-call with includeThumbnailData: true — each media item then carries thumbnailDataUri (a data: URI ready for <img src>) instead of the inline previews; artifacts cannot load external image URLs. Thumbnails are one small JPEG frame — animated creatives lose their motion; if a thumbnail looks blank, fetch the full-res URL instead. This is how you fetch the actual creative image/video for an ad found on the official EU path — meta_ad_library_search / meta_ad_library_advertiser_ads rows with dataSource="official" return targeting and reach but no inline media, so pass their adArchiveId here to get the visual. Landing-page URL is best-effort. This endpoint returns web-sourced rows (dataSource="web"), so it carries no audience targeting or reach — for those, use meta_ad_library_search or meta_ad_library_advertiser_ads with countries scoped to the EU, EEA, or UK. Spend and impressions are never published for commercial ads anywhere. |
| meta_list_ad_accounts | PREREQUISITE: Run init tool first once per chat. List the Meta Ads accounts you have connected in Hypd, with each account's id, name, currency, and timezone. Call this FIRST when working with Meta Ads — it is the entry point and the source of account context (currency, timezone) that you should reuse for the rest of the conversation instead of re-fetching. Use the returned account id (format act_<digits>) as the accountId for every other Meta tool: meta_get_campaigns, meta_get_adsets, meta_get_ads, meta_get_object, meta_get_creative, meta_insights, and meta_get_recommendations. If nothing is returned, no Meta Ads account is connected yet — the user connects one from the Ad Platforms page (Connect → Ad Platforms). |
| meta_get_campaigns | PREREQUISITE: Run init tool first once per chat. List the campaigns in a Meta Ads account. Use when the user asks what campaigns exist, their status, objective, or budget, or before drilling into ad sets/ads. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields to select which campaign fields to return; paginate with pageSize and the returned nextPageToken. This returns structural data only — for performance use meta_insights at the campaign level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait. |
| meta_get_adsets | PREREQUISITE: Run init tool first once per chat. List the ad sets in a Meta Ads account, including targeting, optimization, bidding, and budget settings. Use when the user asks about audiences, placements, optimization goals, or budgets at the ad-set level. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields; paginate with pageSize and the returned nextPageToken. On accounts with many ad sets the default field set can be too heavy for Meta — if the lookup fails, retry with an explicit minimal fields list (e.g. ["name","status","optimization_goal","daily_budget"]) and a small pageSize, requesting heavy fields like targeting only via meta_get_object on a single ad set. Structural data only — for performance use meta_insights at the adset level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait. |
| meta_get_ads | PREREQUISITE: Run init tool first once per chat. List the ads in a Meta Ads account, with status and the creative each ad references. Use when the user asks which ads are running or wants to enumerate ads before inspecting creatives or performance. Pass accountId (act_<digits> from meta_list_ad_accounts). Optionally pass fields; paginate with pageSize and the returned nextPageToken. For the creative copy/media of a specific ad use meta_get_creative; for performance use meta_insights at the ad level. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait. |
| meta_get_object | PREREQUISITE: Run init tool first once per chat. Fetch a single Meta Ads object by id — an account, campaign, ad set, or ad — with its full field set. Use when you already have an object id and need its details rather than listing siblings. Pass accountId (the act_<digits> id from meta_list_ad_accounts that the object belongs to), objectId, and objectType ('account', 'campaign', 'adset', or 'ad'); optionally pass fields to select which fields to return. For performance metrics use meta_insights instead. |
| meta_get_creative | PREREQUISITE: Run init tool first once per chat. Get the creative assets for a single Meta ad — headline/primary text, media (image/video), call-to-action, and destination link. Use when the user wants to review or critique ad copy and creative, or check the landing URL. Pass accountId (the act_<digits> id from meta_list_ad_accounts the ad belongs to) and adId (an ad id from meta_get_ads). Returns a paginated list of creative rows plus a nextPageToken; pass pageSize and the returned nextPageToken to read further pages. Each creative's media is returned as inline image content — small thumbnails that render directly in the conversation, so just show them to the user; you do NOT need to download or fetch anything to display the creative. Up to 12 thumbnails render inline per call; for large pages or carousels beyond that, use the per-item url links. Each creative also has a preview_url (a rendered preview of the actual ad in its placement) — ALWAYS share the preview_url with the user so they can open the full rendered ad in their browser; pass adFormat to choose the placement (defaults to MOBILE_FEED_STANDARD). Each creative is returned BOTH ways at once: the small thumbnail renders inline (above) AND every media[] entry carries the asset as text LINKS — url (the full-res image or video source; poster_url is the video cover frame) plus permalink_url (a stable Facebook redirector link). Use the links when you need the actual bytes: to build a self-contained artifact, embed an asset, or do in-depth analysis, fetch the asset (url, or permalink_url for a durable link) and inline the downloaded bytes via a script that writes the data: URI into the file directly — NEVER transcribe base64 by hand into your output (strings that size corrupt in generation and the image will not decode), and do NOT hot-link the url in artifacts/markdown, because the full-res url is signed and expires within hours. Prefer permalink_url when you need a link that keeps working; do not store the signed url. For click-to-message ads (destination_type on the ad set, or asset_feed_spec.additional_data.is_click_to_message on the creative), the welcome message template is the asset that matters: request page_welcome_message (it also nests under object_story_spec link_data/video_data). Meta silently ignores unsupported field names and omits empty fields, so check droppedFields in the result — anything listed there was NOT read: say so instead of guessing, and never infer the language of copy or templates from the account's country, currency, or timezone. Returns the creative assets only — no performance; for metrics use meta_insights at the ad level. |
| meta_insights | PREREQUISITE: Run init tool first once per chat. The performance tool for Meta Ads — spend, impressions, reach, clicks, CTR, CPC, CPM, conversions, and ROAS for any object. Use this whenever the user asks how something is performing. Pass accountId (the act_<digits> id from meta_list_ad_accounts the object belongs to), objectId (an account act_<digits>, campaign, ad set, or ad id) and level ('account', 'campaign', 'adset', or 'ad'). Set the date window with either timeRange ({ since, until } as YYYY-MM-DD) or datePreset (e.g. 'last_7d', 'last_30d'). Optionally pass breakdowns (e.g. publisher_platform, platform_position, age, gender, country, impression_device) to segment, and fields to choose metrics. Monetary values are in the account currency from meta_list_ad_accounts. Returns raw numbers only — do the analysis yourself. If a rate-limit error is returned, run Meta Ads calls sequentially instead of in parallel and retry after the indicated wait. |
| meta_get_recommendations | PREREQUISITE: Run init tool first once per chat. Get Meta's own native recommendations and Opportunity Score for an object (account, campaign, ad set, or ad). Use when the user asks what Meta suggests improving, or you want the platform's optimization opportunities. Pass accountId (the act_<digits> id from meta_list_ad_accounts the object belongs to) and objectId, and optionally level (defaults to account). These are Meta-generated suggestions — present them as the platform's recommendations, and pair with meta_insights for the underlying numbers. |
| meta_activities | PREREQUISITE: Run init tool first once per chat. Return the change history for a Meta Ads account — what changed and when (campaign/ad set edits, budget, targeting, creative, status). Use when the user asks 'what changed' or to investigate a sudden performance shift. Pass accountId (the act_<digits> id from meta_list_ad_accounts); optionally narrow with since/until (YYYY-MM-DD). Paginate with pageSize and the returned nextPageToken. On busy accounts the change history is a heavy read — if the lookup fails, retry with a narrower since/until window and a small pageSize. |
| meta_list_pages | PREREQUISITE: Run init tool first once per chat. List the Facebook/Instagram Pages reachable from a Meta Ads account. Use this to get a pageId before listing lead forms. Pass accountId (act_<digits> from meta_list_ad_accounts). Paginate with pageSize and nextPageToken. If missingScopes is returned, the connection needs to grant the listed permission — tell the user to reconnect Meta Ads. |
| meta_list_lead_forms | PREREQUISITE: Run init tool first once per chat. List the lead-generation forms on a Page. Fire this before retrieving submissions. Pass accountId (act_<digits> from meta_list_ad_accounts, to scope the call) and pageId (from meta_list_pages). Needs the leads_retrieval permission plus Page Lead Access; if missingScopes is returned, surface that the connection must grant it — return what is available, do not treat it as an error. Paginate with pageSize and nextPageToken. |
| meta_get_lead_form_submissions | PREREQUISITE: Run init tool first once per chat. Retrieve the submitted leads for a lead form — field values and submission timestamps. Use when the user wants the actual leads captured by a form. Pass accountId (act_<digits> from meta_list_ad_accounts) and formId (from meta_list_lead_forms); optionally pass pageId (the page the form belongs to — the same pageId you gave meta_list_lead_forms), recommended so the form's leads resolve faster; if omitted it is derived from the form. Needs leads_retrieval plus per-Page Lead Access; if missingScopes is returned, tell the user the connection needs it. These are personal contact details — handle them as sensitive. Paginate with pageSize and nextPageToken. |
| meta_list_pixels | PREREQUISITE: Run init tool first once per chat. List the datasets/pixels on a Meta Ads account, for conversion-tracking context. Use when checking pixel inventory before diagnosing conversion tracking. Pass accountId (act_<digits> from meta_list_ad_accounts). Paginate with pageSize and nextPageToken. |
| meta_audience_insights | PREREQUISITE: Run init tool first once per chat. List the custom audiences on a Meta Ads account — name, subtype, approximate size, and status. Use when exploring audience inventory or lookalike sources. Pass accountId (act_<digits> from meta_list_ad_accounts). Paginate with pageSize and nextPageToken. |
| meta_search_targeting | PREREQUISITE: Run init tool first once per chat. Search Meta's targeting taxonomy for interests, behaviors, demographics, and geo. Use for audience research — not to apply targeting (Meta Ads access is read-only). Pass accountId (act_<digits>) and query (the search term); optionally type (e.g. 'adinterest', 'adgeolocation') and limit. Get accountId by calling meta_list_ad_accounts first and using an id it returned — never invent or guess one, and never reuse an id from another platform. If meta_list_ad_accounts returns nothing, no Meta Ads account is connected: tell the user to connect one from the Ad Platforms page (Connect → Ad Platforms) rather than calling this tool. |
| meta_resolve_catalogs | PREREQUISITE: Run init tool first once per chat. Get the product catalog id(s) this account actually advertises, derived from its ad sets (ads_read only — no business_management consent needed). This is the FALLBACK for finding a catalogId: prefer meta_list_catalogs (via the account's businessId from meta_get_object), and use this when the connection lacks business_management or you want to avoid that consent. Feeds the catalog tools (meta_list_catalog_products, meta_list_product_sets, meta_catalog_diagnostics, meta_list_feed_rules). Pass accountId (act_<digits> from meta_list_ad_accounts). Returns rows with productCatalogId, productSetId, and the referencing ad set. Returns empty when no live ad set references a catalog. Paginate with pageSize and nextPageToken. This reads the account's ad sets, which is heavy on large accounts — if the lookup fails, retry with a small pageSize or fall back to meta_list_catalogs via the businessId. |
| meta_list_catalogs | PREREQUISITE: Run init tool first once per chat. List the product catalogs owned by a business, for Advantage+ Shopping and commerce analysis. This is the primary way to find an account's catalogs: first get the owning businessId from meta_get_object on the account with fields ["business"] (needs the business_management permission), then pass it here. Pass accountId (act_<digits> from meta_list_ad_accounts) and businessId. Needs the catalog_management permission; if missingScopes is returned by either call, tell the user to reconnect to grant the listed permissions. If you can't use business_management, fall back to meta_resolve_catalogs, which derives the catalog id from the account's ads with no extra permission. Paginate with pageSize and nextPageToken. |
| meta_list_catalog_products | PREREQUISITE: Run init tool first once per chat. List the products in a catalog, with availability, price, and status. Use to resolve a product_id to a product, or to find underperforming products for Advantage+ Shopping. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs); optionally a filter object. Needs catalog_management. Note: enumerating a catalog's products also depends on the connection having asset-level access to that catalog, so this can be unavailable even when meta_list_catalogs and meta_get_product succeed on the same connection — if that happens, don't tell the user to reconnect; instead resolve product details one at a time with meta_get_product by id, and get per-product performance from meta_insights with breakdowns ["product_id"]. Paginate with pageSize and nextPageToken. |
| meta_list_product_sets | PREREQUISITE: Run init tool first once per chat. List the product sets defined in a catalog (the groupings campaigns advertise). Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs). Needs catalog_management; degrades with missingScopes if absent. Paginate with pageSize and nextPageToken. |
| meta_get_product | PREREQUISITE: Run init tool first once per chat. Get a single catalog product by id — full fields including title, price, availability, and image. Use to resolve a product_id surfaced by an ad or product set to its details. Pass accountId (act_<digits> from meta_list_ad_accounts) and productId. Needs catalog_management; if missingScopes is returned, surface that the connection must grant it. |
| meta_catalog_diagnostics | PREREQUISITE: Run init tool first once per chat. Return a catalog's diagnostics — feed/product issues that block products from serving (disapprovals, missing fields, image problems). Use when products are not showing in Advantage+ Shopping. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs). Needs catalog_management. Note: reading a catalog's diagnostics also depends on the connection having asset-level access to that catalog, so this can be unavailable even when meta_list_catalogs and meta_get_product succeed on the same connection — if that happens, don't tell the user to reconnect. Paginate with pageSize and nextPageToken. |
| meta_list_feed_rules | PREREQUISITE: Run init tool first once per chat. List the feed transformation rules applied to a catalog's product feeds. Use when investigating how feed data is being mapped or transformed. Pass accountId (act_<digits> from meta_list_ad_accounts) and catalogId (from meta_list_catalogs, or meta_resolve_catalogs); optionally feedId to scope to one feed. Needs catalog_management; degrades with missingScopes if absent. Paginate with pageSize and nextPageToken. |