Ad campaign management

pinterest_ads_async_report#

Pinterest deep (async) ad report read-only

The DEEP Pinterest ad report — Pinterest’s ASYNCHRONOUS lane, which reaches 914 DAYS back (2.5 years) where pinterest_ads_report stops at 90, and carries roughly three times the metric columns (conversion, ROAS and cross-device families the quick report does not have). Use it for anything older than three months, and for revenue questions. Levels: ADVERTISER / CAMPAIGN / AD_GROUP / PIN_PROMOTION / KEYWORD / PRODUCT_GROUP / PRODUCT_ITEM plus their *_TARGETING twins. Pinterest generates it asynchronously, so this may come back pending:true with a token — CALL AGAIN WITH THAT TOKEN to pick it up, and never re-submit without it (a second submit generates a second report). Pinterest’s own windows are enforced here with the reason rather than as an opaque 400: 914 days back over at most 186 days; at HOUR granularity 8 days back over 3; at a PRODUCT_ITEM level 92 back over 31. A finished report link is valid five minutes and the report one hour, so an EXPIRED status means run it again, not that anything failed. Read-only, 0 credits.

pinterest_targeting_analytics#

Pinterest ads by audience segment read-only

WHICH AUDIENCE SEGMENT actually delivered on Pinterest — ad performance broken down by keyword, targeted interest, age bucket, gender, location, region, country, placement, app type, media type and more. targetingTypes is REQUIRED because it is what the report breaks down BY. scope:"account" covers the whole ad account; "campaign" / "adGroup" / "ad" each REQUIRE their own id list, because Pinterest publishes no all-of-them form at those levels — that is Pinterest’s shape, not a limitation here. 90 days back in windows of at most 90 days, refused locally with the reason. An unknown targeting type is refused BY NAME; note Pinterest’s four per-level enums differ slightly, so a value valid at one level can still be refused at another. Read-only, 0 credits.

pinterest_audience_insights#

Pinterest audience insights read-only

WHO the Pinterest audience IS, rather than what it did — interest categories each carrying an affinity INDEX, plus demographics (ages, countries, devices, genders, metros). Three audiences: YOUR_TOTAL_AUDIENCE, YOUR_ENGAGED_AUDIENCE, and PINTEREST_TOTAL_AUDIENCE as the baseline to compare the other two against. This is an input to a creative brief, not a performance report. SAY THIS WHEN REPORTING: an affinity index is how much MORE likely this audience is to engage with a category than Pinterest’s baseline — it is a comparison, never a count — and when Pinterest flags size_is_upper_bound the audience size is an upper bound, not a measurement. There is no date range: Pinterest returns its current snapshot and names the date it is for. Read-only, 0 credits.

search_pinterest_ads_targeting#

Find Pinterest ad targeting options read-only

THE IDS AN AD GROUP’S targetingSpec NEEDS. create_pinterest_ads_campaign and create_pinterest_ads_ad_group accept interests, locales, locations, age buckets and keywords — this is where those values come from, and guessing one is the worst option available: Pinterest ACCEPTS a well-formed but wrong interest id and the campaign then quietly targets the wrong people. Pass targetingType (INTEREST, GEO, LOCATION, LOCALE, AGE_BUCKET, GENDER, APPTYPE, KEYWORD, AUDIENCE_INCLUDE, AUDIENCE_EXCLUDE) and optionally `query` to narrow the list. INTERESTS ARE A TREE: pass interestId instead to drill into one and get its children, which is how you get from "Food" to something specific enough to target. Pinterest publishes no search parameter of its own, so `query` filters the full list HERE — the note says so, because a filter we applied is not a filter the vendor applied. Read-only, 0 credits, no new permission (it uses ads:read, already granted).

create_meta_ad#

Build a full Meta ad (campaign → ad set → ad, paused)

Build a complete, ready-to-run Meta ad: campaign → ad set (FULL targeting + budget + schedule + bidding) → creative → ad(s), ALL created PAUSED — it spends NOTHING until you activate the campaign with set_meta_campaign_status(confirm:true). This is the "create a campaign and put the ads on it" path. IMAGE, VIDEO (uploaded, transcoded and thumbnailed for you) and CAROUSEL (format:"carousel", 2–10 cards each with its own headline/description/link) all work. Targeting is the `targeting` object: geo down to cities with a radius, age, gender, interests, behaviours, custom audiences and lookalikes, languages, placements, devices and OS. For a conversion objective pass pixelId + conversionEvent and the ad set optimizes for that conversion. Schedule with startTime/endTime + dayparting; bid with bidStrategy + bidAmountUsd/minRoas; use lifetimeBudgetUsd (with endTime) for a fixed flight. Attach to an existing campaign with campaignId or an existing ad set with adSetId. Everything is READ BACK from Meta before you are told it exists — print the returned summary verbatim (it now carries Meta-rendered PREVIEW LINKS for the first ad, valid 24 hours — hand them to the user so they can see the ad; preview_meta_ad renders any ad in any placement). Needs ads-management on the connected account. BOOST AN EXISTING POST: pass boostPostId — a post you have ALREADY published (numeric id, the <pageId>_<postId> form, or a permalink) — INSTEAD of any creative, and the ad promotes that post exactly as published, comments and all. Meta ignores creative overrides on an existing post, so message/headline/cta/link do NOT apply; targeting, budget, schedule, bidding and PAUSED-by-default all work identically. Find ids with list_meta_posts. AN INSTAGRAM POST NEEDS boostTarget:"instagram" — an IG media id and a Facebook post id are both bare digits, so Hermoso will NOT guess which one you meant, and a Facebook boost given an IG media id is refused rather than built against a fabricated id. Instagram eligibility is checked for free before anything is created (Meta refuses to boost a post carrying licensed music or an interactive element).

create_meta_adset#

Create a Meta ad set (audience + budget + schedule)

Create an AD SET on an EXISTING Meta campaign — the level that holds the audience, budget, schedule and bidding. Use it to hang SEVERAL ad sets off ONE campaign, which is how you actually test audiences on Meta (one ad set per audience, same campaign, same creative). Takes the same full `targeting`, pixelId/conversionEvent, bidStrategy, schedule and budget fields as create_meta_ad. Created PAUSED and read back from Meta. It has NO ads until you call create_meta_ad(adSetId:…).

find_meta_audiences#

Look up Meta targeting ids read-only

Look up the Meta targeting ids you need before building an ad set — interests, behaviours, cities/regions/zips/DMAs, languages, employers, job titles and schools. type:"adinterest" (q:"yoga") returns interest ids + audience size; type:"adTargetingCategory" with class:"behaviors" returns behaviour ids; type:"adgeolocation" (q:"Toronto", optionally locationTypes:"city") returns the geo KEYS that go in targeting.geo.cities/regions/zips; type:"adlocale" (q:"french") returns language ids for targeting.locales. Read-only and free. Use it whenever the user names an audience in words — never guess an id.

list_meta_ads#

List Meta campaigns / ad sets / ads read-only

Read the EXISTING campaigns, ad sets, or ads on a connected Meta ad account — id, name, status, budget, objective. Pass adAccountId (from list_meta_pages) and level (campaign|adset|ad). Scope to a parent with campaignId (→ its ad sets/ads) or adsetId (→ its ads), and filter by status (ACTIVE/PAUSED/…). Read-only — use it to inspect an account before editing/deleting, or to answer "what’s running?".

meta_insights#

Meta ad performance metrics read-only

Pull performance INSIGHTS (spend, impressions, reach, clicks, CTR, CPC, CPM, conversions) for a connected ad account, or a specific campaign / ad set / ad. Pass adAccountId (for auth); optionally objectId to scope to one object and level to break the numbers down. BREAKDOWNS are what make the numbers actionable — a flat total says an ad cost $X, never WHO it worked on: pass breakdowns:"age,gender", "publisher_platform,platform_position" (which placement), "country" / "region" / "dma" (where), "impression_device" / "device_platform" (what they held). Comma-separated; "placement", "device" and "geo" are accepted as aliases; an unknown value is REJECTED, never silently ignored. THREE breakdowns need an ad-account OPT-IN from 2026-08-06 — impression_device, hourly_stats_aggregated_by_audience_time_zone and frequency_value: Meta returns NO ROWS (not an error) for an account that has not opted in, so they are always ATTEMPTED, and if nothing comes back the report is re-run WITHOUT them and `droppedBreakdowns` + a note name the missing dimension and say an account admin can enable it in Ads Manager. A dropped dimension is ABSENT, never zero — never present the remaining total as if it were still split by it. Date window: datePreset OR since+until (YYYY-MM-DD). datePreset is Meta's OWN enum — today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_week_mon_today, this_week_sun_today, last_week_mon_sun, last_week_sun_sat, this_month, last_month, this_quarter, last_quarter, this_year, last_year, maximum, data_maximum. THERE IS NO "lifetime": Meta disabled it in Graph API v10.0 and replaced it with "maximum" (the last 37 months); anything unrecognised is refused by name here rather than 400ing at Meta. Read-only.

preview_meta_ad#

Preview a Meta ad exactly as it will appear read-only

Render a REAL preview of a Meta ad, per placement — Meta returns a link that shows exactly what a person scrolling Facebook or Instagram would see. Pass adAccountId + adId (from list_meta_ads), or creativeId. Optional placements (comma-separated): facebook_feed, facebook_feed_desktop, facebook_story, facebook_reels, facebook_profile_feed, facebook_marketplace, facebook_right_column, facebook_video_feed, instagram_feed, instagram_story, instagram_reels, instagram_explore, instagram_profile_feed, messenger_inbox, messenger_story, audience_network — default facebook_feed + instagram_feed + instagram_story + instagram_reels. Free, read-only, spends nothing. THE LINKS EXPIRE AFTER 24 HOURS — always say so when handing them to a user. Use it straight after create_meta_ad, and whenever someone wants to approve an ad before it runs.

estimate_meta_reach#

Estimate how many people a Meta audience reaches read-only

Ask Meta how many people a targeting spec can actually reach — BEFORE any budget is committed. Two ways: pass adSetId to size an ad set you already built (Meta uses its own saved targeting), or pass the same `targeting` object you would give create_meta_ad (plus optional objective / optimizationGoal / country / pixelId) to size an audience you are considering. Returns the monthly-active range, a daily-active estimate, and an explicit warning when the audience is too narrow to deliver. Free, read-only, creates nothing and spends nothing. Use it before recommending a budget and every time the user narrows a geo or piles on interests.

list_meta_audiences#

List Meta custom audiences + lookalikes read-only

List the custom audiences and lookalikes on a connected Meta ad account — id, name, type, approximate size, and whether Meta says it is ready to target. Call it before create_meta_audience (so you never build a duplicate) and before targeting one: the ids go straight into create_meta_ad’s targeting.customAudiences / excludedCustomAudiences. Read-only, free.

create_meta_audience#

Create a Meta custom audience or lookalike

Build a retargeting audience on a connected Meta ad account. Three kinds: kind:"website" (people whose visited URL contains urlContains, seen by pixelId — pass the brand’s own domain for "all visitors"; retentionDays up to 180), kind:"engagement" (people who did `event` on the brand’s Facebook Page, or its Instagram business profile with source:"instagram"; retentionDays up to 730), or kind:"lookalike" (sourceAudienceId + country + ratio 0.01–0.20, lookalikeType "similarity" or "reach"). CREATING AN AUDIENCE SPENDS NOTHING — it is a definition; money only moves when an ad set targets it and that campaign is activated through set_meta_campaign_status(confirm:true). Meta needs roughly 30 minutes and ~1,000 people before a new audience can be targeted, so a fresh one reporting no size is normal. Customer-list uploads are deliberately NOT supported here (hashed personal data + Meta’s Custom Audience Terms) — send the user to Ads Manager for those.

list_meta_pixels#

List Meta Pixels on an ad account read-only

List the META PIXELS on one of the brand’s ad accounts — id, name, when it was created, and WHEN IT LAST FIRED. This is where the pixelId every conversion tool needs comes from: create_meta_ad takes it (with conversionEvent) to optimise an ad set for OFFSITE_CONVERSIONS instead of link clicks, and create_meta_audience needs it to build a website retargeting audience. Without this tool that id could only be read off a screen in Events Manager. READ lastFiredAt BEFORE YOU TRUST A PIXEL: one that has NEVER FIRED is not installed on the site, so an ad optimising against it will spend and never learn. Pass includeCode:true to get the <script> snippet for installation (it is long, so it is off by default). Read-only, free.

create_meta_pixel#

Create a Meta Pixel

Create a META PIXEL on one of the brand’s ad accounts, so their ads can optimise for real website conversions instead of link clicks and so website retargeting audiences become possible. A pixel is a DEFINITION: it cannot serve, cannot spend, and RECORDS NOTHING until its snippet is installed on the site — the reply hands back that snippet and says so. TWO THINGS TO SAY OUT LOUD BEFORE CALLING IT: Meta allows exactly ONE pixel per ad account (a second attempt is refused and Hermoso will name the one that already exists — so call list_meta_pixels first), and Meta publishes NO WAY TO DELETE a pixel, so this is permanent. Creating it spends nothing.

list_meta_lead_forms#

List Meta instant (lead) forms read-only

List the INSTANT LEAD FORMS on a connected Facebook Page — id, name, status, how many leads each has collected and what each one asks. This is where the formId every other lead tool needs comes from, and calling it before create_meta_lead_form is how you avoid building a duplicate. Read-only, free. NEEDS the pages_manage_ads permission, which Hermoso’s Meta consent screen asks for. If Meta answers "Requires pages_manage_ads", the user must RECONNECT Meta under Settings ▸ Connectors ▸ Meta — a connection made before that permission was added cannot gain it by retrying. Call the tool rather than pre-refusing: any refusal comes from Meta and names the one thing that fixes it.

create_meta_lead_form#

Create a Meta instant (lead) form

Create an INSTANT LEAD FORM on a connected Facebook Page — the in-app form a Meta lead ad opens instead of sending someone to a website, which is why lead ads convert far better than a landing page on mobile. `questions` takes Meta’s own type names, e.g. ["FULL_NAME","EMAIL","PHONE"]; for anything bespoke pass {type:"CUSTOM", label:"What size fleet do you run?"} and add options:[…] to make it a dropdown. Ask FEWER questions than you think — every extra field costs completions. privacyPolicyUrl is REQUIRED: the form collects real people’s contact details and has to say where their data goes. Optional: headline, contextCard {title, bullets[], buttonText} for the why-should-I screen, thankYou {title, body, buttonType, buttonText, websiteUrl}, locale, followUpActionUrl. CREATING A FORM SPENDS NOTHING and publishes nothing — it is invisible to the public until an ad points at it (create_meta_ad with objective:"OUTCOME_LEADS" + leadFormId), and that ad is created PAUSED. Read the submissions with read_meta_leads. NEEDS pages_manage_ads — see list_meta_lead_forms for what to do if Meta refuses it.

archive_meta_lead_form#

Archive (or restore) a Meta instant form destructive

