HYPD AI - Paid Ads & Analytics

List the sellers offering a specific Google Shopping product, with each seller's price, shipping, special offers and ratings. Use to compare prices across sellers for one product. Pass a productId from shopping_top_products. Returns paginated seller rows plus a resultId; call again with the same resultId, page and pageSize to read further pages. Location and language default to the Google Ads account context; if none is loaded, ask the user.

shopping_sellers

Fetch the Google search results page (SERP) for one keyword, filtered by block type (organic, paid, featured_snippet, local_pack, people_also_ask, shopping and others). Pass itemTypes explicitly; ['paid'] returns the sponsored results with each advertiser's domain, which answers who is advertising on a keyword. Returns paginated SERP items plus a resultId; call again with the same resultId, page and pageSize to read further pages. Location and language default to the Google Ads account context; if none is loaded, ask the user rather than assuming worldwide. Results combine Google data with third-party aggregated data.

serp_results

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). Returns the creative text (body, headline, CTA), media URLs, advertiser page, publisher platforms, run dates and countries; the thumbnail renders inline. Returns null if no ad matches the id. Use it to get the visual for an ad found on the official EU path (those rows carry targeting and reach but no inline media). This endpoint returns web-sourced rows (dataSource="web") without audience targeting or reach; for those use meta_ad_library_search or meta_ad_library_advertiser_ads scoped to EU, EEA or UK countries. Media URLs are signed and expire within hours.

meta_ad_library_ad_detail

Return definitions of the Meta Ads performance metrics produced by meta_insights — what each field means and its unit (spend, impressions, reach, frequency, clicks, link clicks, CTR, CPC, CPM, actions, action_values, purchase_roas, cost_per_action_type, video play milestones). Use to interpret meta_insights output correctly before drawing conclusions. Pass metric to get one definition (e.g. "purchase_roas"); omit it to get them all. This is curated reference data, not a live account lookup.

meta_get_metric_definition

Return Meta's official advertising policy and compliance references (Advertising Standards, prohibited and restricted content, Special Ad Categories, commerce policies, community standards) with their canonical URLs and a short summary of each. Use when reviewing whether an ad, creative, or landing page is compliant, or when the user asks what Meta allows. Optionally pass topic to filter to a specific area (e.g. "restricted", "special ad categories"). This is curated reference data, not a live account lookup.

meta_get_policy

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_get_search_volume

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_top_products

List HYPD's marketing methodology guides (skills), with a name and a one-line description for each. Skills are reference documents on topics such as Google Ads account review, Shopping feed diagnostics or Meta creative review. Use when the user asks which guides are available, or to find the name to pass to load_skill. Takes no arguments and reads nothing from any external platform.

list_skills

List HYPD's library of saved prompt templates: pre-written analysis and reporting requests a user can run against their connected accounts, for example a weekly Google Ads performance summary or a Merchant Center disapproval report. Each entry has a key, title, category, platforms, tags and runsIn (which assistant the template was written for). Optionally filter by category, platform or a text query over titles and tags. Use when the user asks which templates or ready-made reports exist. Pass the chosen key to prompt_templates_run.

prompt_templates_list

List the user's connected LinkedIn Ads accounts. Use this first to discover the accountId every other linkedin tool requires. Returns each account's numeric id, display name, currency, account status, and whether it is a test account — test accounts return NO analytics data, so warn the user before analyzing one. If no accounts are returned, the user needs to connect LinkedIn Ads on the Ad Platforms page (Connect → Ad Platforms).

linkedin_list_ad_accounts

List the user's connected Microsoft Advertising (Bing Ads) accounts. Use this first to discover the accountId every other microsoft_ads tool requires. Returns each account's id, display name, account number, and account status. If no accounts are returned, the user needs to connect Microsoft Advertising on the Ad Platforms page (Connect → Ad Platforms).

microsoft_ads_list_accounts

List the ads a specific advertiser is running or has run in the public Meta Ad Library. Pass pageId (from meta_ad_library_advertisers, from a meta_ad_library_search row, or a known Facebook Page id); optionally countries (two-letter ISO codes) and adActiveStatus (active, inactive, all). Each result carries the creative text, media URLs, publisher platforms and run dates; thumbnails render inline (up to 12 per call). EU, EEA and UK country scopes add Meta's official transparency fields (audience reach, targeting, payer), marked dataSource="official". Spend and impressions are not published for commercial ads. Media URLs are signed and expire within hours. Paginate with pageSize and nextPageToken.

