Skip to main content
Glama

Nova Amazon MCP Server

query_advertising

Read-only

Amazon advertising console — Sponsored Products + Sponsored Brands + Sponsored Brands Video + Sponsored Display + Full-Funnel campaigns — at the AD PRODUCT / PORTFOLIO / CAMPAIGN / AD GROUP / KEYWORD grain, the same pipeline as the app's PPC page. Answers: which keywords or campaigns waste spend (high spend, low sales, high acos), where to cut or raise bids, which keyword drives sales on a given ASIN/SKU, which placement (top of search vs product pages) the money goes to, where the money goes across ad products. groupBy takes the ad product (adProduct), an ad-structure grain (portfolio, campaign, adGroup, targetingType, targetingDetail, keyword), the placement grain, a product grain (childAsin, sku), or a TIME grain (day/week/month/quarter/year) for a series in ONE call. Keyword rows carry BOTH bids: bid is the target's current setting (falling back to the ad group default) and reportedBid is the bid Amazon reported on the last day of the window. Metric keys are a SEPARATE universe from list_metrics — use ONLY: spend, sales, sales14d, impressions, clicks, orders, units, units14d, acos, roas, cpc, ctr, cvr, marginBeforeAds, breakEvenAcos, profitAfterAds, spendWithoutSales, newToBrandOrders, newToBrandSales, newToBrandUnits, videoCompleteViews, viewableImpressions, brandedSearches, topOfSearchImpressionShare. 🏷️ THE BRAND KEYS (2026-09-17) are what only the Sponsored Brands / Brands Video / Display reports publish: newToBrandOrders / newToBrandSales / newToBrandUnits (14-day, click-attributed), videoCompleteViews (video rows only), viewableImpressions, brandedSearches; and topOfSearchImpressionShare, the share of top-of-search impressions the TARGET won (0-100, impression-weighted when rows are grouped): Sponsored Brands / Brands Video at any grain, and Sponsored Products at a TARGET grain only (groupBy keyword / targetingType / targetingDetail), from September 2026 (earlier days are null). ⚠️ It is NOT the console's 'IS | IR' (search-term impression share and rank): those ride on the KEYWORD rows as attributes, attrs.searchTermImpressionShare (0-100) and attrs.searchTermImpressionRank (1 = first), Amazon's numbers per account × marketplace × keyword TEXT over a rolling 30 days ending on attrs.searchTermImpressionAsOf (the latest daily snapshot, from 2026-09-18), independent of the period and NOT additive: never sum or average them; Sponsored Products keywords only, null on product targets and on every other ad product. Sponsored Products publishes none of the other six: with adProducts limited to sponsored_products (the default) they come back null on every row with an unservedMetrics note, never a 0 — pass the other ad products to read them; topOfSearchImpressionShare gets the same note when Sponsored Products is asked at a grain that is not a target grain. 💰 THE PROFIT KEYS answer 'is this advertising actually making money': marginBeforeAds is the P&L's Margin before Ads of the advertised products (exact per ASIN and marketplace, ad-sales-weighted elsewhere), under the organization's saved P&L rules and its own costs as the app's P&L page shows it (the answer then carries pnlRules and pnlRulesNote, to relay once), breakEvenAcos is the same number read against ACOS (spending above it loses money), profitAfterAds is (margin x ad sales) - ad spend, and spendWithoutSales is the spend on TARGETS with zero attributed sales over the whole period (not per day). Asking for any of them joins the P&L and resolves the attributed target_asin cut, so spend/sales on those rows become the attributed estimate rather than the exact advertised reading (it re-sums within 0.01%); omit them for the exact reading. They cannot be combined with the placement grain or a search-term filter (neither carries an ASIN or a target) and the call is refused with a message saying so. They are Sponsored Products / Sponsored Display keys: with sponsored_brands, sponsored_brands_video or full_funnel in adProducts they come back null on every row with an unservedMetrics note (per-ASIN Sponsored Brands is an allocation — query_metrics serves it; a Full-Funnel campaign's sales cover the whole brand), never a refusal; likewise the margin keys at a target grain with sponsored_display (no SD target → ASIN attribution). Sponsored Brands has no advertised-product report either, so childAsin / sku / parentAsin / tags with it are refused by name. ⚠️ Never sum or compare these with query_metrics' ad metrics (adSpend & co cover SP+SD+SB allocated to products, over the full history) — totals legitimately differ. ⚠️ Placement rows cannot be combined with a keyword or product dimension (Amazon reports placement per campaign only); such a combination is refused rather than silently emptied. Returns rows with value, comparison value and variance, plus the reporting currency. 🧭 AD PRODUCTS: the console serves Sponsored Products, Sponsored Brands, Sponsored Brands Video, Sponsored Display and Full-Funnel campaigns as DISJOINT blocks of rows — adProducts picks which (default ['sponsored_products'] until the fact serves the others; pass several to read them in ONE call, or groupBy='adProduct' to split the money by product). Each block is read from its own cut of the fact at its OWN attribution window: SP orders/sales/units are 7-day on a Seller Central account and 14-day on a Vendor Central account (each console's own window), SB and SBV 14-day, SD 14-day after a click OR a view, as Amazon's console counts them (the *14d metrics keep the clicks alone) — so never sum or compare sales, orders, ACOS or ROAS across products; spend is the ONE additive column across all of them, sponsored_brands + sponsored_brands_video (one report, split per row) the ONE additive pair, and sales14d / units14d the like-for-like 14-day reading. Sponsored Display has no search-term and no placement report (such a call is refused by name). Entity rows carry attrs.adProduct; it is null on a VALUE row (an ASIN, a placement, a targeting type, a search term) that folds two products. 🎯 FULL-FUNNEL ('full_funnel'): Amazon's Full-Funnel campaigns, ONE campaign serving on Amazon, off Amazon and on streaming video. Read them in total, over time, by campaign, or by product (childAsin / sku / parentAsin: the spend Amazon reports on no product, streaming video mostly, is one row with no ASIN, so the products re-sum to the campaign). They have no ad group, no keyword or target, no search term and no placement of this console: those grains and filters are refused by name. Their sales / orders / units are EVERY sale Amazon attributes to the campaign, the promoted products and the rest of the brand together, at a window Amazon does not state; sales14d / units14d, the profit keys, newToBrandUnits, viewableImpressions, brandedSearches and topOfSearchImpressionShare come back null with an unservedMetrics note, while newToBrandOrders, newToBrandSales and videoCompleteViews are served. A campaign Amazon's weekly report has not named yet reads its id without a name, and their current day is as of Nova's last hourly build, not the live stream. The P&L counts the same campaigns' cost as fullFunnelCost (query_metrics), where the part on no product is shared among the campaign's products. ⏳ HISTORY & ROUTING: this console route is built on Amazon's per-product advertising reports, so EACH AD PRODUCT HAS ITS OWN HISTORY FLOOR — the response's historyStartsAtByProduct is the first day held per product for the queried accounts (Sponsored Products ~95 days of report retention, Sponsored Brands / Brands Video 60 days, Sponsored Display 65–95 days; all backfilled ~60 days before the account's Ads connection; Full-Funnel from the first day Amazon's Full-Funnel report or its ads spend stream delivered for the account), and historyStartsAt is the earliest floor among the products you queried. Nothing before a product's floor is served for it (null, never zero spend). For ad TOTALS by account, product or period, and for ANY year-over-year or long-history comparison that needs no ad-product / portfolio / campaign / ad group / keyword / search-term / placement breakdown, use query_metrics instead (adSpend, sponsoredSales, organicSales, sponsoredAcos, sponsoredRoas, sponsoredTacos, impressions, clicks, costPerClick, clickThroughRate): it carries the whole ads history Nova holds for each account (from ~60 days before its Ads connection, complete from there; adsHistory gives the first day when a period starts earlier), Sponsored Products + Display + Brands allocated to products, plus the Full-Funnel campaigns. routingNotice, when present, says which route to prefer and where this one's history starts — relay its history part to the user whenever a requested period precedes a queried product's floor. 🕒 CURRENT DAY: on Seller Central accounts the current day is served live, from Amazon's hourly advertising stream, through the last hour Amazon has finished delivering (an hour that ended 45 minutes to two hours ago; the hour being delivered is left out, it holds its spend before its sales): all four ad products at the total, time, adProduct, portfolio and campaign grains, and Sponsored Products / Sponsored Display at the adGroup, childAsin and sku grains too. Attributed orders and sales of a recent day keep growing as Amazon attributes them. The keyword / targetingType / targetingDetail and placement grains, and Vendor Central accounts, follow Amazon's reports instead: their current day arrives hours later and can read lower than the live total — say so, never sum the two, and read a current-day total at a grain that is served live. ⏱ INTRADAY: the smallest grain of this tool is the DAY, and the current day is partial until it ends — its total against a whole earlier day is not a like-for-like comparison. For today by the hour, today against another day at the same time of day, the campaigns out of budget right now or the latest orders, use query_live. TODAY as this tool reads it: each marketplace on its own day; the orders within about a minute; the ad figures of an account through the last hour Amazon has finished delivering to THAT account, 45 minutes to two hours behind the clock — so today's TACOS and profit set sales to the minute against ad spend an hour behind, and are provisional. query_live reads today on ONE clock and holds an hour for every account once the first has it: over several time zones or several accounts its total for today can differ from this tool's, and neither is wrong. 💱 CURRENCY: monetary values are served in the caller's Nova display currency when it is one of the organization's configured currencies (its primary or up to four secondary currencies), else in the organization's primary. In the response, currency is the code, currencyBasis says why (user_preference | organization | pinned) and currencyNotice, when present, MUST be relayed to the user. Quote the code; never assume a symbol from the marketplace. Pass currency to pin any configured code — e.g. to reproduce a figure the seller read on a dashboard set to another currency.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "metrics": "<metrics>",
      "from": "<from>",
      "to": "<to>"
    },
    "name": "query_advertising"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesPeriod end, INCLUSIVE (YYYY-MM-DD): a calendar month is from=YYYY-MM-01 to=its LAST day. to=the 1st of the next month adds one extra day to every total (and one extra bucket with a time grain).