Retire an INSTANT LEAD FORM so it stops collecting — the only way to tidy a Page’s Instant Forms list, because META DOES NOT SUPPORT DELETING A LEAD FORM AT ALL, only archiving it. This is REVERSIBLE: pass status:"ACTIVE" to switch an archived form back on. Archiving publishes nothing, spends nothing and DELETES NO LEADS — everything the form already collected stays readable with read_meta_leads. CALL IT WITHOUT confirm FIRST: nothing changes and you get the form’s real name, current status and lead count READ BACK FROM META, so you can show the user exactly which form they are about to retire rather than echoing back an id they may have mistyped; then call again with confirm:true. WARNING WORTH RELAYING BEFORE ARCHIVING: if a live ad still points at this form, its button will open nothing — check the ad first. The new status is READ BACK from Meta after the change, so the summary reports what Meta actually stored and says plainly when the change did NOT take; print it verbatim rather than assuming a successful call means a changed form.

read_meta_leads#

Read Meta lead-ad submissions read-only

Read the LEADS a form (formId) or a single ad (adId) has collected — the real answers people submitted, fetched live from Meta. THIS RETURNS REAL PEOPLE’S CONTACT DETAILS (names, emails, phone numbers). Treat it as the user’s own customer data: show only what they asked for, never post a lead list anywhere public, and do not copy it into an unrelated document. Hermoso PULLS these on demand and keeps no copy — nothing here watches, polls or files leads anywhere, so if the user wants this batch kept, put it somewhere THEY own in the same turn (a Google Sheet with create_sheet / append_to_sheet, a doc, or their own CRM). Meta makes each lead available for 90 days after it is submitted; anything older is handled in Meta’s own Leads Center and CRM integrations. Narrow with since/until (ISO dates), page with cursor, or pass redact:true to see counts, timestamps and which ad produced each lead WITHOUT the personal details. NEEDS leads_retrieval — see list_meta_lead_forms for what to do if Meta refuses it.

delete_meta_audience#

Delete a Meta custom audience destructive

PERMANENTLY delete a Meta custom audience or lookalike. Meta’s own warning: "When you delete a custom audience, it will be permanently removed from your account and your ads using it will stop running." An audience is the one ad object whose value is its CONTENTS — a big retargeting list cannot be rebuilt, it has to re-accumulate — so CALL IT WITHOUT confirm FIRST: nothing is deleted, and you get its real name, how many people are in it and which lookalikes were built from it, read live from Meta. Show the user exactly that. A populated audience, or one with lookalikes, then needs confirmName set to its exact name (and confirmChildren set to the lookalike count when there are any). META REFUSES to delete an audience that has lookalikes derived from it (error 2656) — delete those first; the unconfirmed call names them. Pass adAccountId + audienceId (from list_meta_audiences). The result is READ BACK from Meta: it says deleted only when the id no longer resolves.

register_merchant_developer#

Register Hermoso with a Merchant Center account

ONE-TIME SETUP, and the FIRST thing to run when Merchant Center calls are being refused. Google blocks every Merchant API call until Hermoso's Google Cloud project is registered against the merchant's account, and says so verbatim ("GCP project ... is not registered with the merchant account"). This performs that link. It is NOT a broken connection and reconnecting cannot fix it. Google asks for up to 5 minutes afterwards before the API starts answering.

list_merchant_accounts#

List Merchant Center accounts read-only

List the Google Merchant Center accounts this brand's connected Google account can reach. EVERY other Merchant tool needs the merchantCenterId this returns, and an agency often has several, so never guess one — ask the user which store. Read-only and free. If it is refused, the Merchant Center permission has not been granted yet; that is not a broken connection and reconnecting will not change it.

No parameters.

list_merchant_products#

List Merchant Center products read-only

Read the products in a Merchant Center feed — what the merchant actually offers, which is what Shopping and retail Performance Max campaigns serve. Needs merchantCenterId from list_merchant_accounts. Read-only and free.

list_merchant_promotions#

List Merchant Center promotions read-only

The sale and discount promotions on a Merchant Center account, with each one's PER-DESTINATION status and any issues Google has raised against it. GOOGLE VALIDATES PROMOTIONS ASYNCHRONOUSLY, so 'created' and 'running' are different states and only destinationStatuses tells them apart — never report a sale as live off a successful create. Read-only, 0 credits. Needs Google Ads connected (Merchant Center rides the same connection).

create_merchant_promotion#

Create a Merchant Center promotion (sale badge)

PUT A SALE BADGE ON THE MERCHANT'S SHOPPING LISTINGS — the most seasonal thing a retail advertiser does, and until now unreachable through Hermoso. It creates the promotion and resolves (or creates) the promotion DATA SOURCE that country/language needs automatically; a promotion data source is its own kind and cannot be the product feed. IT IS NOT LIVE ON CREATE: Google validates promotions asynchronously and can take days to approve one, so report it as SUBMITTED and re-read with list_merchant_promotions. Everything Google marks Required is refused up front by name, including the pairings its own 400 does not mention — PERCENT_OFF needs percentOff, MONEY_OFF needs moneyOffAmount, GENERIC_CODE needs genericRedemptionCode — because otherwise Google accepts the promotion and disapproves it hours later where nobody is watching. 0 credits.

merchant_issue_help#

Google's own fix steps for a Merchant Center issue read-only

GOOGLE'S OWN FIX STEPS, not just the name of the problem. list_merchant_issues stops at the symptom; this returns the remediation content Google writes for each issue, plus the ACTIONS available on it — request a review, claim the website, edit a named attribute — with the exact opaque ids trigger_merchant_issue_action needs. Pass an offerId (with feedLabel, and contentLanguage if it is not 'en') for one PRODUCT's issues, or leave it off for the ACCOUNT's. The fix text is Google's and is relayed verbatim: RELAY IT, do not paraphrase a remediation step into something that sounds simpler. Read-only, 0 credits.

trigger_merchant_issue_action#

Fire a Merchant Center issue action

FIRE one of the actions merchant_issue_help returned — most usefully 'request a review' on a disapproval. SEVERAL OF THESE ARE ONE-SHOT and Google says so in its own dialog callout ('You can only request a review for disagreeing with this issue once. If it's not approved, you'll need to fix the issue and wait'), so read that callout back to the user before confirming: a review spent on the wrong issue cannot be spent again. WITHOUT `confirm` IT FIRES NOTHING. `actionContext` is OPAQUE by Google's own instruction — pass it back exactly as merchant_issue_help gave it; it cannot be constructed or edited. The answer is Google's own message to the business, relayed verbatim, because this endpoint returns no resource to read back. 0 credits.

list_merchant_inventory#

Merchant store and region overrides read-only

The per-store and per-region price and availability overrides on one Shopping product. An override REPLACES the product's own price and availability for that store or region; where there is no override the product-level values apply, so an empty result is the normal answer and does NOT mean the product is missing. Needs the product's offerId plus its contentLanguage and feedLabel, because in the Merchant API those three together ARE the product's address rather than optional filters. Read-only, free.

set_merchant_inventory#

Set store or region price and stock

SET the price, availability or stock level of one Shopping product at ONE physical store (kind:"local", keyed by storeCode) or in ONE region (kind:"regional", keyed by region). This is what stops a Shopping ad advertising something the nearest store has sold out of. Google's insert REPLACES the whole entry, so this tool reads what is already stored, merges your fields over it, and reports which stored fields it preserved; pass an explicit null to CLEAR one. The API publishes no enum for availability, so it accepts anything and only Google's local inventory data specification says which values actually serve: In stock, Limited availability, On display to order, Out of stock, submitted in English. An unrecognised value is warned about here rather than refused, because refusing would mean inventing an enum Google does not publish. Google states it can take up to 30 minutes before the product itself reflects the change, so a product read straight afterwards can still show the old value and be correct. Free.

merchant_account_status#

Merchant Center serving status read-only

WHY THE MERCHANT CENTER ACCOUNT IS OR IS NOT SERVING, in one read. Do not trust the program state on its own: an account can report Shopping ads and free listings as ENABLED and serve in ZERO countries, because Google counts a region as active only where every requirement for that program is met. This reports the active regions, the unmet requirements Google names with its own help link for each, and then the eight account settings that explain them — whether the homepage is CLAIMED (unclaimed stops the whole account serving), whether business info has an address, a verified phone and a customer service contact, whether any active shipping service covers the countries you sell to, the return policies, whether the Merchant Center terms have been accepted, plus autofeed and automatic improvements. An account with no shipping settings at all is reported as not configured, which is an account state and not a failed read. Anything that genuinely could not be read comes back null with a warning, which means unknown rather than missing. Read-only, free.

merchant_quota#

Merchant Center quota and limits read-only

Merchant Center API quota and account limits, which is the difference between "the API refused" and "you are out of daily quota". Two different things in one answer: quota groups are how many API CALLS each method group has left today, and account limits are how many PRODUCTS the account may hold per destination. Google resets the daily quota at 12:00 PM MIDDAY UTC, not at midnight. If one half of the read fails it comes back null with a warning, which means unknown rather than zero. Read-only, free.

manage_merchant_notifications#

Merchant Center push notifications

PUSH INSTEAD OF POLLING for Merchant Center product status. Google POSTs to a URL the moment a product's status changes — a disapproval is otherwise found whenever someone happens to run list_merchant_issues, which for a feed of thousands means money burning unnoticed. action:'list' shows the subscriptions, 'create' adds one, 'delete' removes one. BE HONEST ABOUT WHERE IT GOES: callBackUri must be an HTTPS endpoint THE MERCHANT runs and can decode — Hermoso does not receive these notifications, so this only helps someone with a server on the other end. 0 credits.

manage_merchant_conversion_source#

Merchant Center conversion sources destructive

WHERE MERCHANT CENTER GETS ITS CONVERSION DATA FROM, which is what free-listing and Shopping performance reporting is built on — a merchant with no conversion source sees clicks and no outcomes, and nothing in Merchant Center says why. Two kinds, and they are different jobs: a MERCHANT CENTER DESTINATION is a Google tag target, and creating one returns a destination id (MC-…) that is the only place that id exists, so it must be read back to the user because it is what the Google tag has to send conversions to. A GOOGLE ANALYTICS LINK pulls conversions from a GA4 property instead, needs the connected Google account to be an ADMIN on that property, and Google marks it IMMUTABLE — the property cannot be changed afterwards, only deleted and re-created. action:'list' shows every source including archived ones, 'create' adds one, 'update' changes a destination's name, currency or attribution, 'delete' ARCHIVES one (confirm-gated) and 'undelete' restores it until the expiry Google reports on the archived row. Attribution lookback is 7, 30 or 40 days and nothing else. Free.

list_merchant_data_sources#

List Merchant Center product feeds read-only

List the data sources (feeds) on a Merchant Center account and say which of them can actually take a product write. Do this BEFORE creating or deleting a product: writes go into a data source, and Google only accepts them into an API-input product feed — a file feed, the feed Merchant Center's own UI creates, and an autofeed all list here and all REFUSE writes, so picking the first row would pick a feed that cannot be written to. Needs merchantCenterId from list_merchant_accounts. Read-only and free.

create_merchant_data_source#

Create a Merchant Center product feed

Create an API product feed on a Merchant Center account — the container upsert_merchant_product writes into. Most accounts have none until one is made: a store set up through the Merchant Center UI has a UI feed, which is read-only. feedLabel and contentLanguage must be set TOGETHER or not at all and BOTH ARE IMMUTABLE — leave them off and the feed accepts products for any market and language, which is the safer default because a wrong feed label can never be corrected. Omit destinations to inherit wherever the account already sells. Creating a feed costs nothing and cannot spend.

upsert_merchant_product#

Create or replace a Merchant Center product destructive

Create or replace a product in a Merchant Center feed — this is how a merchant's catalogue gets populated, and it is what Shopping ads, free listings and retail Performance Max actually serve. It is an UPSERT and a WHOLE-ROW write: calling it again for the same offerId REPLACES the product rather than patching it, so send every field you want kept each time. You do not have to find a feed first — omit dataSource and it resolves the account's one writable feed, creates one if there is none, and REFUSES by name if there are several rather than putting the product in a market the campaigns may not target. offerId, contentLanguage and feedLabel together ARE the product's identity and are all immutable; contentLanguage and feedLabel are taken from the feed when the feed declares them. For the product to serve at all Google needs title, description, link, imageLink, availability and price — a row missing any of them is stored and then disapproved, and the reply says so rather than letting you believe it published. The reply reports what GOOGLE STORED, not what was sent. Free: a feed edit cannot spend.

delete_merchant_product#

Delete a Merchant Center product destructive

Delete a product from a Merchant Center feed. CONFIRM-GATED: without confirm:true nothing is deleted and it reports the real product it WOULD delete — title, price and availability read back from Google — because the id you were given proves nothing about what is actually there. It is recoverable: re-inserting the same offerId re-creates the product. Needs the same offerId + contentLanguage + feedLabel that identify the product (contentLanguage and feedLabel come from the feed when it declares them). Free.

update_merchant_product#

Update fields on a Merchant Center product

Change SOME fields on a product already in a Merchant Center feed — the everyday operation, because price and availability move daily. This is a PATCH: only the attributes you name are touched and everything else on the product survives, which is the difference from upsert_merchant_product (a whole-row write that wipes anything you leave out). It refuses if the product does not exist rather than quietly creating a half-populated one, and it refuses an empty change rather than sending an update mask with nothing behind it. The reply reports every field Google now holds, so you can see what survived. Free.

delete_merchant_data_source#

Delete a Merchant Center product feed destructive

Delete a data source (feed) from a Merchant Center account. CONFIRM-GATED and the heavier of the two deletes: without confirm:true nothing is deleted and it reports the feed plus HOW MANY PRODUCTS would be destroyed with it, counted live from Google. This is NOT recoverable the way a product delete is — the products would have to be re-inserted into a new feed, and feedLabel/contentLanguage are immutable so a replacement may not be identical. Free.

list_google_ads_campaigns#

List Google Ads accounts / campaigns read-only

Read the connected Google Ads account(s). Call with NO customerId to list the accessible accounts (customerId + name + currency) — do this first to pick a target. Call WITH customerId to list that account’s campaigns (id, name, status, daily budget, channel) plus performance metrics (impressions, clicks, CTR, avg CPC, cost, conversions). Date window: datePreset (LAST_7_DAYS | LAST_30_DAYS | TODAY | THIS_MONTH | LAST_90_DAYS …) or since+until (YYYY-MM-DD). Read-only, free. Needs Google Ads connected (Settings ▸ Connectors ▸ Google Ads).

google_ads_report#

Google Ads GAQL report read-only

Run a GAQL (Google Ads Query Language) report for detailed performance breakdowns — ad groups, ads, keywords, search terms, demographics, geo. Pass customerId + a GAQL query (SELECT … FROM <resource> WHERE segments.date DURING LAST_30_DAYS). Allowed FROM resources: campaign, ad_group, ad_group_ad, keyword_view, campaign_budget, age_range_view, gender_view, geographic_view, search_term_view. cost_micros is micros — divide by 1,000,000 for the account currency. Read-only, free.

google_ads_change_history#

What changed on a Google Ads account, and when read-only

