Product Metrics MCP tools

The Product Metrics MCP server gives an AI assistant such as Claude or ChatGPT 24 tools to read your store, your products and your Google Ads account. Every tool reads, except propose_change, which files a proposal that a person approves in Priorities. No tool changes Google Ads or your store. To connect an assistant, see Connect Claude or ChatGPT.

How the tools workCopy Anchor Link

• Pick a store first. One connection covers every store (property) you can open in Product Metrics. The assistant calls list_properties, then passes property_id to every other tool. If you have one store, it can leave property_id out.
• Your role applies. Any member of a workspace can use the read tools. Only editors and admins can file proposals.
• Arguments are forgiving. A limit above the maximum, a plural value or a camelCase name is corrected instead of refused, and the answer starts with what was corrected.
• Hourly limits. Up to 5,000 tool calls per person and 20,000 per store each hour. Expensive tools (marked below) have a lower limit: 30 calls per person and 120 per store each hour.
• Answers are text. Each tool returns a readable summary with figures, dates and currency, cut off at about 40,000 characters. Narrow the request to see more.

StoresCopy Anchor Link

Pick the store (property) to work on and read its own sales numbers.

list_propertiesCopy Anchor Link

Properties · Read-only · reads Product Metrics data · any workspace member

The Product Metrics properties (one store’s Google Shopping account each) the signed-in person can open, with the company, the linked Google Ads customer id and the currency. Call this first when no property is chosen yet, then pass its propertyId as property_id to every other tool. If there is exactly one, use it without asking; if there are several and the question names none, ask which store or answer per store.

get_store_overviewCopy Anchor Link

Store overview · Read-only · reads Product Metrics data · any workspace member

The store’s own numbers next to the ads: web analytics from GA4 for the period (sessions on product pages, sessions with a purchase, revenue, product views, add to carts, checkouts, conversion rate, revenue per session) with the comparison period, an optional daily, weekly or monthly trend and the top products by revenue, plus shop orders from the connected shop when order tracking is set up, over the same range with the comparison and the same trend (orders, revenue ex tax, average order value, new and returning customers, refunds, profit). Use it for how the store is doing overall, whether a change in ads shows up in store revenue, and the ad share of revenue. GA4 figures count sessions that landed on a product page, not every session; shop order figures are the shop’s own.

Google Ads analysisCopy Anchor Link

Read the Google Ads account linked to the store, live. These tools only read: nothing here changes the account.

explain_google_ads_changeCopy Anchor Link

Explain a Google Ads change · Read-only · reads your Google Ads account live · any workspace member · counts towards the hourly limit for expensive tools

Explains why a Google Ads metric changed, in one call: use it first for ‘what happened to …’, ‘why did … drop or rise’, ‘something is off since …’. For the scope (the account, campaign ids, types or a name), it reads the daily series and finds the day the metric stepped to a new level (or says the change is gradual), compares the days after with as many days before, splits the change into its funnel (impressions, CTR, clicks, CPC, conversion rate, value per conversion), ranks which campaigns, asset groups, ad groups, products, devices, networks and conversion actions carry it (concentrated in one, or spread over all), counts how many products got impressions and spend before and after (a widened product mix), flags an asset group or product that started or stopped delivering, estimates how much value is still to come from conversion delay, lists the account changes made in the days before (budget, status, targets, by whom, and listing group edits Google Ads records without values), and sets the store’s own revenue and orders next to it, so a tracking problem can be told apart from a real drop. Follow up with get_google_ads_report only to drill further.

get_google_ads_reportCopy Anchor Link

Google Ads report · Read-only · reads your Google Ads account live · any workspace member

Live Google Ads performance for the property’s linked account, at any level: account totals, campaigns (with type, status, budget, bidding, target ROAS and search impression share lost to budget and rank), ad groups, Performance Max asset groups, search terms, keywords (with quality score), products, conversion actions, device, network, day of week or hour. Each row has impressions, clicks, cost, conversions, conversion value, CTR, CPC, conversion rate, CPA and ROAS, plus the comparison period and its change. Filter by campaign ids, campaign name or type, row name, spend or clicks, or rows with spend and no conversions (wasted spend); sort by any metric or by its change; break down by day, week or month for trends. Use it for Google Ads questions about levels, splits and lists: spend, ROAS, wasted search terms, budget-limited campaigns, device or hour splits, trends. Money is in the account currency. Totals cover every matching row, not just the rows shown. To find out why something dropped or rose, call explain_google_ads_change instead: it does the drill-down in one call. When CPA looks fine but ROAS does not, read level conversion_action for that campaign: each action shows whether it is primary, and a primary action without value (sign-up, call) inflates conversions. For profit, margin, POAS or stock, use get_poas_report instead.