fromYesPeriod start, INCLUSIVE (YYYY-MM-DD).
skusNoAttributed product SKUs.
tagsNo"Your Filters" tag IDS from list_tags — a tag NAME is rejected.
limitNoRows per call of an entity grouping, 1 to 1000 (default 50). A time grain is never cut: its series comes whole, in date order, 1000 buckets at most.
reasonNoOne sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used.
sortByNoADS metric key to rank rows by (e.g. "spend"). Refused with a time grain: a series comes in date order.
groupByNoAd product (adProduct), ad-structure grain (portfolio/campaign/adGroup/targetingType/targetingDetail/keyword), placement, product grain (childAsin/sku), or time grain. Omit for a single total row.
metricsYesADS metric keys (spend, sales, acos, roas, marginBeforeAds, breakEvenAcos, profitAfterAds, spendWithoutSales, newToBrandSales, viewableImpressions, topOfSearchImpressionShare, …) — NOT product keys from list_metrics.
accountsNoRestrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id.
channelsNoONE Amazon programme per call. 'SELLER' = Seller Central (3P) advertising: the seller's own Amazon Ads campaigns. 'VENDOR' = Vendor Central (1P) advertising: the campaigns of the vendor's own Amazon Ads profile. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR. Pass ['VENDOR'] only when the user asks about Vendor Central / 1P advertising. Both at once is refused: 3P and 1P spend and sales are never added into one total. On a Vendor Central read the margin keys (marginBeforeAds, breakEvenAcos, profitAfterAds) come back null with an `unservedMetrics` note: Amazon attributes 1P ad sales at its retail price, while the vendor's margin is earned on what Amazon pays it.
currencyNoPin the reporting currency: one of the organization's configured codes — its primary or any of its secondary currencies (e.g. "USD"). Omit to follow the caller's Nova display currency, the dashboard's rule. Any other code is refused.
sortFieldNoWhat to rank on: 'value' (default), or 'variance' / 'variancePercentage' (need a comparison period).
sortOrderNodesc (default) = biggest first.
adGroupIdsNo
adProductsNoWhich ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display, full_funnel (Amazon's Full-Funnel campaigns: by campaign or by product only). Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note.
childAsinsNoAttributed child ASINs.
keywordIdsNo
placementsNoNormalized placement buckets. Only answerable on the placement cut (no keyword/product dimension alongside).
campaignIdsNo
parentAsinsNoFamily keys — resolved to child ASINs server-side.
comparisonToNoBaseline period end (inclusive).
marketplacesNoMarketplace IDs.
portfolioIdsNoPortfolio ids as returned by groupBy="portfolio". "0" is the campaigns-in-no-portfolio bucket.
metricFiltersNoServer-side threshold filters (ANDed) on ADS metrics — e.g. spend > 100 AND sales < 1 for wasted spend. Needs an ads entity grouping.
comparisonFromNoBaseline period start (inclusive) — enables variance.
targetingTypesNoe.g. keyword, auto, product, category.
targetingDetailsNoMatch types (exact/phrase/broad) or auto groups (close-match/loose-match/complements/substitutes).
excludeUnfinishedNoExclude the current, still-incomplete period so a partial day/week/month is not read as a drop.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / adProducts / description
      Previous value: -"Which ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display. Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note."New value: +"Which ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display, full_funnel (Amazon's Full-Funnel campaigns: by campaign or by product only). Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note."
    • changedInput schema / properties / adProducts / items / enum
      Previous value: -[
      -  "sponsored_products",
      -  "sponsored_brands",
      -  "sponsored_brands_video",
      -  "sponsored_display"
      -]New value: +[
      +  "sponsored_products",
      +  "sponsored_brands",
      +  "sponsored_brands_video",
      +  "sponsored_display",
      +  "full_funnel"
      +]
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only annotations, the description discloses per-ad-product attribution windows, history floors, current-day partiality, currency and notice behavior, refusal conditions, and how profit keys join the P&L and alter spend/sales readings. These are substantial operational details the annotations do not cover, and nothing contradicts readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is organized into thematic sections, but the description is extremely long, dense, and repetitive, with multiple all-caps warnings and emoji markers that make it hard to scan. Several caveats about null metrics and cross-product comparisons are restated, so many sentences do not earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 29-parameter analytical tool with no output schema, the description is complete enough: it explains row values, comparison values, variance, currency, history floors, and routing notices. It also covers complex edge cases across ad products and grains, so an agent has the context needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 90%, the description adds important meaning beyond the schema: metric keys form a separate universe from list_metrics, groupBy time grains produce a series in one call, keyword rows carry both bid and reportedBid, and profit keys change spend/sales to an attributed estimate. It also explains prohibited combinations such as placement plus keyword/product dimensions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-and-resource statement: Amazon advertising console across Sponsored Products/Brands/Brands Video/Display/Full-Funnel at named grains, answering concrete PPC questions. It explicitly distinguishes itself from list_metrics, query_metrics, and query_live, so an agent can identify its role without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing rules: use query_metrics for ad totals and long-history comparisons, query_live for intraday and out-of-budget checks, and this tool for ad-product/portfolio/campaign/ad-group/keyword/placement breakdowns. It also states when calls are refused or metrics come back null with an unservedMetrics note.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.