WHAT CHANGED ON THE ACCOUNT, AND WHEN — the answer to "performance fell off a cliff on Tuesday, what happened?", and the Google twin of reddit_ads_history. source:"change_event" (default) is FIELD-LEVEL over the last 30 days: the change time, who made it, from which client (web UI, API, scripts, bulk upload, automated rule), whether it was a CREATE / UPDATE / REMOVE, and exactly which fields moved — with detail:true it also carries the old and new resource snapshots. source:"change_status" reaches 90 days and is the ONLY one that catches GOOGLE ADS EDITOR and criterion-level edits: Google documents change_event as NEVER returning Editor changes, so an Editor-managed account looks completely untouched there. CHECK BOTH BEFORE TELLING ANYONE NOTHING CHANGED. An unknown source is refused by name; the 30/90-day windows and Google’s own 10,000-row cap are enforced here with the reason instead of surfacing as an unreadable Google error, and a change takes up to three minutes to appear. Neither resource carries any metric or segment, so this says what changed, never what it cost. Read-only, 0 credits.

create_google_ads_campaign#

Build a Google Ads campaign (paused)

Build a campaign on a connected Google Ads account. ALWAYS created PAUSED — it spends NOTHING until you enable it with set_google_ads_status(confirm:true). Google's object graph is campaign → ad group → ad, so a campaign ON ITS OWN CANNOT SERVE AN IMPRESSION: pass adGroup{name, ad{headlines,descriptions,finalUrls}, keywords[]} and this builds budget + campaign + location/language targeting + ad group + ad + keywords in ONE ATOMIC operation (if any part is rejected, nothing at all is created — no half-built campaign to clean up). Also here: bidding strategy, locations by NAME ("United States", "Toronto" — resolved for you), languages, and start/end dates. Google requires 3–15 headlines (≤30 chars) and 2–4 descriptions (≤90 chars) on a search ad. Everything is READ BACK from Google before you are told it exists; print the returned note verbatim, and if it says the campaign cannot serve yet, say that rather than calling it a finished ad.

create_google_ads_ad_group#

Add an ad group to a Google Ads campaign

Add an ad group to an EXISTING Google Ads campaign — the level between a campaign and its ads. Google requires it: a campaign with no ad group cannot serve. Optionally build its ad and keywords in the same ATOMIC call. The ad-group type is taken from the campaign's channel automatically. Created PAUSED and read back from Google before you are told it exists. If the parent campaign is already LIVE (ENABLED), creating this ENABLED starts REAL AD SPEND immediately — show the user what would begin serving, get an explicit yes, then pass confirm:true. Leaving it PAUSED never needs confirmation.

create_google_ads_ad#

Create a Google Ads ad

Create the actual AD inside a Google Ads ad group — this is the object that carries the creative; a campaign or ad group alone shows nothing. On a SEARCH campaign it builds a RESPONSIVE SEARCH AD: 3–15 headlines (≤30 chars), 2–4 descriptions (≤90 chars), at least one finalUrl, optional path1/path2. On a DISPLAY campaign it builds a RESPONSIVE DISPLAY AD: headlines, longHeadline, descriptions, businessName plus BOTH a landscape (1.91:1) and a square (1:1) image asset from upload_google_ads_asset. The right format is chosen from the campaign's channel. Created PAUSED and read back from Google. If the parent campaign is already LIVE (ENABLED), creating this ENABLED starts REAL AD SPEND immediately — show the user what would begin serving, get an explicit yes, then pass confirm:true. Leaving it PAUSED never needs confirmation.

add_google_ads_keywords#

Add Google Ads keywords

Add keywords — and NEGATIVE keywords — to a Google Ads ad group. A Search ad group with no keywords never shows. Each keyword takes text (≤80 chars, ≤10 words) and matchType EXACT | PHRASE | BROAD (default PHRASE). Set negative:true to BLOCK a term instead of targeting it, which is the cheapest way to stop wasted spend. Read back from Google before you are told they exist. If the parent campaign and ad group are already LIVE, a positive keyword starts bidding real money at once — get an explicit yes and pass confirm:true, or add it with paused:true. Negative keywords only restrict spend and never need confirmation.

set_google_ads_targeting#

Add Google Ads location & language targeting

ADD locations and languages to an existing Google Ads campaign. THIS ADDS; IT DOES NOT REPLACE — Google campaign criteria are a list, this call only ever creates entries, and there is no remove operation here. So a campaign already targeting the United States that you "change to Canada" ends up targeting BOTH and still spending in the US; the read-back names every pre-existing location and language it kept, and you MUST relay that rather than reporting the new total as the answer. Removing targeting is done in Google Ads (Campaign ▸ Settings ▸ Locations). Pass locations by NAME ("United States", "California", "Toronto") — they are resolved to Google's geo target ids for you; excludedLocations adds a NEGATIVE criterion (the reliable way to stop serving somewhere from here); languages takes ISO codes ("en","fr"). A campaign with NO location targeting runs WORLDWIDE, which is the most expensive default in Google Ads. Changing a LIVE campaign's targeting moves real spend immediately, so that needs confirm:true.

set_google_ads_bidding#

Set a Google Ads bidding strategy

Change how an existing Google Ads campaign bids: MANUAL_CPC (optionally enhanced), MAXIMIZE_CLICKS (needs maxCpcUsd on an existing campaign — Google requires the CPC ceiling on that change), MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_CPA (needs targetCpaUsd) or TARGET_ROAS (needs targetRoas, e.g. 4 = $4 revenue per $1 spent). TARGET_CPA and TARGET_ROAS are applied as Google's own v25 equivalents — maximize-conversions with a target CPA, and maximize-conversion-value with a target ROAS — so the read-back reports them as MAXIMIZE_CONVERSIONS / MAXIMIZE_CONVERSION_VALUE; report what the read-back says. The conversion-based strategies only deliver once conversion tracking is configured on the account. Changing a LIVE campaign's bidding changes what it pays immediately, so that needs confirm:true.

find_google_ads_locations#

Look up Google Ads locations read-only

Look up Google Ads location targets by name — turns "Toronto" / "California" / "United Kingdom" into the geo target ids Google needs, with each one's type (COUNTRY, STATE, CITY, POSTAL_CODE…) and reach. Use it when a location name is ambiguous, or to show the user exactly which place you are about to target. Read-only and free.

set_google_ads_budget#

Set a Google Ads campaign budget

Create a new daily budget, or change an existing budget’s daily amount (pass budgetResourceName). Raising the budget on a LIVE (ENABLED) campaign increases real spend immediately — you MUST show the user the new daily amount, get an explicit yes, then call with confirm:true. Creating a budget or lowering one on a paused campaign is safe.

set_google_ads_status#

Enable, pause or remove a Google Ads campaign / ad group / ad destructive

Turn a campaign, AD GROUP or AD ON (ENABLED), OFF (PAUSED) or REMOVED. Pass level:"campaign" + campaignId, level:"adGroup" + adGroupId, or level:"ad" + BOTH adGroupId and adId (Google keys an ad by adGroupId~adId). ENABLING STARTS REAL AD SPEND — you MUST first show the user the campaign name + its daily budget, get an explicit yes, then call with status:"ENABLED" and confirm:true. Pausing is always safe. REMOVED is PERMANENT in Google Ads and is handled by the same gate as delete_google_ads_object — call it once WITHOUT confirm to see what goes with it, and expect to echo back the object’s name and child count when it has children, is live, or has spent. The resulting status is READ BACK from Google before you are told it took.

delete_google_ads_object#

Remove a Google Ads campaign / ad group / ad / keyword / asset link / conversion action destructive

PERMANENTLY remove a Google Ads object. Google has no HTTP delete — removal is a `remove` operation that puts the object in the terminal REMOVED state, which cannot be undone or re-enabled, so treat it as a delete. Levels: "campaign" + campaignId · "adGroup" + adGroupId · "ad" + adGroupId AND adId · "keyword" + adGroupId AND keywordId · "conversionAction" + conversionActionId · "campaignAsset"/"adGroupAsset" + the LINK’s full resourceName (get it from google_ads_report over campaign_asset / ad_group_asset — an asset id alone does not identify a link). THERE IS DELIBERATELY NO "asset" LEVEL: Google publishes no operation that deletes an Asset, only its links, so removing a link unlinks the asset and leaves it in the library. CALL IT WITHOUT confirm FIRST — nothing is removed and you get the object’s real name, status, LIFETIME SPEND and child counts read live from Google; show the user exactly that. A target with children, live delivery or real spend additionally needs confirmName (its exact name) and confirmChildren (the child count from that read-back). Removing a CAMPAIGN also removes its campaign-owned budget, and the note says whether it did. Removing the last ENABLED conversion action makes every smart-bidding campaign on the account undeliverable — the refusal says so. To stop delivery without removing, use set_google_ads_status(status:"PAUSED").

upload_google_ads_asset#

Upload a creative to Google Ads

Add a creative to a Google Ads account’s ASSET LIBRARY so it can be used in ads. It does NOT have to be a Hermoso render — the user’s own creative is the normal case; the URL just has to be Hermoso-HOSTED because we fetch the bytes, so run any file of theirs through upload_file and pass the URL it returns. For an IMAGE, pass imageUrl (≤5MB); an arbitrary external/CDN URL is refused. For VIDEO, Google Ads uses YouTube-hosted videos — post the video to YouTube as UNLISTED first (post_to_youtube with privacy:"unlisted" — link-only, not public or searchable, and unlike "private" it CAN run as an ad), then pass its youtubeVideoId here. Returns the asset resource name. Pass customerId (from list_google_ads_campaigns).

create_google_ads_conversion_action#

Create a Google Ads conversion action

Create a CONVERSION ACTION — the thing that tells Google what counts as a result on this account. This is a PREREQUISITE, not a nicety: MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_CPA, TARGET_ROAS and every Performance Max campaign are undeliverable without one, because Google has nothing to optimise toward. type WEBPAGE (a purchase / lead / signup on the site — the normal choice), UPLOAD_CLICKS or UPLOAD_CALLS; every other Google conversion type (Firebase, Google Analytics 4, Floodlight, store visits) is READ-ONLY and is created in those products, not here. Set category to what actually happened (PURCHASE, SUBMIT_LEAD_FORM, SIGNUP, BOOK_APPOINTMENT…) and defaultValueUsd when a conversion has a known worth — TARGET_ROAS has nothing to maximise without a value. Created ENABLED and counted in "conversions" by default, because a conversion action that is neither records nothing. It CANNOT SERVE AN AD and cannot spend a cent, so it needs no confirmation. A WEBPAGE action records NOTHING until its Google tag is installed on the site — say that when you report it.

list_google_ads_conversion_actions#

List Google Ads conversion actions read-only

List the conversion actions on a Google Ads account and say plainly whether smart bidding can work there. Call this BEFORE proposing MAXIMIZE_CONVERSIONS / MAXIMIZE_CONVERSION_VALUE / TARGET_CPA / TARGET_ROAS or any Performance Max campaign: an account with no ENABLED conversion action that counts toward "conversions" cannot optimise on any of them, and the campaign would spend its budget without ever learning. Shows each action’s status, type, category, counting type, and whether it counts toward "conversions". Read-only, free.

add_google_ads_assets#

Add sitelinks / callouts / structured snippets to a Google Ads campaign

Add SITELINKS, CALLOUTS or STRUCTURED SNIPPETS to a Google Ads campaign or ad group — and ATTACH them, which is the part that makes them do anything (an asset sitting in the account library shows nothing at all). Sitelinks are the highest-CTR free win on Search: extra links under the ad, each with its own landing page. Pass assetType plus assets[]: SITELINK needs {linkText (≤25 chars), finalUrl, and optionally description1 / description2}; CALLOUT needs {calloutText (≤25)}; STRUCTURED_SNIPPET needs {header, values[] — at least 3}. Or link assets that already exist with assetResourceNames[]. Assets and links go up in ONE atomic operation, so a rejected link never strands an orphan asset, and the links are READ BACK from Google before you are told they exist. Attaching a live asset to a LIVE (ENABLED) campaign changes what that ad shows on the very next auction — show the user what would appear, get an explicit yes, then pass confirm:true. On a paused campaign it never needs confirmation.

create_google_ads_performance_max_campaign#

Create a Google Ads Performance Max campaign

Build a PERFORMANCE MAX campaign — Google’s cross-surface campaign type (Search, YouTube, Display, Discover, Gmail, Maps) and the one Google pushes hardest at small advertisers. ALWAYS created PAUSED; it spends NOTHING until you enable it with set_google_ads_status(confirm:true). PMax has NO manual bidding and NO keywords: it bids only on conversions, so the account MUST already have a conversion action — check with list_google_ads_conversion_actions, because this REFUSES rather than build a campaign that cannot optimise. Creative lives in an ASSET GROUP, and Google’s minimums are enforced before anything is sent: 3–15 headlines (≤30 chars), 1–5 longHeadlines (≤90), 2–5 descriptions (≤90), one businessName (≤25), at least one LOGO (1:1), one MARKETING_IMAGE (1.91:1) and one SQUARE_MARKETING_IMAGE (1:1) — upload the images with upload_google_ads_asset first and pass their asset resource names. A YouTube video is optional (Google generates one from the asset group if you omit it). Brand guidelines: since Google Ads API v21 they are ON by default for new PMax campaigns, which means the businessName and LOGO assets are linked to the CAMPAIGN (CampaignAsset), not to the asset group — Hermoso does that for you. Leave brandGuidelinesEnabled alone unless the user wants the older asset-group layout, and pass false for that. Budget, campaign, location/language targeting, the asset group and every asset link go up in ONE ATOMIC operation — if any part is rejected, nothing at all is created — and the whole tree is READ BACK from Google before you are told it exists. Print the returned note verbatim; if it says the campaign cannot serve, say that instead of calling it finished. RETAIL/SHOPPING: pass merchantCenterId (from list_merchant_accounts) to make it a Shopping-feed Performance Max — it then advertises the WHOLE feed (one root listing group); feedLabel narrows it to a single feed. Partitioning the feed by brand/category/custom label is NOT built and is refused by name, so a caller can never believe they narrowed it when they did not.

google_ads_keyword_ideas#

Keyword ideas with real Google search volume read-only

Google’s own KEYWORD PLANNER: real keyword ideas with average monthly search volume, competition level and top-of-page bid estimates, so keyword choices are measured instead of guessed. Seed it with keywords[] (terms you already have), url (one landing page to mine) or site (a whole domain — the fastest way to size a competitor). Narrow by locations (place NAMES, resolved for you) and language. Results come back sorted by monthly volume. Use this BEFORE add_google_ads_keywords or create_google_ads_campaign so the ad group targets terms people actually search, and quote the volumes when you propose them. Read-only, free, spends nothing and creates nothing.

list_analytics_properties#

List the GA4 properties shared with this brand read-only