get_poas_reportCopy Anchor Link

Profit on ad spend (POAS) · Read-only · reads your Google Ads account live · any workspace member

Profit on ad spend: live Google Ads per product and campaign joined, in Product Metrics, with the store’s own margin (cost of goods), stock and the engine’s push/hold/reduce/pause decision. Gives per product, per campaign or for the account: cost, conversion value, ROAS, gross profit (conversion value × margin), POAS, profit after ads, the margin coverage, and per product the stock (on hand, weeks of cover, stockout date, slow mover) and decision; campaign rows add the spend on out-of-stock and low-cover products. Filter by stock (out_of_stock, low_cover, slow_movers) or to unprofitable rows (POAS below break-even); sort by profit after ads, POAS or cover. Use it for every question about profit, margin, POAS, ‘which products lose money on ads’, ‘are we advertising products we cannot deliver’, and budget moves that should follow profit or stock rather than ROAS. Search and Demand Gen campaigns sell no single product: their POAS uses the account’s average margin and is marked as estimated.

get_google_ads_changesCopy Anchor Link

Google Ads change history · Read-only · reads your Google Ads account live · any workspace member

The Google Ads account’s change history (the last 30 days, which is all Google Ads keeps): who changed what and when, with each field’s value before and after: budgets, campaign and ad group status, bidding and target ROAS or CPA, and the rest; plus the edits Google Ads records only as ‘changed’ without values (listing group filters, asset groups, criteria), which the change history leaves out. Filter by campaign ids or name. Use it for ‘did anyone change something’, ‘who paused …’, and to check what was changed before a drop.

get_product_targetingCopy Anchor Link

Product targeting (listing groups) · Read-only · reads your Google Ads account live · any workspace member

Which products each Performance Max asset group and Shopping ad group may serve: its listing group filters as rules (custom label, item id, brand, product type; included or excluded; ‘everything else’ nodes), the custom label Product Metrics writes its segments to, and what conflicts: a product excluded in one asset group but still servable through another, a catch-all that serves every other label, filters on a different custom label than the segments. Use it for ‘is my campaign filtered on my segments’, ‘where are my Stars’, ‘why does this excluded product still spend’.

compare_product_segmentsCopy Anchor Link

Segments vs campaign setup and other labels · Read-only · reads your Google Ads account live · any workspace member

Product Metrics segments (Stars, Cash Cows, Question Marks, Ghosts, Drainers, Dogs) against how each campaign is actually set up and against the other labels in the feed, per campaign: which custom label each campaign’s listing groups filter on and what fills it (our segments, ProfitMetrics, Producthero, Channable or Flowboost labels, or the merchant’s own segmentation such as categories or margin bands); spend, conversion value and ROAS per segment and per value of the other labels; the segment × label cells with the most spend; and the spend where the two systems disagree (a product one calls good and the other bad), with examples. Use it for ‘is my campaign built on your segments or on ProfitMetrics’, ‘how do your segments compare with Producthero/Channable/Flowboost/my own labels’, ‘which products do the systems disagree on’.

run_google_ads_queryCopy Anchor Link

Google Ads query (GAQL) · Read-only · reads your Google Ads account live · any workspace member · counts towards the hourly limit for expensive tools

Runs one read-only GAQL (Google Ads Query Language) SELECT against the property’s linked Google Ads account, for what the other Google Ads tools cannot answer: ad copy and asset performance, landing pages, geography, bid strategies, conversion action settings, listing groups, or an unusual combination of fields. Costs more than the report tool: prefer the report. Resources: customer, campaign, ad_group, asset_group, ad_group_ad, keyword_view, search_term_view, shopping_performance_view (segments.product_item_id, segments.product_title, segments.product_brand, segments.product_type_l1), campaign_budget, bidding_strategy, conversion_action (settings: conversion_action.name, status, category, primary_for_goal, counting_type; no metrics: per-action conversions come FROM campaign with segments.conversion_action_name), change_event (prefer get_google_ads_changes), geographic_view, user_location_view, landing_page_view, asset_group_listing_group_filter. Dates: segments.date DURING LAST_7_DAYS | LAST_30_DAYS | THIS_MONTH | LAST_MONTH, or segments.date BETWEEN ‘YYYY-MM-DD’ AND ‘YYYY-MM-DD’. Money fields ending in _micros are millionths of the account currency (divide by 1,000,000); the result adds the divided value as <field> without _micros. No OR in WHERE; use IN. A segment in WHERE must also be in SELECT (segments.date excepted). metrics.search_impression_share and friends cannot be combined with segments.device or hour. Rows come back flattened (campaign.name, metrics.clicks) and capped at max_rows.

Products and segmentsCopy Anchor Link

Find products worth a look, read everything Product Metrics knows about one product, and see how segments and categories are doing.

