Skip to main content
Glama

Nova Amazon MCP Server

query_metrics

Read-only

Query the seller's metrics over a period, optionally grouped and compared to a baseline period. groupBy takes EITHER an entity grain (sku, childAsin, parentAsin, marketplace, sellerAccount), OR "tag" with drawer — one row per tag of one of the seller's own "Your Filters" drawers (list_tags): THE way to read sales, profit or any metric per BRAND, CATEGORY or supplier when the seller tagged the catalog —, OR a TIME grain (day, week, month, quarter, year). tags restricts any read to the SKUs carrying the given tags (ids from list_tags). Use a TIME grain to get a whole time series in ONE call — e.g. groupBy="month" from Jul to Jun returns all 12 monthly rows at once; never call this once per month. Entities batch the same way: for MANY SKUs/ASINs, pass the whole list (skus/childAsins/parentAsins) with an entity groupBy and read all the rows from ONE call — never loop one call per SKU or ASIN. Rank rows with sortBy+sortOrder (e.g. the top SKUs by netSales) and keep only rows meeting a threshold with metricFilters (e.g. SKUs with netProfit < 0) — both run server-side, so never fetch everything and filter yourself. Returns rows with value, comparison value and variance, plus the reporting currency. 📣 ADVERTISING TOTALS & HISTORY: this tool ALSO serves advertising at the account, product and period level — adSpend, sponsoredSales, organicSales, sponsoredAcos, sponsoredRoas, sponsoredTacos, impressions, clicks, costPerClick, clickThroughRate (Sponsored Products + Display + Brands, allocated to products, plus the Full-Funnel campaigns) — over the WHOLE ads history Nova holds for each account: from about 60 days before its Ads connection, complete from there (NOT a rolling 60-day window; adsHistory + adsHistoryNotice give the first day per account when a requested period starts earlier). Use THIS tool for ad totals, trends and year-over-year comparisons that need no ad-product / campaign / ad group / keyword / search-term / placement breakdown; query_advertising is the advertising CONSOLE for those breakdowns — Sponsored Products + Brands + Brands Video + Display + Full-Funnel as disjoint blocks, each at its own attribution window (SP 7-day on Seller Central and 14-day on Vendor Central, SB 14-day, SD 14-day after a click or a view, Full-Funnel every sale attributed to the campaign) and its own history floor (~60 days before the Ads connection at best). ⏱ 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. ⚠️ CAVEATS: the response may carry cogsNotice (units sold with no COGS — profit and margins overstated; cogsCoverage always comes with a COGS-based metric), marketplaceNotice (the totals add up several marketplaces, e.g. US + CA + MX on a North America account, while Amazon screens show one), adsHistoryNotice (part of the period predates the account's ads data) and subscribeAndSaveNotice (Subscribe & Save figures of a period not final yet, or partly without S&S data). Each notice, when present, MUST be relayed to the user before the figures it qualifies. 🔁 SUBSCRIBE & SAVE (Seller Central only): shippedSubscriptionUnits (S&S Units), totalSubscriptionsRevenue (S&S Sales), lostSubscriptionsRevenue (S&S Sales Lost to Stockouts) and missedSubscriptionUnits (S&S Units Missed to Stockouts: Nova's estimate, in units, of the subscription deliveries Amazon missed for lack of stock, from Amazon's report; a floor when a day cannot be priced) are flows summed over the days, final 7 days after the day. subscribeAndSaveDiscount (S&S Discount Funded) is the discount the seller funded on subscriber orders, read from the order lines rather than from Amazon's S&S report, on the SKU of each order line, so neither the report's delay, its S&S data coverage nor the per-ASIN rule below applies to it. It moves with the order lines like productPromotions (Customer promotions), of which it is a part, served with its sign (never add the two): its last days rise as subscriber orders ship, and an order line can still be revised for weeks. On a line that also carried a coupon it is an estimate, usually low. Read it next to S&S Sales and never subtract it from S&S Sales, which is neither gross nor net of it. activeSubscriptions is a LEVEL, known 4 days after the day: the subscriptions active at the END of the period (each account and marketplace on its last day with S&S data in the period, added up across them), never added up over days nor averaged; in a time series each bucket is the level at its own end. salesPenetration (S&S Sales divided by product sales, both summed over the days that have S&S data only) and subscriptionsStockoutRate (S&S Sales Lost to Stockouts divided by S&S Sales plus that loss, both summed over the period, a day Amazon has not served counting on neither side) are ratios of sums, final 7 days after the day: never average daily or per-product values, ask for the period and the grouping you need. A period that ends within a figure's delay is PARTIAL: its figure is served flagged as partial, with the day it becomes final (its last day plus the delay); a period with no final day yet has no value: its figure is null (never the 0 or the partial amount Amazon has published so far), and a ranking or a threshold on it is refused. A period that holds days Nova has no S&S data for (before the account's S&S history, a day missing or held out, a feed that stopped) is INCOMPLETE, with no day to become final. When either period of a comparison is partial or incomplete, the S&S figure keeps its value but its change (variance, variance_percentage) is null. Never present a partial or incomplete figure as complete, nor compare it with another period: a partial or incomplete sum is too low, never a drop. Amazon reports S&S per ASIN, and Nova puts each ASIN's S&S figures on ONE of its SKUs (the first in alphabetical order): a sku or tag row, or a skus or tags filter, therefore holds the whole ASIN's figures or none of them, so read S&S per childAsin or coarser. The answer says which periods are partial or incomplete, and why, in subscribeAndSaveNotice (relay it) and subscribeAndSaveCoverage (per period state and finalBy for the delay and complete; per account and marketplace its days without data). The state of the programme and of each product today is query_subscribe_and_save. 🧾 COST CATEGORIES: every cost has one of four categories (variable, product, oneOff, account; costCategory in list_metrics / describe_metric, and the totals orderCosts "Variable costs", productCosts, oneOffCosts, accountCosts). To compare products on their recurring economics, pass costCategories rather than subtracting lines yourself: the response then carries costCategories (what was counted) and costCategoriesNote, which you MUST relay, since the figures are no longer the P&L the app shows by default. 💱 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. 🏷️ 3P / 1P: an Amazon account sells through ONE programme: Seller Central (3P, channel SELLER: the seller sells its products to Amazon's customers) or Vendor Central (1P, channel VENDOR: Amazon BUYS the products from the vendor and resells them itself). On a Vendor Central read, the basis of units, sales and netSales is the answer's vendorTopLineNetReceived (said in its channelNote): when it is 1, units and sales of a Vendor Central row are Amazon's net received (what Amazon received from the vendor, net of what it returned, at its cost, on the day of the receipt: the Net received of the Vendor Central console) and netSales the net received less the quick-pay and early-payment discounts; what the vendor invoiced reads in vendorInvoiced; when it is 0, units and sales are what the vendor invoiced Amazon (its books, at the invoice date) and netSales the invoiced amount less Amazon's claims; Amazon's shelf (what it shipped to its customers, at its retail price, the latest days provisional, on ordered units) is read with vendorShippedUnits, vendorShippedRevenue and vendorShippedCogs. A vendor's profit is netProfit, the P&L's Net Profit: the P&L's top line (Amazon's net received when the answer's vendorTopLineNetReceived is 1, what the vendor invoiced Amazon when it is 0) less what Amazon takes off (its claims on the invoices, the discounts, the co-op, the chargebacks, the returns to vendor), the product cost and the ad spend. vendorShelfProfit is the result on what Amazon shipped, at the ship date: Amazon's shelf, the figure to compare products on, never added to the P&L. channel in list_accounts says which programme each account sells through. A call reads Seller Central, unless you pass channels=['VENDOR'] (do so only when the user asks about Vendor Central / 1P), the accounts of the call are all Vendor Central accounts, or you pass channels=['SELLER','VENDOR'] for All channels (when the user asks for the total across both programmes): Nova then reads both together as the app's All channels reading does, adding the seller's sales and the vendor's P&L top line. NEVER add 3P and 1P figures yourself: ask for All channels, or make one call per channel and present the two side by side, labelled 3P and 1P. When your scope holds a Vendor Central account the response says which channel it read ('SELLER', 'VENDOR' or 'ALL'), and channelNote what it read and what it left out; a metric the channel does not report (sessions, buy box, promotions on Vendor Central) comes back null with an unservedMetrics note, never 0. 🧮 BASIS: basis picks which P&L the figures are. Omitted or "order" (what this tool always served): the order-based P&L, every amount at the day the order was purchased, the last days brought up to the live orders. "cash": the cash-based P&L, every amount at the day Amazon POSTED it, RELEASED postings only (a DEFERRED posting is a reserve, not cash) — the reading that ties to the settlement reports; no live overlay, Seller Central accounts only, and refused (never answered on the other basis) where the cash P&L is not enabled. Pick "cash" when the user speaks of settlements, payouts, disbursements, what Amazon paid, or reconciling with the bank; keep the order basis for sales performance. A cash answer carries basis: "cash" and a basisNote to relay once. What separates the two readings of a month is query_pnl_bridge. 📏 P&L RULES: the figures apply the P&L rules saved in Nova for this credential's organization, the P&L as the app shows it (a fee excluded from the fee total reads 0 on its line and is in no total; storage, long-term storage and paid services fees spread evenly over their month; margins on net sales; the FBM cost inferred from the shipping price; the VAT on Amazon fees booked as a cost; a share of refunded FBM units counted as put back on sale). When any rule is on, the answer lists them in pnlRules and carries pnlRulesNote, which you MUST relay once: a figure read without them (Seller Central, another tool) differs on every line a rule touches. Pass pnlRules="default" to read with no rule, as Amazon billed; the answer then says which rules the app applies. An organization that saved no rule reads as it always did, with neither key.

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_metrics"
  }
}

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).
skusNo
tagsNo"Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations) — a tag NAME is rejected. Tags of one drawer OR together, tags of different drawers AND together (the dashboard rule).
basisNoWhich P&L the figures are. Omit, or "order", for the order-based P&L this tool always served: every amount at the day the order was purchased, the last days brought up to the live orders. "cash" for the cash-based P&L: every amount at the day Amazon POSTED it, RELEASED postings only (a DEFERRED posting is a reserve, not cash), the reading that ties to the settlement reports — no live overlay, Seller Central accounts only, refused where the cash P&L is not enabled (never answered on the other basis).
limitNoRows per call of an entity grouping, 1 to 100 (default 50); beside `timeGrain`, the entities, each with its whole series. A time-grain groupBy is never cut: its series comes whole, in date order, 1000 buckets at most.
drawerNoThe drawer whose tags make the rows when groupBy is "tag": a drawer `id` from list_tags (one of the seller's own classifications — Brand, Category, Supplier…), never a tag id or a name. A SKU carrying no tag of the drawer is in no row; a SKU carrying two of its tags counts in both. `summary.total` stays the total of the WHOLE scope (every SKU of the accounts, tagged or not — the dashboard's Total row), so it is NOT the sum of the rows: the gap is what the SKUs without a tag of the drawer weigh. `drawer` alone implies groupBy "tag".
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.
sortByNoMetric key to rank rows by (e.g. "netSales") — how you get "top/bottom N by X". Refused with a time-grain groupBy: a series comes in date order. Beside `timeGrain`, it ranks the entities.
groupByNoEntity grain (sku…), "tag" (the tags of ONE drawer — pass `drawer`; rows carry `tagId` / `tagName`), OR time grain (day/week/month/quarter/year). Use a time grain for a full time series in ONE call. Omit for a single total row. A metric not defined at the row grain (sessions, conversionRate or pageViews per sku — Amazon reports traffic per ASIN) comes back null on every row with an `unservedMetrics` note, never a 0; group by childAsin to read it.
metricsYesMetric keys from list_metrics (sales, units, netProfit, refundedUnits, commissionFee, totalAmazonFees, adSpend, sponsoredSales…). Natural names are accepted when they mean exactly one metric — tacos, acos, netMargin, avgPrice, pageViews, unitsSold, unitSessionPercentage… — and resolved to the key; the response lists what was resolved under `metricAliases`. Names that could mean several metrics (refunds, margin, revenue) are refused with the candidates spelled out. Inventory/stock quantities (totalFbaAvailable, daysOfInventory…) are NOT metrics — use query_inventory for stock.
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.
channelsNoThe Amazon programme the call reads. 'SELLER' = Seller Central (3P): the seller's own sales to Amazon's customers. 'VENDOR' = Vendor Central (1P): Amazon buys the products from the vendor and resells them. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR. Pass ['VENDOR'] only when the user asks for Vendor Central / 1P figures. Pass ['SELLER','VENDOR'] for All channels, when the user asks for the total across both programmes: Nova reads them together as the app's All channels reading does, adding the seller's sales and the vendor's top line (Amazon's net received when the answer's vendorTopLineNetReceived is 1, what the vendor invoiced Amazon when it is 0), while a metric one programme measures stays that programme's figure.
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.
pnlRulesNoWhich P&L rules the figures apply. Omit, or "saved", for the rules saved in Nova for this credential's organization (the P&L as the app shows it: fees excluded from the fee total, storage fees spread over the month, margins on net sales, FBM cost from the shipping price, fee VAT booked, FBM returns recovered). "default" reads with no rule, as Amazon billed: to compare with Seller Central or another tool, or when the user asks for the figures before any rule.
segmentByNoBreak EACH grouped row into its top sub-rows at this finer grain, ranked, in ONE call (each row gets a `segments` array). Must be strictly finer than groupBy in the hierarchy sellerAccount>marketplace>parentAsin>childAsin>sku — or any product grain when groupBy is a TIME grain (top products per bucket) or "tag" (top products per tag). E.g. groupBy="marketplace" + segmentBy="sku" = top SKUs per marketplace; groupBy="day" + segmentBy="childAsin" = top ASINs per day. For a chronological series per entity, use `timeGrain` instead.
sortFieldNoWhat to rank on: 'value' (default), or 'variance' / 'variancePercentage' (need a comparison period).
sortOrderNodesc (default) = biggest first, asc = smallest first.
timeGrainNoEntity×time-series mode: set a calendar grain ALONGSIDE a product groupBy (childAsin, sku, parentAsin or tag) to get each entity's chronological, gap-filled `series` of buckets over the whole period in ONE call — e.g. groupBy="childAsin" + timeGrain="day" = every ASIN × every day; NEVER loop one call per ASIN or per day. Requires `limit` (the entity page bounds the series); incompatible with comparison periods, metricFilters and segmentBy. Without any groupBy it is read as groupBy=<grain>: a plain series of totals.
childAsinsNo
parentAsinsNo
comparisonToNoBaseline period end (inclusive).
marketplacesNoMarketplace IDs.
segmentLimitNoMax sub-rows per group (default 10).
metricFiltersNoServer-side threshold filters (ANDed), in the SAME (displayed) terms as the returned values — e.g. netProfit < 0, or cogs > 1000 (a cost above 1000). Requires a PRODUCT grain in groupBy (sku, childAsin, parentAsin, marketplace, sellerAccount or tag): NOT available ungrouped, nor with a time grain (day/week/month/quarter/year).
comparisonFromNoBaseline period start (inclusive) — enables variance.
costCategoriesNoThe cost categories the figures COUNT. Omit for every cost (the default, the P&L as the app shows it). "variable" = triggered by a unit sold or returned: cost of goods, FBM cost, referral and closing fees, FBA fulfillment, refund costs. "product" = keeping the product in stock and replenished: storage, long-term storage, inbound transportation and placement, prep. "oneOff" = a decision or a correction on the product: removals, disposals, deals and coupons, Vine, inventory reimbursements and clawbacks. "account" = billed to the account whatever the products: subscription, paid services, EPR. A category left out reads 0 on its own lines and is out of every total (totalAmazonFees, grossProfit, netProfit, the margins); sales, units and advertising never move. PROFIT WITHOUT ONE-OFFS = netProfit with costCategories ["variable","product","account"]; the profit on unavoidable costs alone = ["variable"]. One-offs are often a net CREDIT (reimbursements), so a profit without them can be lower than net profit.
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. Changed1 schema field changed
    • addedInput schema / properties / pnlRules
      Added value: +{
      +  "description": "Which P&L rules the figures apply. Omit, or \"saved\", for the rules saved in Nova for this credential's organization (the P&L as the app shows it: fees excluded from the fee total, storage fees spread over the month, margins on net sales, FBM cost from the shipping price, fee VAT booked, FBM returns recovered). \"default\" reads with no rule, as Amazon billed: to compare with Seller Central or another tool, or when the user asks for the figures before any rule.",
      +  "enum": [
      +    "saved",
      +    "default"
      +  ],
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare a safe read, yet the description discloses far more: mandatory-to-relay notices (cogsNotice, marketplaceNotice, adsHistoryNotice, subscribeAndSaveNotice, currencyNotice, pnlRulesNote), partial/incomplete period semantics with null variance, and ads history extending to ~60 days before the Ads connection rather than a rolling window. It also documents that unserved metrics return null with a note rather than 0, and the settlement-only restriction of the cash basis.

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 first two sentences are well front-loaded, but the body is a multi-thousand-word wall mixing Subscribe & Save delays, cost categories, currency basis, 3P/1P channel semantics and P&L rules, liberally salted with emoji headers and ALL-CAPS emphasis. Nearly every fact is useful somewhere, yet the sheer bulk makes the definition hard to scan and buries the decision-critical routing at the top.

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 28-parameter analytics tool with no output schema, the description closes every consequential gap: it describes the returned row shape (value, comparison value, variance, currency), the basis/channel/pnlRules dimensions, and the caveat keys in the response. An agent has enough to call it correctly and report results honestly.

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

Parameters4/5

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

Schema coverage is already 89%, but the prose still adds meaning the schema does not: that drawer alone implies groupBy='tag' and that summary.total is the whole scope rather than the sum of tag rows, that a time grain returns the whole series in one call and must not be looped, and that metricFilters require a product grain. Much of it is restated schema text, which keeps it out of the top band.

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 opening states a specific verb and resource plus scope: query the seller's metrics over a period, optionally grouped and compared to a baseline. It then names the grains and explicitly separates this tool from query_advertising (breakdown console) and query_live (intraday), so an agent can place it without opening a 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?

Routing is explicit and repeated: use query_advertising for ad-product/campaign/placement breakdowns, query_live for today-by-hour or out-of-budget campaigns, query_subscribe_and_save for programme state, query_pnl_bridge to reconcile order vs cash basis, query_inventory for stock. It also says when to pass basis='cash', channels=['VENDOR'], and All channels, with the rule never to add 3P and 1P figures manually.

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.