The GA4 properties SHARED WITH THIS BRAND, with their numeric property ids, display names and the Analytics account each sits under. CALL THIS FIRST — every other Analytics tool needs a PROPERTY ID, which is NUMERIC (e.g. 123456789) and is NOT the "G-XXXXXXX" Measurement ID people usually know from their tracking snippet; the API accepts the numeric id and nothing else. Resolve the property yourself from this list instead of asking the user to go and find one, and only ask when two names are genuinely ambiguous. THIS IS NOT EVERY PROPERTY THE GOOGLE ACCOUNT CAN SEE, deliberately: Analytics access is handed out freely, so one login often has Viewer on many different clients' properties, and the user ticks which ones belong to THIS brand. Only ticked properties can be reported on, and any other one is refused by name. An empty list means nothing is ticked yet — say so and point the user at Settings ▸ Connectors ▸ Google Analytics ▸ Manage accounts (or call list_connector_accounts / set_connector_accounts with provider "google_analytics"); never name or guess a property. Read-only, 0 credits. Needs Google Analytics connected (Settings ▸ Connectors ▸ Google Analytics).

No parameters.

analytics_report#

Run a GA4 report read-only

WHAT HAPPENED ON THE SITE — the GA4 Data API report, and the tool that answers "where is our traffic coming from", "which campaign converted", "which landing page is working". Pass metrics by name (activeUsers, sessions, screenPageViews, conversions, totalRevenue, engagementRate, bounceRate, averageSessionDuration …) and dimensions to break them down by (sessionDefaultChannelGroup, sessionSource / sessionMedium / sessionCampaignName, landingPage, pagePath, country, deviceCategory, date, eventName …). GA4 publishes hundreds of both and each property ships its OWN custom dimensions, so names are forwarded as given rather than validated against a copied list — use list_analytics_definitions to see a property's custom ones. THE PROPERTY IS A NUMERIC ID (e.g. 123456789), NOT the G-XXXXXXX Measurement ID — run list_analytics_properties to resolve it. Dates default to the last 28 days and accept either YYYY-MM-DD or GA4's relative forms ("28daysAgo", "yesterday", "today"). Rows come back as flat named objects, and a sampled result says so. Read-only, 0 credits.

analytics_realtime#

Who is on the site right now (GA4 realtime) read-only

WHO IS ON THE SITE RIGHT NOW — GA4's realtime report, covering roughly the last 30 minutes. Use it to see a launch, a post or a campaign landing in real time. IT IS A DIFFERENT REPORT WITH A DIFFERENT METRIC SET, NOT a shortcut for analytics_report: realtime accepts activeUsers, screenPageViews, conversions and eventCount, and REJECTS `sessions` outright — asking for sessions here returns an error, not a zero. Realtime dimensions are also narrower (unifiedScreenName, country, deviceCategory, platform, eventName …) and there is no date range at all. The property is the NUMERIC id from list_analytics_properties, never the G-XXXXXXX Measurement ID. Read-only, 0 credits.

list_analytics_definitions#

List a GA4 property’s key events and custom dimensions read-only

What a GA4 property already MEASURES — its key events (what GA4 counts as a conversion) and its custom dimensions, with each dimension's parameter name and scope. Two reasons to call it: to learn a property's own custom dimension names before using them in analytics_report, and to CHECK BEFORE CREATING — a custom dimension can never be deleted, only archived, and a property is capped at 50 event-scoped ones, so creating a duplicate permanently burns a slot. The property is the NUMERIC id from list_analytics_properties. Read-only, 0 credits.

create_analytics_key_event#

Mark a GA4 event as a key event (conversion)

Mark an event GA4 ALREADY COLLECTS as a KEY EVENT — what GA4 calls a conversion since the 2024 rename (the resource is keyEvents; the old conversionEvents spelling is deprecated). This is what makes an event countable as a result in reports and importable into Google Ads as a conversion. THE EVENT NAME MUST MATCH AN EVENT THE SITE ALREADY SENDS ("purchase", "generate_lead", "sign_up", or a custom one) — marking an event that is never fired creates a key event that can never fire, so check list_analytics_definitions or an analytics_report broken down by eventName first. countingMethod ONCE_PER_EVENT counts EVERY occurrence; ONCE_PER_SESSION counts the event at most ONCE PER SESSION, however many times it fires in that session. Those are the only two GA4 accepts — there is no per-USER counting method, and asking for one is refused rather than quietly counted per event. The result is READ BACK from Google, never echoed from the request. The property is the NUMERIC id from list_analytics_properties. Needs the Google Analytics connection to have edit access on the property.

create_analytics_custom_dimension#

Create a GA4 custom dimension

Register an event parameter the site ALREADY SENDS as a custom dimension, so reports can break down by it (plan tier, content category, logged-in state…). TWO THINGS TO TELL THE USER BEFORE CALLING: a GA4 custom dimension CANNOT BE DELETED — only archived — and a property is capped at 50 EVENT-scoped dimensions, so a duplicate or a typo permanently burns one of them. Call list_analytics_definitions first to see what already exists. GET THE TWO NAMES THE RIGHT WAY ROUND: parameterName is the event parameter GA4 is already collecting (e.g. "customer_tier") and displayName is only the label shown in reports — swapping them silently produces a dimension that always reads "(not set)". Registering a dimension is NOT retroactive: it only collects from the moment it is created. The property is the NUMERIC id from list_analytics_properties. Needs the Google Analytics connection to have edit access on the property.

list_analytics_metadata#

What a GA4 property can be asked read-only

THE VOCABULARY OF ONE PROPERTY — every dimension and metric analytics_report will accept on it, INCLUDING that property's own custom dimensions, each with its api name and its human label. Use this instead of guessing an api name: GA4 publishes hundreds and they are not memorable (sessions broken down by landing page is `landingPage`, revenue is `totalRevenue`, the channel grouping is `sessionDefaultChannelGroup`), and a wrong name is an error mid-conversation rather than a suggestion. analytics_report deliberately forwards names AS GIVEN — it never validates against a copied list, because that list would go stale and start refusing names Google accepts — so THIS is where a name is checked. PASS `search` almost always: unfiltered this returns several hundred rows, and a search matches both the api name and the label ("revenue", "campaign", "device"). Read-only, 0 credits.

archive_analytics_custom_dimension#

Archive a GA4 custom dimension destructive

THE ONLY WAY TO RETIRE A CUSTOM DIMENSION, and it is ONE-WAY. GA4 publishes no delete and no un-archive for custom dimensions anywhere in its API — archiving is permanent through every programmatic surface — so this is how a typo'd or duplicate dimension is cleared, and it also frees the slot it was holding against the 50-event-scoped cap. Reports lose the ability to break down by it. CALLED WITHOUT `confirm` IT ARCHIVES NOTHING and instead reports what the dimension actually is, read back from Google — check that against what the user asked for before confirming, because naming the right dimension is the only thing `confirm` cannot prove. Identify it by its parameterName (the event parameter), which list_analytics_definitions lists. Needs edit access on the property.

delete_analytics_key_event#

Stop counting a GA4 event as a conversion destructive

REMOVE A KEY EVENT — the reverse of create_analytics_key_event, and note the ASYMMETRY with custom dimensions: a key event really can be DELETED, where a custom dimension can only be archived. Nothing is destroyed — GA4 keeps collecting the underlying event and keeps all of its history, this only stops it counting as a conversion, and it can be marked again at any time. Use it for an event marked as a conversion by mistake, or one that should no longer be optimised toward. BE AWARE IT REACHES FURTHER THAN GA4: anything importing this conversion — Google Ads smart bidding in particular — stops receiving it, which changes how campaigns bid. Called without `confirm` it deletes nothing and describes the key event back to you. Needs edit access on the property.

create_analytics_custom_metric#

Register a GA4 custom metric

Register an event parameter the site ALREADY SENDS as a GA4 custom METRIC, so reports can SUM or AVERAGE it. This is the other half of the pair: a custom DIMENSION makes a value something you can group BY, a custom METRIC makes it something you can TOTAL — 'order_value' as a dimension gives you a list of prices, as a metric it gives you revenue. TELL THE USER TWO THINGS BEFORE CALLING: a GA4 custom metric CANNOT be deleted, only archived, and a property is capped at 50 (125 on Analytics 360) — a duplicate or a typo permanently burns a slot, so run list_analytics_definitions first, which lists metrics beside dimensions. measurementUnit IS REQUIRED and is never guessed for you: STANDARD for a plain count or quantity, CURRENCY for money, SECONDS/MINUTES/HOURS for durations. CURRENCY additionally REQUIRES restrictedMetricType (REVENUE_DATA for money coming in, COST_DATA for money going out) and every other unit REFUSES it — both directions are refused before the call is made, because Google's own error names neither field. METRICS ARE EVENT-SCOPED ONLY, unlike dimensions, which take EVENT | USER | ITEM. Not retroactive: it collects from creation onward. The result is READ BACK from Google, never echoed from the request. Needs edit access on the property. 0 credits.

archive_analytics_custom_metric#

Archive a GA4 custom metric (one-way) destructive

THE ONLY WAY TO RETIRE A GA4 CUSTOM METRIC, and it is ONE-WAY: GA4 publishes no delete and no un-archive for custom metrics anywhere in its API, exactly as for dimensions, so archiving is permanent through every programmatic surface. It frees the slot against the 50-per-property cap, and reports lose the ability to sum or average it. WITHOUT `confirm` IT ARCHIVES NOTHING and instead describes the metric read back from Google — check that against what the user asked for before confirming, because naming the RIGHT metric is the one thing confirm cannot prove. Identify it by parameterName (from list_analytics_definitions), not the report label. A custom DIMENSION of the same name is a DIFFERENT resource and needs archive_analytics_custom_dimension. Needs edit access. 0 credits.

check_analytics_compatibility#

Check a GA4 report will work, before running it read-only

FREE PRE-FLIGHT FOR analytics_report — ask Google whether these dimensions and metrics can appear in ONE report together, BEFORE running the report that would fail. Use it whenever a report combines fields you have not combined before, and especially when one of them is a custom dimension: GA4 has real pairs that are each perfectly valid alone and cannot be queried together, and `analytics_report` deliberately forwards names AS GIVEN (GA4 publishes hundreds of dimensions and every property ships its own custom ones, so validating against a copied list would go stale and start REFUSING names Google accepts). Pass EXACTLY what you would pass to analytics_report — same metrics, same dimensions, same filters — and it returns which fields are INCOMPATIBLE so you can drop one and run the real report once. IT DOES NOT CHECK THAT A NAME EXISTS: an unknown api name is refused by Google outright, and list_analytics_metadata is what resolves names. Read-only, 0 credits.

list_analytics_google_ads_links#

Which Google Ads accounts a GA4 property is linked to read-only

Which Google Ads accounts a GA4 property is linked to, and whether each link has PERSONALIZED ADVERTISING on — the flag that decides whether GA4 audiences and remarketing events reach Google Ads at all. RUN THIS BEFORE two claims: that a GA4 audience can be remarketed to, and that a Google Ads campaign's missing conversion data is a Google Ads problem. For a GA4-first advertiser the conversions come from this link, so an unlinked property is the usual cause and no error anywhere says so. Read-only, 0 credits. Needs Google Analytics connected.

link_google_ads_to_analytics#

Link a GA4 property to a Google Ads account

LINK a GA4 property to a Google Ads account. This is the prerequisite for two things users constantly ask for and cannot otherwise have: importing GA4 key events as Google Ads CONVERSIONS — which is what gets a smart-bidding campaign past the conversion-tracking refusal for a GA4-first advertiser — and using a GA4 AUDIENCE for remarketing. RE-LINKING AN ACCOUNT THAT IS ALREADY LINKED IS NOT AN ERROR: it reports that and changes nothing, because this is exactly the call an agent makes when something downstream is not working. adsPersonalizationEnabled DEFAULTS TO TRUE deliberately — a link with it off is the silent dead end where the audience exists in GA4 and never appears in Google Ads, with nothing reporting an error. The connected Google account needs EDIT on the GA4 property AND admin on the Google Ads account; without the second Google refuses and the refusal reads like a Hermoso fault. Google can take 24-48 hours before an audience shows up on the other side. 0 credits.

unlink_google_ads_from_analytics#

Unlink Google Ads from a GA4 property destructive

REMOVE the link between a GA4 property and a Google Ads account. The link itself is trivially re-creatable, which is why this is not a one-way-door gate — but what breaks downstream is not: every campaign bidding on a conversion imported from this property loses that signal, and every remarketing list built from a GA4 audience stops refreshing. WITHOUT `confirm` IT CHANGES NOTHING and reports what is actually attached, read back from Google, including whether it is a MANAGER account (in which case the link covers every account underneath). 0 credits.

list_analytics_audiences#

List the GA4 audiences on a property read-only

The GA4 audiences (remarketing lists) on a property, WITH whether they can actually be used in Google Ads — it reads the Google Ads link state alongside them, because an audience on an unlinked property is a silent dead end that reports no error anywhere. ARCHIVED audiences are not listed, so absence here is not proof one never existed. GA4's PREDEFINED audiences ('All Users', 'Purchasers') ARE returned — verified live against a real property — and they come back with clauseCount 0, because Google defines them internally rather than with filter clauses; that is normal and is not a broken audience. Read-only, 0 credits.

create_analytics_audience#

Build a GA4 audience (remarketing list)

