HYPD AI - Paid Ads & Analytics

Pre-flight a report's size with a one-row GA4 report request that consumes Data API quota. Returns the unpaged row count and property quota state, without returning report rows. Use before google_analytics_run_report to size a broad query before a full fetch. Pass propertyId, metrics, dateRanges, and optionally dimensions and filters. GA4 hard limits: at most 4 dateRanges, 10 metrics, and 9 dimensions per request.

google_analytics_estimate_report_rows

Estimate reach for TikTok targeting without creating a campaign or spending ad budget. Use to size a proposed audience. Requires accountId, objectiveType, optimizationGoal and locationIds (TikTok ids, e.g. Germany 2921044). Optional ageGroups, gender, languages, interests, behaviors, audienceIds/excludedAudienceIds, placements and operatingSystem. Get interest ids from tiktok_ads_search_targeting; do not combine interestKeywordIds with purchaseIntentionKeywordIds. Get audience ids from tiktok_ads_audience_insights. Returns lowerEnd/upperEnd and userCountStage: 1 too narrow, 2 narrow, 3 balanced, 4 fairly broad. Relay this disclaimer verbatim when presenting estimates: "estimated audience size does not include audiences under 18 years of age; ad delivery as permitted by applicable laws is not affected".

tiktok_ads_estimate_audience_size

Forecast impressions, clicks, CTR, average CPC and cost for keywords at a bid and match type. DataForSEO supplies estimates, not connected-Account performance; no Google Ads Connection is required. bid and monetary results use USD. Pass keywords, bid and match for a fresh forecast; optionally dateInterval and target-market location/language. The server does not infer market targeting from an Account. Results expire after 24 hours. For stored pages/re-sorting, pass resultId with page/pageSize/sortBy and omit all fresh-forecast inputs. Stored paging does not refetch data; after expiry request a new forecast.

research_estimate_ad_traffic

Returns one saved HYPD prompt template as user-viewable text, selected by key. It does not execute the template, access an ad platform, or change data. Use when the user names a prompt to run, or to fetch the prompt the user picked after hypd_show_prompt_library listed keys without its table. To browse or pick a prompt, use hypd_show_prompt_library instead.

prompt_templates_get

Search accessible Google Ads Accounts and live report presets for explicit composer attachments. Search does not fetch report metrics.

hypd_resources_search

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_advertisers

Find the location ids a Microsoft Advertising (Bing Ads) campaign targets, from Microsoft's own locations file. Pass accountId and queries (names, each looked up on its own: "Germany", "Berlin", or with its broader places, "Paris, France"), or locationIds to read locations back by id. Each match has its id, its full name (most to least specific), its type (Country, State, MetroArea, City, County, PostalCode) and its status: target Active ones; PendingDeprecation ones stop within 30 days, and Microsoft refuses Deprecated ones. Optional types narrows the matches, limit caps them per query. Use the ids in microsoft_ads_draft_campaign_build.

microsoft_ads_find_locations

Find domains competing with a specified domain in Google organic search, with keyword overlap, average position, and estimated traffic value. These are third-party estimates, not Google's official competitor list or Google Ads auction competitors. For a new lookup, provide domain without a scheme, port, path, query, or fragment (e.g. "acme.com") and omit resultId. Specify the target search-market country and language, reusing known Account context where appropriate; ask the user if unknown. The server does not infer these values from a Google Ads Account, and no Google Ads Connection is required. Returns paginated rows and a resultId for a temporary result that expires after 24 hours. To read another page without fetching again, provide resultId with optional page and pageSize; omit domain, location, language, and limit. Does not modify advertising Accounts or campaigns.

competitors_for_domain

Find ideas from 1-20 seed keywords, with search volumes, competition and bid metrics. Specify target-market location and language; omitted values use provider defaults, not Account-derived targeting (Google backend defaults to United States/English). Ideas come from Google Keyword Planner when the user has a usable Google Ads Account and from DataForSEO otherwise; either way they are market estimates, not that Account's campaign performance. Fresh results are stored for 24 hours. For paging/re-sorting, pass resultId plus page/pageSize/sortBy and omit keywords/location/language; paging does not fetch fresh provider data. Re-run the fresh lookup after expiry.

research_find_keywords

Report sessions, total users, conversions, total revenue, and average session duration by sessionCampaignName and sessionSourceMedium, ordered by sessions descending. Use to evaluate acquisition campaign outcomes in GA4; filter to paid traffic when needed. This preset does not return ad spend or ROAS, or join Google Ads campaign records. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.

google_analytics_get_campaign_performance

Report conversions, total revenue, and sessions grouped by sessionDefaultChannelGroup and sessionCampaignName, ordered by conversions descending. Use to compare conversion outcomes across session channels and campaigns. Aggregate rows only; it does not return multi-step conversion paths or assisted-conversion credit. Pass propertyId and dateRanges; optionally a dimensionFilter and limit.

