Skip to main content
Glama

Nova Amazon MCP Server

query_subscribe_and_save

Read-only

SUBSCRIBE & SAVE: the programme's health, its offers and each product's state, from Amazon's own Replenishment figures (daily snapshots). Four sections. health (per account × marketplace, as of the latest snapshot): lastMonth (units, revenue, active subscriptions, revenue lost to stockouts, revenue penetration, coupons), retention (subscriptions retained after 30 / 90 days), subscribers (average revenue and reorders of a subscriber vs a non-subscriber, revenue from subscriptions with several deliveries / one delivery still active / one delivery then cancelled), fundingTiers (revenue share and sign-up conversion of the seller-funded discount tiers 0 / 5 / 10 / 5+ %), lifetimeValue (by customer segment, one-time purchases vs subscriptions) — every block carries ITS window: the base figures are last month, the others trailing 12 months (24 for lifetime value), and Amazon gives them per account only, never per ASIN. The health's amounts are in each marketplace's own currency (the row's currency), or in the currency you pass, one of the organization's configured codes: each block is then converted at the average daily rate over its own window, convertedFrom naming the marketplace's currency, and an amount whose window has no rate reads null, never unconverted. Pass the currency query_metrics answers in to read the amounts as the cockpit's Subscribe & Save program card shows them. offers (per ASIN × SKU × marketplace): eligibility (ELIGIBLE | INELIGIBLE | SUSPENDED — INELIGIBLE cancels the subscriptions; SUSPENDED: Amazon has suspended the offer from Subscribe & Save, and its existing subscriptions still count in Amazon's figures; what Amazon does with their deliveries is not established, so state the suspension, never a consequence), subscriptions, inventory and stockRisk, price, the funded discounts (seller and Amazon, base and tiered, in %), autoEnrollment, forecastDeliveries at 15/30/60/90 days (units), deliveries30d by condition with atRisk (Amazon's at-risk count never includes a suspended offer), forecastRevenue at 30/60/90 days. changes: the eligibility transitions of the last sinceDays days: kind = loss when the offer leaves ELIGIBLE (a suspension included, which is not a cancellation), recovery when it returns to ELIGIBLE, other between two states that are not ELIGIBLE. Each change also carries marketplaceCode (the code the seller says, US or DE; marketplace keeps the id) and subscriptionsCancelled, true when the offer turns INELIGIBLE, SUSPENDED → INELIGIBLE included (a kind other). The statuses: ELIGIBLE serves the current subscriptions and takes new ones; SUSPENDED: no new subscriptions; INELIGIBLE: no new subscriptions, and Amazon cancels the existing ones. The daily check is section changes with sinceDays 1, keeping the rows where subscriptionsCancelled is true or eligibility is SUSPENDED with previousSubscriptions > 0; the answer's snapshots gives each account's latest offer snapshot (null: no offer snapshot in this scope), and its notice, when present, names the accounts whose snapshot of the day (UTC) has not landed yet: an empty list for them means not read yet, never no change, so relay it. summary (one row per product as of the latest snapshot of each account and marketplace: the cockpit's S&S Health column): per ASIN, or per ASIN × SKU with groupBy='sku'; one row over all the product's marketplaces, or one per marketplace with byMarketplace=true (marketplace then names it). A row adds up the accounts of the call that carry the product: pass accounts to read one. Each row carries subscriptions (its active subscriptions; null when Amazon reported none of its offers' counts), forecastDeliveries30d (the units Amazon plans to deliver to subscribers over the next 30 days), deliveries30d by Amazon's condition: pausedNonBuyable and pausedPricing (PAUSED: those deliveries are stopped, the offer not buyable or for a pricing issue), lowInventoryRisk (AT RISK: still scheduled, threatened by low inventory) and noIssues; suspendedOffers and suspendedSubscriptions (SUSPENDED as in offers: their subscriptions count in subscriptions and in the forecast, and Amazon's at-risk count never includes them), and suspendedOffersWithSubscribers, the suspended offers that carry subscriptions; ineligibleOffers (the INELIGIBLE ones only, their subscriptions cancelled); eligibility, Amazon's status over the product's offers, the one rule of every Subscribe & Save surface: SUSPENDED when a suspended offer carries subscriptions (SUSPENDED as in offers: state the suspension, never a consequence), else ELIGIBLE when one offer is ELIGIBLE or REPLENISHMENT_ONLY_ORDERING, else SUSPENDED when one offer is, else INELIGIBLE when every offer is, else null; a suspended offer without subscribers on an otherwise eligible product leaves it ELIGIBLE (mention it, e.g. '1 suspended offer, no subscribers', never as the product's state); sellerFundedBaseDiscountPct { min, max }, the base discount the seller funds on the product's offers in % (min and max equal on a single offer; null when Amazon reported none); offers, marketplaces and snapshotDate; and health, the worst of Amazon's warnings: paused_non_buyable, then paused_pricing, at_risk_low_inventory, suspended (a suspended offer with subscribers), else no_issues. The products Amazon warns about come first, then the most subscribed, so limit cuts quiet products first. Counts and units only, no amount. For the S&S sales, units, active subscriptions, stockout loss (in sales and in units) and the discount the seller funded OVER A PERIOD and by product, use query_metrics (activeSubscriptions, shippedSubscriptionUnits, totalSubscriptionsRevenue, salesPenetration, lostSubscriptionsRevenue, subscriptionsStockoutRate, missedSubscriptionUnits, subscribeAndSaveDiscount), whose answer says when the S&S figures of a period are partial or incomplete; for the projected units next to days of inventory, query_inventory.

Input Schema

NameRequiredDescriptionDefault
skusNooffers / changes / summary: only these SKUs.
asinsNooffers / changes / summary: only these ASINs.
limitNooffers / changes / summary: row cap (default 200).
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.
groupByNosummary only: one row per ASIN (default) or per ASIN × SKU ('sku').
sectionYeshealth = account-level programme health; offers = the offers as of today; changes = eligibility transitions; summary = one row per product as of today (the cockpit's S&S Health).
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.
currencyNohealth only: the amounts in this currency, one of the organization's configured codes (its primary or a secondary currency, e.g. "USD"), each block converted at the average daily rate over its own window; any other code is refused. Omit for each marketplace's own currency.
sinceDaysNochanges: days back from today (default 30).
marketplacesNoRestrict to these marketplace IDs.
byMarketplaceNosummary only: one row per marketplace of each product (true) instead of one row over all its marketplaces (default).

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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 readOnlyHint, so the description carries most of the burden and does so: currency conversion at the block's own window rate, nulls for windows without a rate, `convertedFrom` semantics, null meaning 'no offer snapshot in scope', the `notice` field meaning 'not read yet, never no change', ordering/limit behaviour, and repeated caution that a suspension must be stated without inferring consequences. These are exactly the non-obvious traits an agent needs.

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 four sections are labelled, but the body is a single dense block of 700+ words with parenthetical asides nested several levels deep, making it hard to scan in a tool-selection context. Much of the content is genuinely useful, but the packaging costs readability and repetition (the SUSPENDED/at-risk caveat is restated three times).

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?

Eleven parameters, no output schema, and the description compensates by documenting the shape of each section's return fields (health blocks, offers columns, changes kinds, summary row fields including eligibility derivation rules). For a read-only, no-output-schema tool of this complexity, nothing essential about correct invocation is left unstated.

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 100%, so the bar is added meaning beyond the schema; the description supplies it for `currency` (must be an organization-configured code, per-block window conversion, refusal of other codes), `sinceDays`, `limit` (products Amazon warns about first, quiet products cut first), and `accounts`. It adds little for `skus`/`asins`/`marketplaces`/`reason` beyond what the schema states, so it stops short of a 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 (Subscribe & Save programme health, offers, per-product state) sourced from Amazon Replenishment daily snapshots, and enumerates the four sections explicitly. It is clearly distinguished from the sibling tools query_metrics and query_inventory, which are named for the cases this tool does not cover.

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?

Explicitly routes the agent: use query_metrics for period-based S&S sales/units/stockout loss/discounts and query_inventory for projected units next to days of inventory. It also gives a concrete recipe for the daily check ('section changes with sinceDays 1, keeping rows where subscriptionsCancelled is true or eligibility is SUSPENDED with previousSubscriptions > 0') and a rule for when to pass `accounts`.

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.