Skip to main content
Glama

Nova Amazon MCP Server

explain_movement

Read-only

For one SKU, pull the causal signal bundle (traffic, conversion, price, buy box, promotions, ads, rank) for a period vs a baseline, so you can reason about WHY its sales moved. Returns each signal with value, comparison value and variance. 💱 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": {
      "sku": "<sku>",
      "from": "<from>",
      "to": "<to>",
      "comparisonFrom": "<comparisonFrom>",
      "comparisonTo": "<comparisonTo>"
    },
    "name": "explain_movement"
  }
}

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).
skuYesThe SKU to explain.
fromYesPeriod start, INCLUSIVE (YYYY-MM-DD).
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.
comparisonToYesBaseline period end (inclusive).
comparisonFromYesBaseline period start (inclusive).

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 it a non-destructive read, and the description goes well beyond them: it states the response carries value, comparison value and variance per signal, that unserved Vendor Central metrics come back null with an unservedMetrics note rather than 0, that currencyBasis/currencyNotice must be relayed, and that pnlRulesNote must be surfaced once. It also discloses that P&L rules change every line a rule touches — exactly the kind of caveat annotations cannot express.

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 sentence is a strong, front-loaded summary, but the body is roughly 800 words of Vendor Central accounting semantics and P&L rule enumeration that an agent calling this tool rarely needs. The emoji section headers aid scanning, yet substantial blocks (vendorInvoiced/vendorShippedCogs/netProfit definitions) are reference material rather than invocation guidance, burying the operative instructions.

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 10-parameter, no-output-schema read tool this is essentially over-complete: it explains inputs, the returned signal bundle shape, the currency and channel metadata keys, the null-vs-zero metric behaviour, and the pnlRules caveats. Nothing an agent needs to invoke it correctly or interpret the answer is missing.

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 100%, so the baseline is 3; the description still adds meaning the schema does not, notably the rationale for pinning currency (reproduce a figure the seller saw on a dashboard in another currency) and the consequence of reading with pnlRules="default". Much of the channel and P&L prose duplicates the property descriptions, so it does not rise to 5.

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?

Opens with a specific verb, resource and scope: 'For one SKU, pull the causal signal bundle (traffic, conversion, price, buy box, promotions, ads, rank) for a period vs a baseline'. The enumerated signals and the 'WHY its sales moved' framing let an agent distinguish this diagnostic tool from sibling listers such as find_movers, describe_metric or query_metrics 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 Guidelines4/5

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

Gives explicit conditional guidance for the tricky decisions: pass channels=['VENDOR'] only when the user asks for Vendor Central/1P, ['SELLER','VENDOR'] when they want a total across programmes, and 'NEVER add 3P and 1P figures yourself'. It also tells the agent when to pin currency and when to pass pnlRules="default". It stops short of naming a sibling alternative (e.g. find_movers for 'which SKUs moved'), so 4 rather than 5.

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.