list_products_to_investigateCopy Anchor Link

Products to investigate · Read-only · reads Product Metrics data · any workspace member

Ranked list of products that need attention now, across ads performance, web traffic, competitor prices, margin and stock. Ranked by severity and money at stake per week. Start here when the user asks what to look at, what changed or where money is lost. Each row has the decision (push/hold/reduce/pause) and its strongest signal; call get_product_context for the full picture. Filter by segment or category to drill into a group from summarize_groups; then the reply can also list the group’s highest-spend products the assistant does not store (beyondStore: ad totals only, no decision).

search_productsCopy Anchor Link

Search products · Read-only · reads Product Metrics data · any workspace member

Find products by title, brand, item_id, offer id or product type. Use when the user names a product; returns item_ids for the other tools.

get_product_contextCopy Anchor Link

Product Context · Read-only · reads Product Metrics data · any workspace member

Full Product Context for up to 10 products: the five layers (advertising, journeys, market prices, margin, inventory) with their freshness, the decision with each layer’s vote and reason, signals and suggested Merchant Center labels. detail=‘detailed’ adds the figures behind the layers: advertising window totals and series summaries, journey next buys, competitor rows, and stock planning (weekly sales, cover, stockout and reorder dates, suggested quantity, lead time). Use it when the answer needs those figures; concise is enough to explain a decision.

summarize_groupsCopy Anchor Link

Segments and categories · Read-only · reads Product Metrics data · any workspace member

Totals per Product Segmentation segment (Stars, Cash Cows, Question Marks, Dogs, Drainers, Ghosts) or per value of the property’s category column: products, spend, conversion value, ROAS, share of spend and of conversion value, and the mix of decisions (push/hold/reduce/pause). With coverage ‘catalogue’ the totals cover every product in the catalogue; the decision mix only counts the products the assistant stores (storedProducts). Use for questions about a segment or category, or where spend goes without conversions; then drill in with list_products_to_investigate segment/category. Totals are for Product Segmentation’s date range; there is no previous period. The segments: Stars sell at volume at or above target; Cash Cows return strongly on smaller volume; Question Marks are mid performers, or above target on too little traffic; Dogs had enough traffic and stayed below par; Drainers take clicks and spend with little or no conversion value (and low-volume products that never got enough traffic to be judged); Ghosts get impressions but no clicks.

get_changesCopy Anchor Link

What changed · Read-only · reads Product Metrics data · any workspace member

What changed in the property, precomputed at the last refresh: the last delivered week against the week before (spend, conversion value, ROAS) for all products and per segment or category; the products that gained or lost the most conversion value and those whose spend rose most; signals that appeared or cleared and decisions that changed since about a week ago; and how much of the ad spend the daily history covers. Start here for ‘what changed’, ‘how was this week’, a weekly briefing or ‘anything unusual’, then drill into products with get_product_context or get_product_timeseries. Week figures cover only the products with daily history (see coverage): name the two weeks’ dates and how much of the spend the history covers.

get_insightsCopy Anchor Link

Store insights · Read-only · reads Product Metrics data · any workspace member

Store insights, precomputed per feed after the nightly feed run: Stars that run out of stock while advertised (dashboard_run_out), return rates per category (category_returns), break-even ROAS of Shopping and Performance Max campaigns (campaign_break_even, information only), low-stock products that the next save would put in Stars (save_settings_stock) and products where competitors undercut us while we spend (competitor_comparison). Each card has a state: ready (shown in the app), below_threshold (computed, too little at stake to show) or not_applicable (a source is missing: say which and how to connect it). Population: every catalogue item matched to a Google Ads item of the feed, not only the products get_product_context stores; computed for properties with a Product Segmentation subscription only. Quote the numbers with their dataAsOf per source and the footnote; describe what happened together, never a cause, and never turn break-even into a bid change.

get_highlightsCopy Anchor Link

Product Segmentation highlights · Read-only · reads Product Metrics data · any workspace member

The property’s Product Segmentation highlights over its saved date range: revenue, ad spend and ROAS in total, the spend going to Drainers (products that spend without returning) and the ROAS Product Segmentation estimates if that spend earned what Stars and Question Marks earn. Use for how the account is doing overall, to size the waste before drilling into products, or to open a monitoring update. These are Product Segmentation’s numbers and segments: explain them, never relabel products or promise the uplift.

get_inventory_stateCopy Anchor Link

Inventory state · Read-only · reads Product Metrics data · any workspace member