google_analytics_get_conversions_by_channel_and_campaign

Report items viewed, items added to cart, items purchased, and item revenue by itemName, ordered by item revenue descending. Use to compare product engagement and sales. This preset does not group by source or campaign or return transaction counts. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.

google_analytics_get_ecommerce_performance

Report sessions, total users, engagement rate, average session duration, conversions, and total revenue by landingPagePlusQueryString, ordered by sessions descending. Use to evaluate entry pages, including their query strings, for landing-page and post-click quality questions. Pass propertyId and dateRanges; optionally a dimensionFilter and limit. Dimensions and metrics are preset.

google_analytics_get_landing_page_performance

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

google_analytics_get_property_details

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_account_overview

Standard performance for an Account, Campaigns, Ads, Keywords, Search Terms or Bidding Strategies, with fixed columns. Choose reportType: customer, campaign, ad_group_ad, keyword, search_term, dsa_search_term or bidding_strategy. Rows total the date window and sort by cost. Use dateRange (default LAST_30_DAYS) or startDate + endDate together. limit defaults to 250, max 10000; truncated means more rows existed. additionalMetrics adds valid metrics.* fields; Google rejects unknown names. Rows use dotted GAQL names and raw Google units: cost_micros, average_cpc and cost_per_conversion are micros (divide by 1000000 for Account currency); conversions_value is already in currency. Use googleAdsId from google_ads_list_accounts. Use google_ads_run_gaql for custom filters, segmentation or other resources.

google_ads_get_report

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. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId.

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. For fresh searches, specify location and language from known market context or ask the user; never omit location or assume worldwide. Omit both when paging with resultId. Results combine Google data with third-party aggregated data.

serp_results

LinkedIn Ads metrics over a date range, grouped by 1-3 pivots: CAMPAIGN_GROUP, CAMPAIGN, CREATIVE or firmographics such as MEMBER_JOB_TITLE, MEMBER_SENIORITY, MEMBER_INDUSTRY, MEMBER_COMPANY_SIZE and MEMBER_COUNTRY_V2. A LinkedIn campaign group corresponds to a Meta campaign; a LinkedIn campaign to a Meta ad set. Pass accountId, pivots, up to 20 camelCase metric fields and startDate/endDate. Resolve pivot URNs with linkedin_get_object or list tools. costInLocalCurrency uses the LinkedIn ad account currency. Results are not paginated, with a provider cap around 15000 rows: narrow dates or add entity filters. Demographic rows lag 12-24h, suppress counts under 3 events and are approximate; prefer timeGranularity ALL because daily sums can undercount. Call sequentially and chunk long date ranges to manage account-wide throttling.

linkedin_analytics

SEE an actual ad from a connected LinkedIn Ads Account — LinkedIn's Accurate Preview of one creative, rendered exactly as it serves. Pass accountId (from linkedin_list_ad_accounts) and the numeric creativeId (the digits of urn:li:sponsoredCreative:<id>, from linkedin_get_creatives). Returns one preview per placement (desktop and mobile feed): previewUrl is a linkedin.com/ads/ad-preview link — Share it so the user can open the rendered ad in their browser. Links expire after ~3 hours; re-call for a fresh one instead of storing it, and never embed previewUrl or previewHtml in an artifact (the artifact sandbox blocks linkedin.com, so it renders blank there — the link is for the user to click). Works for single image, carousel, video, single job and event ads, INCLUDING drafts and unserved creatives the public Ad Library never indexes. Requires the connected member to hold any role on the LinkedIn Ads Account (VIEWER is enough). Issue LinkedIn reads sequentially, not in parallel.

linkedin_get_ad_preview

Estimate how many LinkedIn members a targeting definition reaches — no campaign needed. Use for planning questions like "how many senior marketers in DACH could we reach?". Pass accountId plus include clauses (each clause = one facet URN with its value URNs; clauses are ANDed, values within a clause ORed) and optional exclude clauses. Common facets: urn:li:adTargetingFacet:locations (values urn:li:geo:...), seniorities (urn:li:seniority:...), industries (urn:li:industry:...), staffCountRanges (urn:li:staffCountRange:...), titles (urn:li:title:...). Returns total targetable members; `active` is null because LinkedIn no longer populates it — never report an active-member count. A total of 0 also means "under 300" — LinkedIn reports audiences below its 300-member privacy floor as zero, so say "under 300", not "nobody".

linkedin_audience_count

List the campaign groups in a LinkedIn Ads account. TERMINOLOGY: a LinkedIn campaign group is the top budget/schedule container — it corresponds to what Meta and Google call a "campaign", so when the user says "my LinkedIn campaigns" they often mean campaign groups. Pass accountId from linkedin_list_ad_accounts. Rows are raw LinkedIn campaignGroup objects (id, name, status, runSchedule, totalBudget, ...). Structural data only — for spend and performance use linkedin_analytics. Paginate with pageToken from nextPageToken. Issue LinkedIn reads sequentially, not in parallel.

