Skip to main content
Glama

Nova Amazon MCP Server

find_movers

Read-only

Find the entities (SKUs by default) whose value moved the most for a metric between a period and a baseline. Use direction="down" to surface the biggest losers. This answers "which SKUs lost the most sales"; with tags (ids from list_tags) it ranks inside a brand or any tagged set. A metric of Amazon's S&S report is ranked only between two complete periods, past Amazon's delay and with S&S data every day: otherwise the answer has no rows, and notRanked and subscribeAndSaveNotice say why. 🧾 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. 📏 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": {
      "metric": "<metric>",
      "from": "<from>",
      "to": "<to>",
      "comparisonFrom": "<comparisonFrom>",
      "comparisonTo": "<comparisonTo>"
    },
    "name": "find_movers"
  }
}

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).
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).
limitNo
metricYesA single metric key, e.g. "netSales" or "units" (natural names that mean exactly one metric are accepted too).
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.
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.
dimensionNoWhat to rank. Defaults to sku.
directionNodown = biggest losers (default), up = biggest gainers.
comparisonToYesBaseline period end (inclusive).
comparisonFromYesBaseline period start (inclusive).
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.

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.4/5.0
Behavior5/5

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

Annotations only declare that this is a safe read; the description goes far beyond by disclosing that unserved metrics come back null rather than 0, that empty answers are explained by notRanked and subscribeAndSaveNotice, and which response keys must be relayed (currencyNotice, costCategoriesNote, pnlRulesNote, channelNote). It also states how Seller and Vendor figures are combined by the server rather than by the caller.

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 purpose is front-loaded, but the body is many hundreds of words of reference documentation (full 3P/1P accounting semantics, P&L rule enumerations, currency resolution rules) under emoji section headers — far more than an agent needs to select and invoke the tool. Much of it duplicates the schema and buries the operational guidance it does contain.

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?

With 15 parameters, no output schema and three enum-typed behaviours, the description carries the full burden and does so: it explains response keys, null-vs-zero semantics, currency basis, channel resolution and P&L rule effects. An agent has everything needed to interpret and relay the result.

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 93%, so most parameter meaning lives in the schema, and large parts of the description restate it (channel definitions, costCategories definitions). Where it adds real value is the intent behind parameters: pass costCategories rather than subtracting lines yourself when comparing recurring economics, pin currency to reproduce a dashboard figure, and use pnlRules='default' to compare against another tool.

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 sentence gives a specific verb, resource and scope: rank entities (SKUs by default) by how much a metric moved between a period and a baseline. It also names the two ranking knobs (direction, tags) and the Amazon S&S ranking precondition, so an agent can separate it from query_metrics or explain_movement 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 Guidelines4/5

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

Explicit when-to-use rules are given for the riskiest choices: pass channels=['VENDOR'] only when the user asks for Vendor Central/1P, ['SELLER','VENDOR'] only for All channels, and 'NEVER add 3P and 1P figures yourself'. It also explains when to pin currency and when to pass pnlRules='default'. It never names the neighbouring tools it competes with (query_metrics, explain_movement), so the routing is clear but not complete.

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.