BUILD A GA4 AUDIENCE — a remarketing list defined by what people did on the site, which flows into Google Ads across the property's Google Ads link. TELL THE USER TWO THINGS BEFORE CALLING: GA4 marks the DEFINITION, the MEMBERSHIP DURATION and every filter SCOPE immutable, so a wrong audience is archived and rebuilt rather than edited; and it is NOT retroactive — it starts collecting members from creation onward, and Google takes 24-48 hours to populate it. `filterClauses` is GA4's own nested shape and the TOP level of each filterExpression MUST be a single `andGroup` (Google's schema says so and its rejection names no field). Worked example, 'everyone who fired purchase': [{"clauseType":"INCLUDE","simpleFilter":{"scope":"AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS","filterExpression":{"andGroup":{"filterExpressions":[{"orGroup":{"filterExpressions":[{"eventFilter":{"eventName":"purchase"}}]}}]}}}}]. The result says whether the property is linked to Google Ads, because an audience nobody can remarket to is not a finished job. 0 credits.

list_analytics_data_streams#

GA4 data streams read-only

The GA4 data streams on a property, with the measurement ID (G-...) each one carries and how many Measurement Protocol secrets it already has. THIS IS WHERE A GTAG OR GTM INSTALL GETS ITS ID, and it is the first call before sending any server-side event. A web stream has a measurementId; an app stream has none and uses its firebaseAppId instead, so do not report an app stream as broken for having no G- id. A stream whose secret count could not be read comes back as null, which means unknown and not zero. Read-only, free.

get_analytics_stream_setup#

GA4 install tag and stream settings read-only

THE GTAG SNIPPET TO PASTE, plus what that web stream is actually set to collect. list_analytics_data_streams gives the measurement ID and stops one step short of what someone installing GA4 needs, which is the finished <script> block — Google returns it verbatim and marks it immutable. The same call answers the two questions that come next: whether ENHANCED MEASUREMENT is collecting scrolls, outbound clicks, site search, video, downloads, form interactions and single-page-app page views, and whether client-side REDACTION is stripping emails or query parameters out of recorded URLs. Read the master switch before believing a toggle: if enhanced measurement is off for the stream, every individual toggle is inert whatever it says. WEB STREAMS ONLY — all three resources are web-stream resources, and an app stream is refused by name with what it has instead. Any half that could not be read comes back null, which means unknown and not off. Read-only, free.

manage_analytics_measurement_protocol_secret#

GA4 Measurement Protocol secrets destructive

THE SERVER-SIDE EVENT CHANNEL FOR GA4, the Google twin of the conversions APIs Hermoso already ships for Reddit, Snapchat and OpenAI Ads. A Measurement Protocol secret is the api_secret half of https://www.google-analytics.com/mp/collect; the other half is the stream's measurementId for a web stream or its firebaseAppId for an app stream, and this tool reports whichever applies. action:"list" shows every secret with its value, action:"create" mints one (displayName is required, and it is the ONLY label a secret ever gets because the values are opaque), action:"delete" revokes one and NEEDS confirm:true. TELL THE USER THIS BEFORE THEY DELETE: there is no rotation anywhere in the API, because the value is output-only and patch reaches only the display name. A delete takes effect at once, and anything still sending with the old value stops being recorded SILENTLY, since the Measurement Protocol answers a bad api_secret with a 2xx and drops the hit. Rotating safely means create the new one, move every sender across, then delete the old one. Free.

archive_analytics_audience#

Archive a GA4 audience (one-way) destructive

ARCHIVE a GA4 audience, and it is ONE-WAY: GA4 publishes no delete and no un-archive anywhere in its API. Any Google Ads remarketing list sourced from it stops refreshing, and because the definition is IMMUTABLE the audience cannot be recovered by editing — rebuilding means a NEW audience that starts collecting members from scratch, so months of accumulated membership are gone. WITHOUT `confirm` IT ARCHIVES NOTHING and describes the audience read back from Google; check that against what the user asked for, because naming the right audience is the one thing confirm cannot prove. An ambiguous displayName is REFUSED rather than first-matched — GA4 does not enforce unique names and there is no way back. 0 credits.

manage_analytics_channel_group#

GA4 channel groups destructive

HOW GA4 DECIDES WHICH BUCKET A CLICK LANDS IN, which is the number an ad studio is judged on and the answer to "why is my campaign showing as Unassigned". action:'list' reads every group with its channels in the order GA4 tests them, including Google's own Default channel group — read that first, because a campaign landing in the wrong channel is a rule that does not match rather than missing data. 'create' authors your own group, 'update' changes one, 'delete' removes one (confirm-gated). AUTHORING: `channels` is an ordered list, each with a name and its conditions, and GA4 STOPS AT THE FIRST RULE THAT MATCHES — so a broad rule above a narrow one silently swallows it. A condition is {fieldName, matchType, value} or {fieldName, values:[…]} for a list, plus not:true to invert; an entry that is itself an ARRAY of conditions is OR'ed, and separate entries are AND'ed. THE FIELD NAMES ARE NOT THE REPORT DIMENSIONS: use eachScopeSource, eachScopeMedium, eachScopeCampaignName, eachScopeCampaignId, eachScopeSourcePlatform or eachScopeDefaultChannelGroup — sessionSource, medium and the rest are real GA4 dimensions that Google REFUSES here, and its refusal does not say what to use instead. `primary:true` makes the group the one every report is bucketed by AND unsets whichever group was primary before. Google's own Default channel group cannot be edited and is refused by name. An update REPLACES the whole rule set. Free.

manage_analytics_calculated_metric#

GA4 calculated metrics destructive

THE DERIVED NUMBER A MARKETER ACTUALLY REPORTS — cost per purchase, revenue per session, a margin — built from metrics GA4 already collects and then available to analytics_report like any other metric. action:'list' reads them, 'create' adds one, 'update' changes the formula, name, unit or description, 'delete' removes one (confirm-gated). THE ID IS CHOSEN ONCE AND IS PERMANENT: calculatedMetricId becomes the API name reports ask for (calcMetric:your_id), Google marks it output-only afterwards, and renaming is refused by name rather than silently ignored — so pick it deliberately. The formula takes + - * / and parentheses over metric names and plain numbers, referencing at most 5 unique custom metrics; Google answers a syntax error with the exact position. WATCH invalidMetricReference ON THE WAY BACK: a formula naming a metric this property does not collect is created happily and flagged invalid, and any report using it may fail or return unexpected numbers — report that rather than a clean success. Free.

list_tag_manager_containers#

List the Tag Manager containers shared with this brand read-only

The Google Tag Manager containers SHARED WITH THIS BRAND, with the exact containerPath every other Tag Manager tool needs. CALL THIS FIRST. A container is addressed by PATH, "accounts/<id>/containers/<id>", never by the GTM-XXXXXX public id a human reads off the snippet: no Tag Manager method accepts the public id, so passing one is refused. Each row carries the public id beside the path so you can match what the user says to what the API wants. THIS IS NOT EVERY CONTAINER THE GOOGLE ACCOUNT CAN SEE: one agency login routinely administers every client's container, and a container is not data about a client, it is control of what runs on their website, so the user ticks which containers belong to THIS brand and only those are reachable. An empty list means nothing is ticked yet: say so and point the user at Settings, Connectors, Google Tag Manager, Manage accounts. Never name or guess a container. Read-only, free. Read-only, 0 credits. Needs Google Tag Manager connected.

No parameters.

list_tag_manager_tags#

What is actually firing on the site read-only

WHAT IS ACTUALLY FIRING ON THE SITE. Every tag in the container's workspace with its type, whether it is paused, which triggers fire it by name, and the one field that matters most: whether each tag is LIVE on the website or only STAGED in a draft. Also returns the container's triggers so you can reuse one instead of creating a duplicate. USE THIS TO ANSWER "is conversion tracking actually working": a Google Ads conversion action created by create_google_ads_conversion_action records nothing until a tag in this container fires it, and this is the only way to see whether that tag exists, whether it is paused, and whether it has been published. THREE VALUES FOR live, AND THEY ARE DIFFERENT ANSWERS: true means it is in the published container version and running, false means it is staged and NOT running yet, and null means the published version could not be read so you cannot tell. Never report null as false. If the response says the container has never been published, nothing in it is running at all. Read-only, free. 0 credits. Needs Google Tag Manager connected.

create_tag_manager_tag#

Install a tag in the container draft

INSTALL A TAG in the container's draft workspace: a Google Ads conversion tag, a GA4 event, or a third-party pixel. IT DOES NOT GO LIVE. Everything written here lands in a WORKSPACE, which is a draft, and it does not run on the website until a human opens Tag Manager and publishes the container. Staging NEVER publishes: making a tag live is a separate, explicitly confirmed call (publish_tag_manager_container), because publishing changes what executes for every visitor on the live site. Always tell the user the change is staged, and that it does nothing until it is published. TWO THINGS YOU MUST GET FROM THE CONTAINER RATHER THAN INVENT. (1) type is a Tag Manager type string and Google publishes no machine-readable list of them, so Hermoso forwards whatever you pass rather than validating against a list that would go stale and start refusing real types. Get the right one by calling list_tag_manager_tags and copying the type off a tag of the same kind that already exists, or read it in Tag Manager. (2) firingTriggerId is required and must name at least one real trigger id from list_tag_manager_tags, because a tag with no trigger is installed and never runs, which is worse than not installing it. Use create_tag_manager_trigger if the container has no suitable trigger. 0 credits. Needs Google Tag Manager connected.

update_tag_manager_tag#

Change a tag in the container draft

CHANGE AN EXISTING TAG in the draft workspace: rename it, fix a wrong conversion id or label, move it onto a different trigger, or pause it. Like create_tag_manager_tag this lands in a DRAFT and does not reach the website until a human publishes the container. Hermoso reads the tag first and merges your change on top of it, because Tag Manager's update replaces the whole tag and sending only the changed field would silently strip its parameters and triggers. A tag's type cannot be changed: that is deleting one tag and creating another. If somebody edited the tag in Tag Manager after Hermoso read it the change is REFUSED rather than overwriting their edit, and the fix is to read it again and reapply. To stop a tag running, pause it rather than removing its trigger. 0 credits. Needs Google Tag Manager connected.

create_tag_manager_trigger#

Create a trigger in the container draft

CREATE A TRIGGER, the rule that decides when a tag fires, in the container's draft workspace. Use it when list_tag_manager_tags shows no trigger matching what a conversion needs, for example a purchase confirmation page or a dataLayer purchase event. A trigger on its own fires nothing: it has to be named in a tag's firingTriggerId, so create the trigger, then create or update the tag that uses it. Like every other write here it lands in a DRAFT and does not reach the website until a human publishes the container. type must be one of Tag Manager's own trigger types, and an unrecognised one is refused by name with the accepted list, for free, before any request. A customEvent trigger with no customEventFilter fires on EVERY dataLayer event in the container rather than the one you meant, so that is refused too. 0 credits. Needs Google Tag Manager connected.

list_tag_manager_versions#

Tag Manager version history read-only

THE CONTAINER'S VERSION HISTORY, and the thing to read before proposing to publish or to roll one back. Every version with its id, its name, how many tags, triggers and variables it holds, whether it is archived, and which one is LIVE on the site right now. This is what makes a publish reversible: pass a row's path as publish_tag_manager_container's versionPath to put that version back on the site. The live flag is three-valued — true, false, or null when Google would not tell us which version is live, and null must never be read as false. Read-only. 0 credits. Needs Google Tag Manager connected.

preview_tag_manager_publish#

What would go live read-only

WHAT WOULD HAPPEN IF YOU PUBLISHED — free, read-only, and it publishes nothing. Returns the container, the version live on the site right now and what it holds, the exact list of staged changes (added, updated, deleted) as Tag Manager itself reports them, any merge conflicts, and the one sentence to show a user before asking them to agree. Use it to answer 'what is waiting to go live?' without going anywhere near the publish call. publish_tag_manager_container without confirm returns the same facts, so this is for when you want them with no chance of a publish at all. 0 credits. Needs Google Tag Manager connected.

publish_tag_manager_container#

Publish the container to the live site destructive

PUBLISH THE CONTAINER — the ONE call in Hermoso that changes what runs on the customer's live website for every visitor, immediately. Everything else in Tag Manager is staged; this is not. TWO STEPS UNDER THE HOOD, because Tag Manager publishes a VERSION and not a workspace: Hermoso turns the draft workspace into a version and then publishes that version. CALLING IT WITHOUT confirm PUBLISHES NOTHING and is the correct first move: it returns what is live right now, how many tags, triggers and variables that live version holds, and exactly what would change — read back from Google, not echoed from your request. Show the user that, get an unambiguous yes, then call again. THE GATE SCALES WITH THE DAMAGE. A container that has NEVER been published has nothing that currently works and nothing this can break, so confirm:true alone is enough. A container that ALREADY has a live version is replacing something that works, so it additionally needs confirmPublicId set to that container's GTM-XXXXXXX public id — the id printed on the snippet installed on the website. It cannot be guessed; read it from list_tag_manager_containers or from the preview. IT REFUSES, FOR FREE AND WITHOUT PUBLISHING, in four cases you should relay rather than retry: merge conflicts in the workspace (somebody changed the same thing in the container — resolve in Tag Manager first), a workspace with no changes at all, a version Google reports a COMPILER ERROR in, and a container whose public id could not be read. TO UNDO A PUBLISH, publish the previous version again: pass versionPath (from list_tag_manager_versions) and no workspace is involved at all. The reply names the version that was live before this call in rolledBackTo for exactly that purpose, so a publish is reversible. READ verified BEFORE YOU TELL ANYONE IT IS LIVE. It is three-valued: true means the container's live version was re-read and IS the one just published; false means Google accepted it but something else is live, which can be Tag Manager's own read lag and must be reported as unconfirmed; null means the read-back could not run, so it is not known — never report false or null as published. TWO THINGS THAT SURPRISE PEOPLE: creating the version DELETES the draft workspace it was made from (Tag Manager's own behaviour) and opens a fresh empty one, whose id is in the reply, so any workspace id you were holding is stale afterwards. And publishing needs the PUBLISH right on the container in Tag Manager, Admin, User Management, which is separate from Edit — an account that can stage a tag can still be refused here, and that is a permission on the container, not a broken connection. 0 credits. Needs Google Tag Manager connected.

list_posthog_projects#

List the PostHog projects this key can see read-only

The PostHog projects the connected personal API key can see, and which ONE this brand is pointed at. Only the ACTIVE project is readable. That is deliberate: PostHog's API otherwise falls back to "the last project you visited in the UI", which would make every answer depend on the user's browsing history, so Hermoso pins a project at connect time instead of relying on their implicit default. To move this brand to a different project, the user reconnects PostHog under Settings ▸ Connectors ▸ PostHog with that project id. Read-only, 0 credits.

No parameters.

posthog_query#

Ask PostHog a question in HogQL read-only

ASK POSTHOG A QUESTION IN HogQL — their SQL dialect over the `events`, `persons` and `sessions` tables. This is the lane for per-user funnels, retention and any breakdown GA4 cannot express, e.g. `SELECT properties.$current_url, count() FROM events WHERE event = '$pageview' AND timestamp > now() - INTERVAL 7 DAY GROUP BY 1 ORDER BY 2 DESC`. IT IS NOT AN EXPORTER AND MUST NEVER BE LOOPED — PostHog's own policy, verbatim: "Third-party connectors must use batch exports, not /query. Connectors built on /query are not supported and will be rate-limited or rejected." Ask ONE bounded question. Do not paginate it, do not schedule it, and do not call it repeatedly to assemble a whole table; if the user genuinely needs bulk data, tell them to set up a PostHog batch export. Every query is capped at 1000 rows, and OFFSET is refused outright because PostHog returns HTTP 400 for it on API keys — use keyset pagination on `timestamp` (events) or `id` (persons) if a second page is truly needed. Read-only, 0 credits.

posthog_insight#

Read a saved PostHog insight (funnel / retention / trend) read-only

Read back an insight the user already BUILT in their PostHog UI — funnels, retention curves, trends and paths. Call with NO id to LIST the saved insights with their names and ids; call with insightId for that insight's definition and computed result. THIS IS THE RIGHT WAY TO ANSWER A FUNNEL OR RETENTION QUESTION when the report already exists, and the reason is a documentation fact rather than a preference: PostHog's typed query kinds (FunnelsQuery, RetentionQuery, PathsQuery) are undocumented — their own docs say those "are mostly used to power PostHog internally and are not useful for you" and publish no request payload, no field table and no example for any of them, so building on them would be a private API that can change without notice. The two supported routes are HogQL (posthog_query) and a saved insight (this). Read-only, 0 credits.

list_posthog_session_recordings#

List PostHog session replays read-only

SESSION REPLAYS — the capability GA4 has no equivalent of at all. Lists recent recordings with who they belong to, how long they ran, how many clicks / keypresses / CONSOLE ERRORS each had, the URL they started on, and a link that opens the replay in PostHog. USE THE SIGNALS RATHER THAN JUST LISTING THEM: a session with console errors and a high keypress count on a checkout page is a bug report with a video attached, and that is the insight worth surfacing. THE RAW REPLAY IS NOT AVAILABLE OVER THE API — PostHog's words: "This endpoint does not provide the raw JSON of the replays. To get the raw JSON, you need to click Export as JSON in the replay options menu in-app." So describe and link; never promise a download and never claim to have watched one. Links need the user's own PostHog login. A publicly shareable link is minted in the PostHog UI and deliberately not by an agent, because it publishes a real person's session and PostHog themselves say they "make no guarantees about sensitive information contained in the recording". Read-only, 0 credits.

posthog_persons#

Look up people in PostHog read-only

Look up PEOPLE in PostHog by distinct id, email or a free-text search, with their properties. This is the per-user half GA4 cannot do: resolve a specific customer, then use their distinct id inside posthog_query to see exactly what that one human did. Read-only, 0 credits.

mixpanel_insights#

Read a saved Mixpanel report read-only

READ BACK A SAVED MIXPANEL REPORT by its bookmark id — and this is the PREFERRED Mixpanel lane, not a fallback. Mixpanel has put BOTH its Segmentation and its Funnels query APIs in maintenance mode and recommends in their place that the report is built in the Mixpanel UI and read programmatically through Insights, which is exactly what this does. THE BOOKMARK ID MUST COME FROM THE USER: Mixpanel publishes no endpoint that lists saved reports, so ask them to open the report in Mixpanel and copy the id out of its URL (the part after "report-"). Remember Mixpanel allows only 60 QUERIES PER HOUR across its entire Query API — the tightest budget of any connector here — so reuse an answer rather than re-asking. READ BACK dateRange, do not assume the window: a saved report's date range is configured in Mixpanel's own UI and not by this call, and it comes back stamped with the PROJECT's UTC offset — the only place this connector can observe that timezone at all. Read-only, 0 credits.

mixpanel_retention#

Mixpanel retention cohorts read-only

MIXPANEL RETENTION — how many of the people who did a first thing came back and did another, cohorted by day / week / month. This endpoint is FULLY SUPPORTED, unlike segmentation and funnels, which Mixpanel has put in maintenance mode — so it is the one typed Mixpanel report to reach for first. retentionType "birth" cohorts people by their FIRST occurrence of bornEvent (new-user retention, and Mixpanel's DEFAULT); "compounded" counts anyone active. ⚠️ MIXPANEL REQUIRES bornEvent WHENEVER retentionType IS "birth", AND BIRTH IS THE DEFAULT — so a call with neither is refused HERE, for free, rather than spending one of the sixty hourly queries on their 400; use list_mixpanel_events first to name a real event. TWO FILTERS, NOT ONE: bornWhere filters who ENTERS the cohort, where filters the RETURNING event. And interval is the WIDTH of each bucket while intervalCount is HOW MANY of them — different knobs. Dates are YYYY-MM-DD and BOTH ENDS ARE INCLUSIVE, resolved in the PROJECT's timezone (UTC unless its owner changed it) rather than in yours. 60 queries/hour across the whole Query API (5 concurrent) — the tightest budget of any connector here, so widen a range rather than looping over days. Read-only, 0 credits.

mixpanel_segmentation#

Mixpanel event segmentation (maintenance mode) read-only

One Mixpanel event over time, optionally broken down by a property (`on`) and filtered (`where`). ⚠️ MIXPANEL HAS PUT THIS ENDPOINT IN MAINTENANCE MODE — their words: "We recommend discontinuing new use of this endpoint. To break down and filter event data, build an Insights report in-app and query it programmatically with the Insights Query API." It still answers today, which is why it is offered rather than withheld, but SAY SO when you use it and prefer mixpanel_insights whenever the user can build the report. It takes ONE event name and not an array (the /events endpoints take an array; this one does not — an easy and silent mistake). 60 queries/hour across the whole Query API. Read-only, 0 credits.

mixpanel_funnel#

Read a saved Mixpanel funnel (maintenance mode) read-only

A saved Mixpanel funnel. Call with NO id to LIST the saved funnels and their ids; call with funnelId to read its conversion data. ⚠️ MIXPANEL HAS PUT THE FUNNELS QUERY API IN MAINTENANCE MODE — their words: "We recommend discontinuing new use of this endpoint. To get funnel data, build a Funnels report in-app and query it programmatically with the Insights Query API." So prefer mixpanel_insights with that report's bookmark id; this is offered because it still answers and because it is the only way to LIST a project's funnels. `length` IS BOUNDED AT 90 DAYS, WHICH IS NOT THE NUMBER 90: it counts lengthUnits, so 90 days is 2160 hours or 129600 minutes, and an over-long window is REFUSED BY NAME rather than trimmed — silently shortening it would answer a different question with nothing to show that it had happened. Omit both and Mixpanel uses whatever the funnel was saved with in its own UI, which is usually what you want. Dates are YYYY-MM-DD and BOTH ENDS ARE INCLUSIVE, resolved in the PROJECT's timezone (UTC unless its owner changed it) rather than in yours. 60 queries/hour across the whole Query API (5 concurrent) — the tightest budget of any connector here, so widen a range rather than looping over days. Read-only, 0 credits.

list_mixpanel_events#

List Mixpanel events (or one event’s properties) read-only

The EVENT VOCABULARY of the Mixpanel project — the most common event names over THE LAST 31 DAYS, so a query names something the project actually records rather than a guess. Start here before any other Mixpanel call. Pass `event` to list THAT event's top property names instead; the two are different questions with different answers, and a failure to read properties is reported AS a failure and never as "this event has no properties". Pass window "today" for Mixpanel's separate today-only endpoint, which carries counts and the percent change from yesterday — that is a DIFFERENT and far narrower question, and on a quiet project (or simply early in the project's own timezone day) it legitimately returns nothing while the project still records dozens of event types, so NEVER read an empty today answer as "this project has no events". 60 queries/hour across the whole Query API (5 concurrent) — the tightest budget of any connector here, so widen a range rather than looping over days. Read-only, 0 credits.

amplitude_segmentation#

Amplitude event segmentation read-only

AMPLITUDE EVENT SEGMENTATION — an event over time, with filters and group-bys. metric is uniques / totals / pct_dau / average / histogram / sums / value_avg / formula (and "formula" additionally REQUIRES `formula`, or Amplitude refuses it). Dates take YYYY-MM-DD or YYYYMMDD. AMPLITUDE'S RATE LIMIT IS COST-BASED, not per-request: cost = days × conditions × query type, 1000 per 5-minute window, so one very wide query can exhaust the budget on its own — the fix for a 429 here is to NARROW the range or the conditions, not to retry. AN EMPTY RESULT IS A VALID ANSWER, not a failure: a new or low-traffic Amplitude project genuinely has no data, and reporting that as a broken connection sends the user to fix something that is working. Read-only, 0 credits.

amplitude_funnel#

Amplitude funnel (conversion + drop-off) read-only

AMPLITUDE FUNNELS — the richest documented funnel surface of any analytics connector here, and the reason Amplitude is worth reaching for on a conversion question. Pass `events` as an ORDERED array of at least two steps. mode is ordered / unordered / sequential. conversionWindowSeconds is how long a user has to complete the funnel and DEFAULTS TO 2,592,000 SECONDS (30 DAYS) — ALWAYS state which window a conversion rate was measured over, because a 30-day window makes a funnel look dramatically healthier than a same-session one and the difference is invisible in the number itself. At most ONE group-by: segmentation allows two, funnels do not, and a second is refused by name rather than silently dropped. Returns step-by-step and cumulative conversion plus median and average transition times. Read-only, 0 credits.

amplitude_retention#

Amplitude retention read-only

AMPLITUDE RETENTION — of the people who did startEvent, how many came back and did returnEvent. The two magic values are "_new" (first-time users) and "_active" (any active user), which is what makes "new-user retention" a single call. retentionMode is n-day / bracket / rolling, and "bracket" additionally REQUIRES `brackets` — it is refused without them rather than silently switched to another mode, because a retention curve computed under a different definition than the one asked for is a wrong answer that looks right. Read-only, 0 credits.

amplitude_active_users#

Amplitude active / new users read-only

Amplitude ACTIVE or NEW user counts over a date range — the top-line "is the product growing" number, and the cheapest Amplitude call to run first after connecting because it proves the credential with no setup. metric is "active" or "new"; interval 1 daily, 7 weekly, 30 monthly. An empty series on a new project is the CORRECT answer and means the connection works and there is no data yet — never report it as a failure. Read-only, 0 credits.

amplitude_user_activity#

One person’s Amplitude activity stream read-only

ONE PERSON'S ACTIVITY STREAM in Amplitude — the per-user lane, and the kind of question GA4 cannot answer at all. Pass a user id, device id or user-id PREFIX and it SEARCHES; pass a numeric Amplitude ID and it returns that user's recent events with their properties. Two steps, because Amplitude splits them across two endpoints: search resolves a human-typed identifier to an Amplitude ID, and only that id reads an activity stream. NOTE these two endpoints sit on a DIFFERENT rate limit from the rest of Amplitude — flat counts (10 concurrent, 360 queries/hour) rather than the cost model — so they do not consume the segmentation budget and are not protected by it either. Read-only, 0 credits.

list_amplitude_events#

Amplitude taxonomy (declared events and properties) read-only

The Amplitude TAXONOMY — the project's declared events, event properties, user properties or group properties, so a query names something real instead of a guess. category is event (default) / category / event-property / user-property / group-property. IF AMPLITUDE REFUSES THIS, REPORT THEIR REFUSAL AND MOVE ON. The Taxonomy API is widely believed to require an enterprise/Govern entitlement, but Amplitude documents no such gating on either the taxonomy page or the Dashboard API page (both checked), so a 403 here is surfaced as AMPLITUDE'S OWN message and is never presented as a Hermoso plan rule, as a broken connection, or as a fact about the user's plan that we cannot actually know. Every other Amplitude tool is unaffected by that refusal. Read-only, 0 credits.

amplitude_chart#

Read a saved Amplitude chart read-only

READ BACK A SAVED AMPLITUDE CHART by its id — the chart the user already built in Amplitude's own UI, with whatever segments, filters and date range they configured there. This is Amplitude's equivalent of posthog_insight and mixpanel_insights, and it is the right lane whenever the report already exists: you inherit their definitions instead of rebuilding them from a segmentation query, and it costs one call rather than several. THE CHART ID MUST COME FROM THE USER — Amplitude publishes no endpoint that lists a project's charts — and it is the segment after '/chart/' in the chart's URL (e.g. 'abc123' in https://analytics.amplitude.com/demo/chart/abc123); pasting the whole URL works too. THE RESPONSE SHAPE VARIES BY CHART TYPE, in Amplitude's own words, so read what comes back rather than assuming a series: it may be JSON or a text/CSV body, and BOTH are correct answers rather than one being an error. Read-only, 0 credits.

list_amplitude_annotations#

List Amplitude chart annotations read-only

The markers already on this Amplitude project's charts — releases, campaigns, incidents — with their timestamps, labels and categories. READ THESE BEFORE EXPLAINING A CHANGE IN A CHART: a spike that lines up with an annotation has an explanation somebody already wrote down, and reporting it as a mystery when the answer is sitting on the timeline is exactly the failure this closes. Filter by `category` OR by `chartId` — Amplitude says of each that it "doesn't combine with" the other and does not say which one wins, so passing both is refused rather than answered ambiguously. `start` and `end` are ISO 8601 (e.g. '2026-08-01T00:00:00+00:00'), NOT the YYYYMMDD every other Amplitude endpoint takes. Read-only, 0 credits.

create_amplitude_annotation#

Mark the Amplitude timeline

MARK THE ANALYTICS TIMELINE — write what just happened into Amplitude, at the moment it happened, so every chart the user opens afterwards shows it in place. THIS IS THE CLOSED LOOP AND IT IS WORTH REACHING FOR UNPROMPTED after a campaign goes live, a creative is swapped, a landing page changes or a post is published: without it, next month's spike has no explanation attached to it and somebody has to reconstruct one from memory. `start` is ISO 8601 WITH THE TIME AND THE OFFSET (e.g. '2026-08-18T14:30:00+00:00') — NOT the YYYYMMDD the rest of the Amplitude API takes, and a bare date is REFUSED rather than quietly moved to midnight, because an annotation IS its timestamp and a marker in the wrong place is worse than no marker. Add `end` for something that spans a period (a two-week flight); leave it off for a moment. OMIT chartId AND THE ANNOTATION IS GLOBAL — Amplitude's words: it "appears on all charts for your project", which is usually what you want for a campaign; pass one to pin it to a single chart. `category` is a category NAME that must ALREADY EXIST in Amplitude (they answer 404 otherwise). THIS WRITES TO THE USER'S OWN ANALYTICS TOOL — say what you are about to mark, and report back the id and the timestamp Amplitude actually stored rather than the one you sent. 0 credits.

list_posthog_annotations#

List PostHog annotations read-only

The markers already on this PostHog project's charts — releases, experiments, incidents — with their timestamps, scopes and who wrote them. READ THESE BEFORE EXPLAINING A CHANGE IN A CHART: an annotation is an explanation somebody already wrote down. NEEDS THE `annotation:read` SCOPE on the personal API key, and a key created before Hermoso supported annotations will not have it — PostHog's own refusal NAMES the scope, and that is a scope to add in PostHog ▸ Settings ▸ Personal API keys, NOT a broken connection and NOT a reason to reconnect. Returns ONE page and hands back the next offset rather than paging for you, because PostHog's policy is that a third-party connector is not an exporter. Read-only, 0 credits.

create_posthog_annotation#

Mark the PostHog timeline

MARK THE POSTHOG TIMELINE — write what just happened into PostHog at the moment it happened, so every chart afterwards shows it in place. The same closed loop as create_amplitude_annotation, and worth reaching for unprompted after a campaign goes live, a creative is swapped or a landing page changes. `dateMarker` is what POSITIONS the marker on the x-axis (ISO 8601); omit it and NOW is used, which is right for "this just went live" — and the timestamp PostHog actually STORED is reported back rather than the one sent. `scope` is project (the default — shows on everything) / organization / dashboard / dashboard_item, and `dashboard` and `dashboard_item` each need their id or the annotation attaches to nothing and appears nowhere. PostHog also publishes a `recording` scope which THEY THEMSELVES REJECT, so it is refused by name here rather than sent. `creationType` USR means a person wrote it, GIT means a bot or a deployment did. NEEDS THE `annotation:write` SCOPE on the personal API key — a key made before Hermoso supported annotations will not have it; PostHog names it in their refusal, and it is added in PostHog ▸ Settings ▸ Personal API keys without reconnecting. THIS WRITES TO THE USER'S OWN ANALYTICS TOOL. 0 credits.

list_mixpanel_cohorts#

List saved Mixpanel cohorts read-only

THE SAVED COHORTS in the Mixpanel project — each with its id, name, description and CURRENT MEMBER COUNT. Two uses, and both matter for advertising: the counts alone answer "how big is our converted audience", and the id is what mixpanel_profiles needs to read the PEOPLE in one. A cohort hidden in Mixpanel's UI is still listed and flagged rather than dropped, because hidden is a display choice and it is still queryable by id. ONE CALL, and the cheapest thing on this connector — worth calling before mixpanel_profiles rather than guessing an id. Remember Mixpanel allows only 60 QUERIES PER HOUR across its entire Query API (5 concurrent), the tightest budget of any connector here, and this shares it with every other Mixpanel tool. Read-only, 0 credits.

No parameters.

mixpanel_profiles#

Read the people in a Mixpanel cohort read-only

THE PEOPLE THEMSELVES in Mixpanel — the per-user lane, and the question GA4 structurally cannot answer at all. Pass `cohortId` (from list_mixpanel_cohorts) for "who is in the Converted cohort and what do we know about them", or `where` for an ad-hoc filter over profile properties, or `distinctId` for one person. PASS `outputProperties` ALMOST ALWAYS: it cuts the payload to the properties you actually need, and Mixpanel says it "can drastically reduce the amount of data returned" and "can speed up queries significantly". RETURNS ONE PAGE AND DOES NOT PAGINATE FOR YOU — it hands back page, pageSize, total and a sessionId, and Mixpanel REQUIRES that sessionId alongside any page above 0, so a second page is a deliberate second call. DO NOT LOOP IT: Mixpanel allows 60 queries per hour across its ENTIRE Query API and each page spends one of them. REPORT `total` (the whole cohort) SEPARATELY FROM `count` (this page) — quoting only the page size understates the audience, which is the number a targeting decision gets made on. Read-only, 0 credits.

list_microsoft_ads_campaigns#

List Microsoft Advertising accounts / campaigns read-only

Read the brand’s connected Microsoft Advertising (Bing Ads) account(s). Call with NO accountId to list the accounts shared with this brand — do this first to pick a target. Call WITH accountId to list that account’s campaigns (id, name, status, daily budget, campaign type, and whether the budget is SHARED). Microsoft statuses are Active / Paused — never Google’s ENABLED — and Microsoft also sets BudgetPaused, BudgetAndManualPaused and Suspended on its own, so report the status you read rather than assuming a paused campaign was paused by a person. Read-only, free. Needs Microsoft Advertising connected (Settings ▸ Connectors ▸ Microsoft Advertising).

microsoft_ads_report#

Microsoft Advertising performance report read-only

Performance for a Microsoft Advertising account — impressions, clicks, CTR, average CPC, spend, conversions. `reportType` picks WHICH report, and that is the whole Microsoft reporting surface, not just campaigns: AdGroupPerformance, AdPerformance, KeywordPerformance, SearchQueryPerformance (the actual search terms people typed), GeographicPerformance, UserLocationPerformance, AgeGenderAudience and ProfessionalDemographicsAudience (LinkedIn-sourced job function and industry, inside Bing), ConversionPerformance, DestinationUrlPerformance, ShareOfVoice, AssetPerformance, ProductDimensionPerformance, SearchCampaignChangeHistory ("what changed on Tuesday") and ~30 more — an unknown name is refused WITH the full list rather than forwarded. `aggregation` controls the row grain (Summary / Daily / Hourly / Weekly / Monthly / Yearly / HourOfDay / DayOfWeek). Two reports keep far less history than the usual 36 months — AssetPerformance 30 days, ShareOfVoice 6 — and the reply says so, because an empty short-retention report is a retention limit, not an absence of delivery. Window via timePeriod (Today | Yesterday | LastSevenDays | Last14Days | Last30Days | ThisWeek | LastWeek | LastFourWeeks | ThisMonth | LastMonth | LastThreeMonths | LastSixMonths | ThisYear | LastYear | ThisWeekStartingMonday | LastWeekStartingMonday | LastFourWeeksStartingMonday) or since+until (YYYY-MM-DD) — default Last30Days. An unrecognised timePeriod is REFUSED, never silently swapped for another window. Microsoft generates reports ASYNCHRONOUSLY: this can return pending:true with a reportRequestId, and you must call again rather than reporting any numbers. A report that succeeds with ZERO rows genuinely means there was no delivery in that window — say exactly that; never present zeros as measured performance. Read-only, free.

microsoft_ads_keyword_ideas#

Microsoft Advertising keyword planner read-only

Microsoft Advertising’s KEYWORD PLANNER — real monthly search volume, competition, suggested bid and ad impression share, expanded from seed keywords, a landing-page URL to mine, or a category. Run it BEFORE choosing keywords for a Microsoft campaign, exactly as you would google_ads_keyword_ideas for Google. Unlike Google’s Keyword Planner there is NO planning-tier gate here — a developer token is sufficient. locationIds is REQUIRED and deliberately not defaulted: a search volume with no market attached is a number nobody can act on, and inventing a country would silently answer about the wrong market — use microsoft_ads_geo_search to resolve a country or city name to an id, free. SAY THIS WHEN REPORTING: Competition is Microsoft’s Low/Medium/High bucket, NOT a percentage; MonthlySearchCounts is a per-month series rather than one number; SuggestedBid is in the account currency. An empty result means Microsoft found no ideas for those seeds, never that nobody searches for them. Read-only, 0 credits.

microsoft_ads_traffic_estimates#

Microsoft Advertising traffic estimates read-only

What a set of keywords would DELIVER on Microsoft Advertising at a given bid — estimated impressions, clicks, CTR, average CPC, average position and total cost. maxCpc is REQUIRED because a traffic estimate IS a function of the bid; estimating without one would be inventing the input. locationIds is REQUIRED for the same reason a search volume needs a market. SAY THIS WHEN REPORTING: Microsoft returns a MINIMUM and a MAXIMUM per keyword — quote the range, never average the two into a single figure — and every number here is a FORECAST, so never present it as measured performance. Read-only, 0 credits.

microsoft_ads_budget_opportunities#

Where Microsoft says budget is capping delivery read-only

Where a Microsoft Advertising campaign is BUDGET-CONSTRAINED — Microsoft’s own recommended budget against the current one, the estimated WEEKLY click and impression gain from raising it, and a budget/return curve. Omit campaignId for the whole account. SAY THIS WHEN REPORTING: these are Microsoft’s FORECASTS, never measurements — a projected increase has not happened — and acting on one spends real money, so it takes set_microsoft_ads_budget and an explicit yes from the user. Microsoft EXCLUDES user-paused campaigns from this analysis, so a paused campaign is absent by design rather than well-funded. Read-only, 0 credits.

microsoft_ads_geo_search#

Find Microsoft Advertising location ids read-only

Resolve country / region / city names to the Microsoft Advertising location ids that create_microsoft_ads_campaign needs. Read-only, free, 0 credits. Use it when a location ask is ambiguous ("Springfield") — this returns EVERY candidate with its id so the USER can pick, and you never guess between two places. Accepts names, ISO country codes ("CA"), or numeric location ids. Pass `query` as ONE ask (a plain string) or SEVERAL (an array of strings) — a comma is part of a place's name ("Seattle, Washington, United States"), never a separator. Postal codes and neighbourhoods are not name-searchable — pass their numeric location id straight through; the campaign read-back reports the name Microsoft resolves for it.

create_microsoft_ads_campaign#

Build a Microsoft Advertising campaign (paused)

Build a campaign on a connected Microsoft Advertising (Bing Ads) account. ALWAYS created Paused — it spends NOTHING until you activate it with set_microsoft_ads_status(confirm:true). Microsoft’s object graph is campaign → ad group → responsive search ad → keywords, so a campaign ON ITS OWN CANNOT SERVE AN IMPRESSION: pass adGroup{name, ad{headlines,descriptions,finalUrls}, keywords[]} and this builds the whole tree. Microsoft has NO atomic multi-object write (unlike Google), so the levels are created in sequence and the campaign is DELETED again if anything below it is rejected — you never inherit a half-built campaign. Microsoft requires 3–15 headlines (≤30 chars) and 2–4 descriptions (≤90 chars); expanded text ads can no longer be created at all. dailyBudget is in the ACCOUNT’S currency, not necessarily USD. LOCATION TARGETING: pass locations[] (country / region / city names, ISO country codes, or numeric Microsoft location ids). A Microsoft campaign has NO geo targeting unless it is set, and Microsoft does not require any — so if you pass none, the campaign IS CREATED and serves WORLDWIDE (Microsoft’s own default), and the returned note says so loudly. That is safe at this stage because the campaign is Paused and spends nothing; it is NOT safe to activate without telling the user, so relay the warning. Nothing is created when a location you DID name cannot be resolved (call microsoft_ads_geo_search to disambiguate, then pass the id). Pass worldwide:true to record that everywhere was deliberate and suppress the nudge. The locations are written and READ BACK inside the same rollback as the rest of the tree, so a campaign is either targeted as asked or does not exist. Everything is READ BACK from Microsoft before you are told it exists; print the returned note verbatim, and if it says the campaign cannot serve yet, say that rather than calling it a finished ad.

create_microsoft_ads_ad_group#

Add a Microsoft Advertising ad group

Add an ad group to an existing Microsoft Advertising campaign — optionally with its responsive search ad and keywords in the same call. Created Paused by default. If the parent campaign is already LIVE (Active), creating this ad group Active starts REAL AD SPEND on the next auction, exactly like activating it — show the user what would begin serving, get an explicit yes, then pass confirm:true. Leaving it Paused never needs confirmation. Read back from Microsoft before you are told it exists.

create_microsoft_ads_ad#

Create a Microsoft responsive search ad

Create the actual AD inside a Microsoft Advertising ad group — this is the object that carries the creative; a campaign or ad group alone shows nothing. It builds a RESPONSIVE SEARCH AD: 3–15 headlines (≤30 chars), 2–4 descriptions (≤90 chars), at least one finalUrl, optional path1/path2. Expanded text ads CANNOT be created any more — Microsoft rejects them outright. Created Paused; if the parent ad group and campaign are both Active, creating this Active starts REAL AD SPEND immediately — get an explicit yes and pass confirm:true. Read back from Microsoft, including its editorial status, before you are told it exists.

add_microsoft_ads_keywords#

Add Microsoft Advertising keywords

Add keywords to a Microsoft Advertising ad group. Match types are Exact, Phrase and Broad — Microsoft has no broad-match-modifier. Keywords are added Paused unless you set status:"Active"; an Active keyword on a live ad group makes the campaign bid on a new term immediately, so that needs confirm:true. Note that per-keyword bids are honoured but ad-group / keyword BID STRATEGIES are silently ignored by Microsoft — they inherit the campaign’s. Only the keywords Microsoft confirms on the read-back are reported as added.

set_microsoft_ads_budget#

Set a Microsoft Advertising daily budget

Change a Microsoft Advertising campaign’s DAILY BUDGET (in the account’s currency). Raising it on a LIVE (Active) campaign increases real spend immediately — you MUST show the user the new daily amount, get an explicit yes, then call with confirm:true. If the campaign is on a SHARED budget its amount is read-only here and this refuses with an explanation rather than pretending to change it. Read back after the change.

set_microsoft_ads_status#

Activate or pause a Microsoft Advertising campaign / ad group / ad

Turn a Microsoft Advertising campaign, AD GROUP or AD on (Active) or off (Paused). Pass level:"campaign" + campaignId, level:"adGroup" + adGroupId, or level:"ad" + BOTH adGroupId and adId. ACTIVATING STARTS REAL AD SPEND — you MUST first show the user the campaign name + its daily budget, get an explicit yes, then call with status:"Active" and confirm:true. Pausing is always safe. Microsoft has only these two statuses — its Deleted state is internal-only and cannot be SET — so to remove something use delete_microsoft_ads_object, which is a real delete operation, not a status. The resulting status is READ BACK from Microsoft before you are told it took — and Microsoft may report BudgetPaused / BudgetAndManualPaused / Suspended instead, which the note names explicitly.

delete_microsoft_ads_object#

Delete a Microsoft Advertising campaign / ad group / ad / keyword destructive

PERMANENTLY delete a Microsoft Advertising campaign, ad group, ad or keyword. This is a real delete — Microsoft removes the object and it stops being returned by every read, with no undelete and no documented recovery window. Pass level:"campaign" + campaignId, level:"adGroup" + adGroupId, level:"ad" + adGroupId AND adId, or level:"keyword" + adGroupId AND keywordId. CALL IT WITHOUT confirm FIRST: nothing is deleted, and you get back the object’s real name, its status and how many ad groups / ads / keywords go with it, read live from Microsoft — show the user exactly that. If the object has children, is Active, or has spent, confirming alone is NOT enough: you must also pass confirmName set to its exact name and confirmChildren set to the child count from that read-back, which is what proves you are deleting the object you think you are. A campaign that is paused, empty and never ran deletes on plain confirm:true. To stop delivery WITHOUT deleting, use set_microsoft_ads_status(status:"Paused") instead. The result is READ BACK from Microsoft: it says "deleted" only when the object no longer resolves, "not confirmed" if it does, and "could not tell" if the check itself failed — repeat that verbatim rather than claiming success.

list_microsoft_merchant_stores#

List Microsoft Merchant Center stores read-only

List the brand's MICROSOFT MERCHANT CENTER stores — the product-feed side of Microsoft Advertising, the exact twin of Google Merchant Center. THIS IS WHERE THE merchantId COMES FROM: every other Microsoft Merchant tool needs it and there is no other way to discover it (Content API's own Store resource is closed-beta only, so Hermoso reads the list from Campaign Management instead, which is open to everyone). Each row carries the store name, its URL, and whether it is active, has a catalog and has product ads enabled. Microsoft's own caveat, which the note repeats: those flags are set inside Merchant Center and are read-only here — an inactive store can still be referenced by a Shopping campaign. An account with NO store has no product feed at all, and a store cannot be created through the API. Read-only, free, 0 credits.

list_microsoft_merchant_products#

List Microsoft Merchant Center product offers read-only

Read the product offers in a Microsoft Merchant Center store — the feed a Microsoft Shopping campaign serves from. Pass productId to fetch ONE offer, or omit it to page the store (limit up to 250, then pass the returned pageToken). MICROSOFT'S PRODUCT IDS ARE COMPOSED AND CASE SENSITIVE: the id is channel:contentLanguage:targetCountry:offerId (e.g. Online:en:US:Sku123), not the bare offerId, and a re-cased id addresses nothing — always use the id this tool returned. Read-only, free, 0 credits.

upsert_microsoft_merchant_product#

Add or update Microsoft Merchant Center product offers

Add or update product offers in a Microsoft Merchant Center store. THE ONE THING TO KNOW BEFORE CALLING IT: Microsoft has NO partial update — 'because an update is an insert operation, you must include all fields of the offer in the request' — so a title-only 'update' CLEARS every other field. Always send the whole offer. Ten fields are required: availability, channel, condition, contentLanguage, imageLink, link, offerId, price, targetCountry, title; brand/gtin/mpn are strongly recommended and their absence is set as identifierExists:false for you. Pass product for one offer or products[] for a batch (Hermoso caps a batch at 300 — Microsoft publishes two contradictory ceilings for this and we take the lower). Pass dryRun:true to validate against Microsoft without writing anything; Microsoft returns no ids on a dry run, so none is claimed. Feed edits cannot spend and cannot start an auction, but an offer goes through editorial review — being STORED is not the same as being served. Everything is read back from Microsoft. 0 credits.

delete_microsoft_merchant_product#

Delete a Microsoft Merchant Center product offer destructive

Delete one product offer from a Microsoft Merchant Center store. Pass productId as the FULLY QUALIFIED id (channel:contentLanguage:targetCountry:offerId), not the offerId. Call without confirm first — nothing is deleted and you get Microsoft's own better advice back: deleted products can take UP TO 12 HOURS to stop delivering, so if the goal is to stop showing it today, upsert it with availability 'out of stock' instead. The outcome is READ BACK by re-fetching the offer, and says 'deleted', 'not confirmed' or 'could not tell' — repeat that verbatim rather than claiming success from the delete's own empty response. 0 credits.

list_microsoft_merchant_issues#

Why Microsoft Merchant Center products are not serving read-only

Why a Microsoft Merchant Center store's products are NOT serving — the approved / disapproved / expiring counts plus the per-offer disapprovals and warnings with Microsoft's own issue codes. This is the tool to reach for when a Microsoft Shopping campaign is live and showing nothing. TWO CAVEATS THAT LOOK LIKE FAILURES AND ARE NOT, both repeated in the note: Microsoft returns detail rows ONLY for offers that are Disapproved or in Warning, so an EMPTY detail list is the healthy state; and a status change takes up to two hours to reach the summary, so a fresh upload legitimately shows as nothing yet. Read-only, free, 0 credits.

list_microsoft_merchant_catalogs#

List Microsoft Merchant Center catalogs read-only

List the catalogs inside a Microsoft Merchant Center store. Catalogs logically group products, and a Shopping campaign's product scope points at them. Each row says whether publishing is ENABLED — products in a catalog with publishing off do not serve at all, which is a common and invisible reason a feed appears healthy and delivers nothing. Products go into the store's default catalog unless a call names catalogId. Read-only, free, 0 credits.

manage_microsoft_merchant_catalog#

Create, update or delete a Microsoft Merchant Center catalog destructive

Create, update or delete a catalog in a Microsoft Merchant Center store. Creating needs name + market + isPublishingEnabled; updating needs catalogId + name + isPublishingEnabled (market is not settable after creation). isPublishingEnabled is NEVER defaulted on — products serve only when it is true, so publishing a catalogue is always an explicit choice. Names must be unique within the store and are capped at 70 characters. Pass deleteIt:true with catalogId and confirm:true to remove one. Every outcome is READ BACK from Microsoft. 0 credits.

list_microsoft_ads_audiences#

List Microsoft Advertising audiences (Customer Match lists) read-only

List a Microsoft Advertising account's audiences — by default the CUSTOMER LISTS (Customer Match), with each row's membership duration and its current Search and Audience-network sizes. TWO MICROSOFT CAVEATS THAT LOOK LIKE FAILURES AND ARE NOT: a size is nil or empty for UP TO 48 HOURS while a list is being built, and Microsoft will not use an audience of fewer than 300 people at all — so never report a fresh list's 0 as a failed upload. Pass types[] to ask for other audience types. Read-only, free, 0 credits.

create_microsoft_ads_customer_list#

Create an empty Microsoft Advertising Customer Match list

Create an EMPTY Customer Match list on a Microsoft Advertising account, ready for apply_microsoft_ads_customer_list to fill. membershipDuration is 1–390 days, or -1 for no expiration (Microsoft's default is 30). scope 'Account' (the default) makes it usable only by that ad account; scope 'Customer' makes it usable by every account under the manager — Hermoso derives the right parent id for whichever you choose, because getting that pair wrong mis-parents the list silently. An audience is a definition: it cannot spend and it cannot serve on its own. Read back from Microsoft. 0 credits.

apply_microsoft_ads_customer_list#

Upload customer emails into a Microsoft Customer Match list

Upload customer emails into a Microsoft Advertising Customer Match list so campaigns can target or exclude them. YOU PASS PLAIN EMAIL ADDRESSES — Hermoso normalizes and SHA-256 hashes them locally and sends ONLY the digests, so no plaintext ever leaves the server; values that arrive already hashed (64 hex characters) are passed through untouched. Microsoft's own normalization is applied exactly as published: trim, remove all dots from the user portion, remove any +alias, lowercase, then SHA-256. YOU MUST GET THE USER'S AGREEMENT FIRST: show them https://about.ads.microsoft.com/en-us/legal/customer-match-terms and only then call with acceptTerms:true, which Microsoft says 'eliminates the need to accept terms through the Microsoft Advertising UI' — without it nothing is uploaded and nothing is hashed. action is Add (additive, the default), Remove or Replace. Maximum 1000 items per call; page larger lists. Email is the only supported identifier — Microsoft publishes Phone and CRM as 'Not currently supported' and both are refused by name. DO NOT read a size of 0 afterwards as a failure: Microsoft leaves it empty for up to 48 hours while the audience builds. 0 credits.

list_openai_ads_campaigns#

List ChatGPT Ads account / campaigns / ad groups / ads read-only

Read the brand’s connected ChatGPT Ads account — the ads that appear below ChatGPT answers. Call with NO ids to get the ad account itself (name, currency, status, review state) plus its campaigns; with campaignId to list that campaign’s ad groups; with adGroupId to list that ad group’s ads, including each ad’s REVIEW status, which is what decides whether it can ever show. Statuses here are active / paused / archived. Read-only, free, zero spend risk. Needs ChatGPT Ads connected (Settings ▸ Connectors ▸ ChatGPT Ads): the user pastes an Advertiser API key from ChatGPT Ads Manager ▸ Settings — there is no OAuth and no manager account, and one key is scoped to one ad account.

openai_ads_report#

ChatGPT Ads performance report read-only

Performance for ChatGPT Ads — impressions, clicks, spend, CTR, CPC, CPM. The scope follows the id you pass: none = the whole ad account, or campaignId / adGroupId / adId. granularity is hourly, daily, monthly or none (default daily); the default window is the last 30 days; segment by country or device for a breakdown, and level rolls the rows up by campaign / ad group / ad. A report with NO rows genuinely means there was NO delivery in that window — say exactly that; never present zeros as measured performance. Read-only and free, so run it FIRST after connecting: it proves the key works with zero spend risk.

openai_ads_geo_search#

Find ChatGPT Ads location ids read-only

Look up ChatGPT Ads location ids by name — countries, regions and DMAs — so a campaign can be geo-targeted. GEO AND CUSTOM AUDIENCES ARE THE ONLY LIST-BASED TARGETING THIS PLATFORM HAS: there are no interests, no lookalikes, no age or gender. Everything else is semantic, through an ad group’s context hints. Custom audiences are targeted with customAudienceIds / excludedCustomAudienceIds (see list_openai_ads_audiences). Pass the returned ids as locationIds when creating or updating a campaign; a campaign with no location targeting runs everywhere available. Read-only, free.

list_x_ads_accounts#

List X ad accounts read-only

List the X (Twitter) ad accounts this brand can act on, with the PERMISSION LEVEL held on each so you can tell an admin grant from a read-only one before attempting a write. X grants API access PER AD ACCOUNT, not per app: the customer adds Hermoso’s X user to their ad account at business.x.com → Account access, and it appears here. Read-only, free.

No parameters.

list_x_ads_campaigns#

List X ads campaigns read-only

List campaigns on an X ad account — status, budgets, and whether X considers each servable. Omit accountId when only one account is reachable and it resolves itself. Read-only, free.

create_x_ads_campaign#

Build an X ads campaign (paused)

Create a campaign on X (Twitter). ALWAYS CREATED PAUSED with no override — it spends NOTHING until set_x_ads_status(confirm:true). A CAMPAIGN ALONE CANNOT SERVE ON X: it needs a line item and a promoted post underneath it, and the read-back says so rather than letting you call it a finished ad. Requires a funding instrument (a payment method on the X ad account) — omit fundingInstrumentId to be shown the usable ones, and if there are none this refuses with that reason instead of failing at X. Budgets are in the ad account’s own currency. Everything is READ BACK from X before you are told it exists; print the returned note verbatim.

set_x_ads_status#

Pause or activate an X campaign or line item

Pause or ACTIVATE an X ads CAMPAIGN (campaignId) or ONE LINE ITEM inside it (lineItemId) — pass exactly one. ACTIVATING STARTS REAL SPEND on the next auction, so it requires confirm:true — this is the only switch on X that arms money. Tell the user the budget and what will start spending BEFORE you pass confirm. DELIVERY ON X IS THE AND OF BOTH LEVELS: an ACTIVE line item under a PAUSED campaign serves nothing, so the result reads the PARENT back too and states whether anything can actually spend rather than letting you infer it. Pausing a line item is the REVERSIBLE way to take one ad group out of delivery — deleting it is not.

microsoft_ads_bulk_download#

Export a Microsoft Advertising account as a bulk file read-only

Export a Microsoft Advertising account as a BULK FILE — one spreadsheet holding whatever slice of the account you ask for. This is the ONLY way to read most of a Microsoft account: roughly 185 of Microsoft’s record types are reachable here and nowhere else in Hermoso — sitelink / callout / structured-snippet / image / logo / price / promotion ad extensions, labels, shared negative keyword lists, bid strategies, audiences and their associations, experiments, seasonality adjustments, conversion goals, asset groups and listing groups, feeds. Pass entities[] (default Campaigns, AdGroups, Ads, Keywords), campaignIds[] to narrow it, or since for a DELTA of what changed (Microsoft refuses anything older than 30 days). The reply carries the WHOLE FILE as a string in `file` — edit that and pass it straight to microsoft_ads_bulk_upload, which is the round trip this exists for. A bulk export is a SNAPSHOT of what Microsoft held when it ran, never a live view, so do not quote a status from it as current after a change. Microsoft builds it asynchronously: a large account can come back pending:true with a downloadRequestId — call again with that id rather than resubmitting, which would export the whole account a second time. Read-only, 0 credits.

microsoft_ads_bulk_upload#

Apply a Microsoft Advertising bulk file (spend-gated) destructive

Apply a Microsoft Advertising BULK FILE — edit hundreds of campaigns, ad groups, ads, keywords, extensions or labels in one request. Pass `file` as the CSV/TSV string; microsoft_ads_bulk_download returns exactly that shape in its `file` field. THE SPEND GATE, AND IT IS UNLIKE EVERY OTHER TOOL HERE. A bulk file carries a Status column, so one upload can turn campaigns ON — and confirm:true ALONE IS NOT ENOUGH for a file: it proves you meant to upload something, not that you know what THIS file does, and it reads identically for a file that changes two bids and one that activates fifty campaigns. So: call it ONCE with no confirmation. Nothing is uploaded, and you are told exactly how many objects the file would ACTIVATE (they can then spend real money) and DELETE (which Microsoft never undoes — a deleted object is never returned by any read again), each named with its row number, type, id and name. SHOW THAT LIST TO THE USER, get an explicit yes, then call again with confirm:true, confirmActivations:<n> and confirmDeletions:<n>. If the activations are incidental — a file you round-tripped out of a download and only meant to edit bids in — pass pauseInstead:true instead and those rows are written as Paused, so everything else lands with nothing armed; it is refused when the file also deletes, because pausing is a safe substitute for activating and there is none for deleting. Partial success is normal on this API: rows Microsoft rejects come back listed individually and the correct ones ARE applied, so never describe a CompletedWithErrors upload as a failure. 0 credits.

list_microsoft_ads_conversion_goals#

Microsoft Advertising conversion goals read-only

The conversion goals on a Microsoft Advertising account — what the account COUNTS as a conversion, and therefore what every conversion-optimised bid strategy on it is optimising toward. Flags which ones are OFFLINE goals: those are the only goals send_microsoft_ads_offline_conversions can post to, and its conversionName must match one of their names EXACTLY, including case and spacing. An account with no goals at all has no conversion tracking — say that plainly rather than reporting an empty list, because it means smart bidding there has nothing to aim at. Read-only, 0 credits.

send_microsoft_ads_offline_conversions#

Send offline + enhanced conversions to Microsoft

Tell Microsoft Advertising about conversions that happened OFF the website — a phone sale, an in-store purchase, a lead that closed weeks after the click — so smart bidding on that account stops optimising against only what converted online. Each row needs conversionName (an existing OFFLINE conversion goal, matched by name — list_microsoft_ads_conversion_goals shows them), conversionTime (within the last 90 days AND after the click), and an identifier: either microsoftClickId (the msclkid Microsoft appends to the landing-page URL) or, for ENHANCED conversions, a plain email and/or phone. YOU PASS PLAIN VALUES AND THE HASHING HAPPENS SERVER-SIDE: emails are normalized and SHA-256’d to Microsoft’s own published five-step spec, which is verified against Microsoft’s own worked digests. A PHONE MUST ALREADY CARRY ITS COUNTRY CODE (+14255551234) and is refused otherwise — Microsoft’s spec says "normalize to E.164 format with country code" and stops there, and guessing which country a bare 4255551234 belongs to is not a mistake you would ever see: the upload succeeds and matches nobody. SAY THIS WHEN REPORTING: accepted is not the same as visible. Microsoft takes up to 6 hours to show offline conversion data and applies nothing at all in the first 2 hours after a goal is created, and a conversion only counts inside the goal’s own conversion window. Duplicates are silently ignored (the first wins), so re-sending a batch is safe and changes nothing. 0 credits.

microsoft_ads_auction_insights#

Who else is bidding on the same Microsoft auctions read-only

Who ELSE is competing for the same Microsoft Advertising auctions — the other advertisers’ domains with their impression share, overlap rate, position-above rate, top-of-page rate and outranking share. microsoft_ads_report tells you what the account did; this tells you who it did it against, which is the input to a bid or a creative decision rather than a report. Scope it with entityType Account (default, the whole account) / Campaign / AdGroup / Keyword plus entityIds (max 200), and optionally segment by up to three of Day, DayOfWeek, Device. SAY THIS WHEN REPORTING: every figure is a share of the auctions YOUR ads entered, never a measure of a competitor’s whole account or budget — a competitor missing from the list did not necessarily not bid. An empty result means there was no delivery to compare in that window, which is MISSING data; never report it as "nobody is bidding against you". Read-only, 0 credits.

microsoft_ads_recommendations#

What Microsoft suggests changing on the account read-only

What Microsoft Advertising ITSELF suggests changing on the account: budget raises, new keywords, broad-match widenings, conflicting negative keywords to remove, and responsive search ads or extra headlines Microsoft has written. Each row carries the campaign and ad group it touches plus Microsoft’s OWN estimate of what applying it would add to clicks, impressions, conversions and COST; a budget recommendation states the current and the recommended daily amount, so the money is a vendor fact rather than a guess. SAY THIS WHEN REPORTING: every Microsoft recommendation INCREASES what the account buys, that is what they are for, so none of them is a free win, and an empty list means Microsoft has no ADVICE (usually too little delivery to compute any), never that the account is optimal. Dismissed recommendations are hidden unless you ask for them. Read-only, 0 credits.