meta_ad_library_advertiser_ads

Inventory the JavaScript, CSS, and image resources loaded by a single landing page URL, 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).

lp_audit_resources

Return the full text of one HYPD marketing methodology guide (skill) by name, from list_skills. A skill is reference material written by HYPD: definitions, checklists and analysis steps for a topic such as wasted-spend review or landing-page checks. Use it as background when the user asks for that type of analysis. The text can be shown to the user on request. Reads nothing from any external platform.

load_skill

Returns HYPD's getting-started reference: supported platforms, account identifier formats, how the tool groups relate, and current plan/trial status. Use when setup context is needed or the user asks what HYPD can access. Takes no arguments and does not access ad platforms.

init

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_transparency_advertiser

Capture a screenshot of a single landing page URL, 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_screenshot

Search LinkedIn's public Ad Library — find live and past LinkedIn ads across ALL advertisers for competitor and market research (the LinkedIn counterpart of meta_ad_library_search). Provide at least one of keyword (space-separated words are ANDed), advertiser (company name), or payerName (who paid — can differ from the advertiser); optionally countries (two-letter ISO codes, e.g. ["DE","US"]), a serving-date range, and targeting-facet filters (includedTargetingFacetCategories / excludedTargetingFacetCategories from LANGUAGE, LOCATION, AUDIENCE, AGE, GENDER, COMPANY, EDUCATION, JOB, INTERESTS, TRAITS). accountId is required for authentication only — any connected LinkedIn Ads account works and the results are NOT limited to it. DATES: endDate is EXCLUSIVE (for one day, pass the next day as endDate); omitting the whole range defaults to YESTERDAY's ads, so pass startDate for anything broader. Coverage starts 2023-06-01; ads appear 24-48h after their first impression and are retained one year past their last. Each ad renders inline as a thumbnail creative (up to 12 per call) with its text (headline, body, CTA) and full-res image URL; rows carry the official transparency metadata — advertiser, the public ad detail page URL (adUrl), targeting criteria, and per-country impression RANGES (LinkedIn never publishes exact spend or impressions). Restricted ads and video files carry no inline creative (videos show their poster frame); the adUrl detail page always has the full ad. Paginate with count (max 25 per page — the library's hard cap) and start: pass the returned nextStart back as start until it is null. Thumbnails are one small JPEG frame (animated creatives lose their motion); full-res image URLs are also returned. Results may lag LinkedIn's UI; previews are best-effort and a missing preview does not mean the ad has no creative.

linkedin_ad_library_search

Search the public Meta Ad Library (Facebook and Instagram) by keyword to find live and past ads across advertisers, for competitor and market research. Pass query; optionally countries (two-letter ISO codes), adActiveStatus (active, inactive, all) and mediaType (image, video, meme, none, all). Each result carries the creative text (body, headline, CTA), media URLs, advertiser page name and id, publisher platforms and run dates; thumbnails render inline (up to 12 per call). When every country passed is in the EU, EEA or UK, rows also include Meta's official transparency fields (audience reach, targeting, payer) and are marked dataSource="official"; otherwise those fields are absent. Spend and impressions are not published for commercial ads. Media URLs are signed and expire within hours. Paginate with pageSize and nextPageToken.

meta_ad_library_search

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.

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

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.

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.

PREREQUISITE: Run init tool first once per chat. Validate that a set of GA4 dimensions and metrics can be queried together before running a report (GA4 rejects incompatible combos). Use to de-risk a google_analytics_run_report query the user is unsure about. Pass propertyId and the dimensions/metrics to test; optionally a compatibilityFilter (COMPATIBLE or INCOMPATIBLE).

PREREQUISITE: Run init tool first once per chat. Compare conversions under last-click vs data-driven attribution, to see how credit shifts between channels/campaigns. Use when the user questions which attribution model to trust or why Ads and GA4 conversion counts differ. Pass propertyId and dateRanges; optionally a dimensionFilter and limit.

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.

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.