Stock from the connected shop: on hand, units sold per week, weeks of cover, stockout and reorder dates, the suggested reorder quantity and slow movers, with the lead time behind them. Pass item_ids for specific products, or leave them out and pick a filter (‘reorder_due’, ‘slow_movers’ or ‘all’) to list the shop’s products that need stock attention; list rows carry the shop’s product id, variant id and SKU (search_products with the SKU finds the item_id). Use for stock, reorder and ‘can we keep advertising this’ questions. Reorder dates and quantities are the planner’s: report them, do not order or pause anything.

get_competitor_offersCopy Anchor Link

Competitor offers · Read-only · reads Product Metrics data · any workspace member

The latest price of every seller of one product from the competitor price scraper over the last days: our own offer first, then competitors from cheapest, each with its gap to our price in percent and when it was seen. Use for ‘who is cheaper’, ‘what does this seller charge’ or to check a price-position signal from get_product_context. One product per call: to rank many products use the market layer of get_product_context instead. Report the gaps and their age; price and label changes are the merchant’s and the algorithm’s call.

HistoryCopy Anchor Link

Day-by-day history of a product, a group of products or the segments.

get_product_timeseriesCopy Anchor Link

Product history · Read-only · reads Product Metrics data · any workspace member

Daily or weekly history for one product. By default returns a summary per measure (total, recent change, trend per week, level shift date, outliers), which is what you should reason from. Ask for format=‘csv’ only when you must inspect individual points; prefer grain=‘week’ for more than 60 days. History holds about 90 days, for the top products by spend only, and only the measures the sources record (ad and session measures; stock, price and gross profit series only where connected): the result names measures that are not recorded. Ratios such as ROAS/POAS are not series: compute them from the summed measures, or use the advertising window in get_product_context.

get_group_timeseriesCopy Anchor Link

Group history · Read-only · reads Product Metrics data · any workspace member

Summed daily or weekly history across several products: the top products by ad spend or conversion value (optionally within a Product Segmentation segment or a category), or a list of item_ids. Use it for the trend of a group or the portfolio (is revenue growing, week by week for our top 20, did a segment change) instead of reading products one by one. Returns the summed series as a table, a summary per measure, the dates the data covers and how many of the products have history (only some do): say which products and weeks the result covers. Ratios such as ROAS come from the summed conversionValue and cost.

get_segment_historyCopy Anchor Link

Segment history · Read-only · reads Product Metrics data · any workspace member

How one product moved between segments (stars, cash_cows, question_marks, dogs, drainers, ghosts, or not_in_feed) over the last days, from the daily segment snapshots of its feed. Each move comes with the product’s Google Ads spend and conversion value in the 7 days before vs the 7 days from the move (null where not cached) and the campaign and Product Segmentation settings changes within 7 days of it. Use when the user asks why a product changed segment, when it dropped out of Stars or Cash Cows, or whether a move followed a settings change; point to the spend and value before vs after the move and the changes around it. A segment describes the 30 days of results before the day it was captured: say plainly that it explains the past and does not predict future profit.

ProposalsCopy Anchor Link

File a proposed change for a person to approve in Priorities, and list existing proposals. Filing a proposal never changes Google Ads or the store by itself.

propose_changeCopy Anchor Link

Propose a change · Files a proposal · reads Product Metrics data · editors and admins only

Propose a change for a person to approve: a Merchant Center custom label, a priority, or a task (e.g. reorder). Nothing is written to Merchant Center until a person approves it. Always pass the context_version you based the proposal on and a rationale that cites the layers and signals behind it.

list_proposalsCopy Anchor Link

Proposals · Read-only · reads Product Metrics data · any workspace member

Proposals in the Priorities ledger with their status and, once measured, an outcome: the 28 days after the change was applied versus the 28 days before. An outcome with verdict “causal” carries outcome.did, an estimate against matched products that did not change: causal: compared with matched products that did not change, the 95% interval of the effect excludes zero and a placebo check 28 days earlier found none. Only for that verdict may you say the change caused the effect, quoting the estimate and its interval. Every other outcome is directional: before/after, may reflect season, budget or competitors: report how the numbers moved and never say the change caused it. Use to avoid duplicate proposals and to report how metrics moved after earlier changes.

AdvancedCopy Anchor Link

Raw SQL over the store’s data, for questions the other tools cannot answer.

query_lakeCopy Anchor Link

Query the lake · Read-only · reads Product Metrics data · any workspace member · counts towards the hourly limit for expensive tools

Last resort, costing far more than the other tools: one read-only SELECT over this property’s lake tables, for what they cannot answer, e.g. a custom daily breakdown, a total across all products or a window the context does not hold. Use the logical table names below exactly (the tenant scope is applied for you). Lake column names are not the other tools’ field names: use the columns listed below and the mapping after them. No comments, UNION or writes. Results are capped and carry the data age per source; dates outside a table’s range are missing, not zero, so state the first and last date the result covers. Aggregate in SQL; never select raw rows you do not need.