HYPD AI - Paid Ads & Analytics

PREREQUISITE: Run init tool first once per chat. Pre-flight a report's size before fetching it — returns the row count (and remaining quota) for a given metrics/dimensions/date-range query, without pulling all the rows. Use before google_analytics_run_report on a broad query to avoid huge or quota-heavy pulls. Pass propertyId, metrics, dateRanges, and optionally dimensions and filters.

PREREQUISITE: Run init tool first once per chat. Conversions, revenue, ROAS, and engagement by Google Ads campaign / source-medium — the core GA4-to-Ads join. Use to evaluate paid campaign outcomes in GA4 terms. Pass propertyId and dateRanges; optionally a dimensionFilter (e.g. to paid traffic) and limit. Dimensions and metrics are preset.

PREREQUISITE: Run init tool first once per chat. Conversion-path / assist analysis (GA4 Data API v1alpha) — the channel sequences that lead to conversions, for understanding assisted vs last-touch contribution. Use for "what helped drive conversions" questions. Pass propertyId and dateRanges; optionally a dimensionFilter and limit.

PREREQUISITE: Run init tool first once per chat. List a property's custom dimensions and custom metrics (the Admin API definitions) — the property-specific fields beyond the GA4 standard set. Use to find a client's custom field API names before reporting on them. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).

PREREQUISITE: Run init tool first once per chat. Revenue, transactions, items, and purchase value by source / campaign — GA4 ecommerce outcomes for the paid funnel. Use for "what did we actually sell from this traffic" questions. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.

PREREQUISITE: Run init tool first once per chat. Landing pages ranked by engagement and conversion, filterable to paid traffic — find which entry pages convert and which leak. Use for landing-page and post-click quality questions. Pass propertyId and dateRanges; optionally a dimensionFilter (e.g. to paid) and limit. Dimensions and metrics are preset.

PREREQUISITE: Run init tool first once per chat. List the dimensions and metrics available for a GA4 property (the GA4 Data API metadata), including custom ones. Use to discover valid API names before building a google_analytics_run_report query. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).

PREREQUISITE: Run init tool first once per chat. Get a GA4 property's metadata — display name, timezone, currency, and industry category. Use to orient before reporting (the timezone and currency frame every metric). Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).

PREREQUISITE: Run init tool first once per chat. List the Google Analytics accounts and GA4 properties this connection can access. Use this FIRST for any GA4 task to get a propertyId (properties/<digits>) to pass to the other google_analytics_ tools. Takes no arguments. Returns account summaries with their nested property summaries (property id, display name). If nothing is returned, no Google Analytics Connection exists yet — the user connects one from the Data Sources page (Connect → Data Sources).

PREREQUISITE: Run init tool first once per chat. List the Google Ads links on a GA4 property — confirm whether GA4 is linked to Google Ads (required for campaign-level joins and imported conversions). Use before google_analytics_get_campaign_performance when Google Ads dimensions look empty. Pass propertyId (properties/<digits> from google_analytics_list_account_summaries).

PREREQUISITE: Run init tool first once per chat. Funnel / drop-off analysis (GA4 Data API v1alpha) — step-by-step completion and abandonment for a sequence of events or conditions. Use for "where do users drop off" questions. Pass propertyId, dateRanges, and a funnel: an ordered steps array where each step has a name and a filterExpression (an event or field condition). Optionally funnelBreakdown (a dimension to split each step by) and limit.

PREREQUISITE: Run init tool first once per chat. Last-30-minutes activity from the GA4 Realtime API — active users and events right now, by dimensions like unifiedScreenName or country. Use for "what's happening now" checks, not historical analysis (use google_analytics_run_report for that). Pass propertyId and metrics; optionally dimensions, minuteRanges, filters, and limit.

PREREQUISITE: Run init tool first once per chat. The open-ended GA4 report: any dimensions x metrics x date range, with optional filters, ordering, and paging (limit/offset). Use for ad-hoc questions the preset performance tools do not cover. Validate combos with google_analytics_check_compatibility and size with google_analytics_estimate_report_rows first. Pass propertyId, metrics, dateRanges, and optionally dimensions, dimensionFilter/metricFilter (a single condition on a field, or an andGroup/orGroup of conditions), orderBys, limit, offset.

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 data sources the user can connect, how the other Hypd tools fit together, and the conventions they assume — read it and work from it. Do not skip init because a request looks simple, and do not call another tool first: run init, follow what it returns, then proceed.

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.

PREREQUISITE: Run init tool first once per chat. Load a Hypd MCP skill by name. Get available skills via list_skills.

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.

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.

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).

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).

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.

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.

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.

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.

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.

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.

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 Data Sources page (Connect → Data Sources).

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.

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.

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.

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.

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.

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. To embed the creative in an artifact or report, fetch its URL and inline the downloaded bytes — do NOT hot-link the URL: it is signed and expires within hours. 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.

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. To embed a creative in an artifact or report, fetch its URL and inline the downloaded bytes — do NOT hot-link the URL: it is signed and expires within hours. 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.

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.

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. To embed a creative in an artifact or report, fetch its URL and inline the downloaded bytes — do NOT hot-link the URL: it is signed and expires within hours. 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.

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.

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.

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.

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.