linkedin_get_campaign_groups

List the campaigns in a LinkedIn Ads account. TERMINOLOGY: a LinkedIn campaign holds targeting, bidding, and format — it corresponds to what Meta calls an "ad set", one level BELOW a campaign group. Pass accountId from linkedin_list_ad_accounts; optionally pass campaignGroupId to restrict to one group. Rows are raw LinkedIn campaign objects (id, name, status, type, targetingCriteria, dailyBudget, ...). Structural data only — for spend and performance use linkedin_analytics. Paginate with pageToken from nextPageToken. Issue LinkedIn reads sequentially, not in parallel.

linkedin_get_campaigns

List individual ads in a connected LinkedIn Ads account, their intended/review status and campaign/content references. Pass accountId from linkedin_list_ad_accounts; optionally restrict with campaignIds. Returns raw creative objects. Resolve campaign URNs with linkedin_get_object. Copy and images are behind content references that this Connection cannot read directly: use the numeric creative id with linkedin_get_ad_preview for a browser preview, including drafts, video and carousel. Served ads may be enriched via linkedin_ad_library_search; its adUrl detail id matches the sponsoredCreative id. For performance, use linkedin_analytics with pivot CREATIVE. Pass nextPageToken as pageToken for subsequent pages. Call LinkedIn tools sequentially.

linkedin_get_creatives

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_product_performance

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.

merchant_center_get_product_status

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

Get the creative for a single Meta ad: headline, primary text, call to action, destination link and media. Use when the user wants to review ad copy and creative or check the landing URL. Pass accountId (act_<digits> from meta_list_ad_accounts) and adId (from meta_get_ads); optionally adFormat to choose the placement rendered in preview_url (defaults to MOBILE_FEED_STANDARD). Media thumbnails are returned inline (up to 12 per call); each media entry also carries url (full-resolution, signed, expires within hours) and permalink_url (stable link). preview_url opens the rendered ad in the browser. Paginate with pageSize and nextPageToken.

meta_get_creative

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_adsets

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_ads

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_campaigns

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_catalog_diagnostics

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_activities

Meta Ads performance: spend, impressions, reach, clicks, CTR, CPC, CPM, conversions and ROAS. Use for performance questions about a Meta ad account, campaign, ad set or ad. Requires accountId (act_<digits> from meta_list_ad_accounts), level (account/campaign/adset/ad) and either since + until (YYYY-MM-DD) or datePreset. Example: {"accountId":"act_123","level":"campaign","since":"2026-06-01","until":"2026-06-30"}. objectId defaults to the Meta ad account; set it for one campaign, ad set or ad. breakdowns segment metrics (e.g. publisher_platform, age, gender, country); fields selects metrics. Monetary values use the Meta ad account currency returned by meta_list_ad_accounts. Returns raw metrics without server-side analysis. After a rate-limit error, call sequentially and retry after the indicated wait.

meta_insights

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 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_get_recommendations

Read shared negative keyword lists in a Microsoft Advertising (Bing Ads) account: each list's negative keywords (itemId, text, matchType) and the campaigns it is attached to (campaignIds). Pass accountId and listIds (up to 20) from microsoft_ads_list_negative_keyword_lists. The item ids are what microsoft_ads_draft_negative_keyword_list_changes removes.

microsoft_ads_get_negative_keyword_lists

Asset group performance report for Microsoft Advertising (Bing Ads) PerformanceMax campaigns: spend, impressions, clicks, CTR, average CPC, conversions, cost per conversion, revenue, and ROAS per asset group. This is the performance view for PMax — the campaign/keyword reports cover other campaign types. Pass accountId plus startDate/endDate (YYYY-MM-DD). Aggregation 'Summary' (default) returns one totals row per asset group; 'Daily' adds a TimePeriod column. Values arrive as strings exactly as Microsoft reports them (some include % signs). The report runs asynchronously upstream and can take up to a minute; narrow the date range if it times out.

microsoft_ads_get_asset_group_performance

Campaign performance report for a Microsoft Advertising (Bing Ads) account: spend, impressions, clicks, CTR, average CPC/CPM, conversions, conversion rate, cost per conversion, revenue, and ROAS. Pass accountId plus startDate/endDate (YYYY-MM-DD). Aggregation 'Summary' (default) returns one totals row per campaign; 'Daily' adds a TimePeriod column with per-day rows. Values arrive as strings exactly as Microsoft reports them (some include % signs). The report runs asynchronously upstream and can take up to a minute; narrow the date range if it times out.

microsoft_ads_get_campaign_performance