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.

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": {
      "section": "<section>"
    },
    "name": "query_subscribe_and_save"
  }
}

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?

Beyond the read-only annotations, the description discloses snapshot semantics, currency conversion rules (per-window average rate, convertedFrom, null when no rate), the missing-snapshot notice behavior (an empty list means not read yet, never no change), and nuanced eligibility/SUSPENDED consequences. These are exactly the behavioral traits an agent cannot infer from annotations or schema.

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 opening overview is front-loaded, but the body is a single dense wall of prose with repeated restatements of the SUSPENDED semantics and the ineligibility rule. Several long parenthetical asides and duplicated caveats (e.g., 'SUSPENDED as in offers: state the suspension, never a consequence' appearing twice) could be removed without losing meaning.

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 an 11-parameter, four-section tool with no output schema, the description is unusually complete: it explains each section's row grain, null behavior, currency handling, eligibility precedence rules, and the meaning of each summary field. An agent has enough to call the tool correctly and interpret the returned rows.

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 schema already documents the parameters; the description still adds real meaning, notably the currency conversion behavior for `currency`, the ordering semantics of `limit` (warned products first, quiet products cut first), how `accounts` is narrowed, and how groupBy/byMarketplace reshape `summary`. The additions are valuable, though much of the parameter-specific guidance is buried in prose rather than tied to the parameter names.

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 precise verb-and-resource statement: it reads Amazon's Subscribe & Save Replenishment figures across four named sections (health, offers, changes, summary), and it distinguishes those sections' scopes explicitly. It also names the sibling tools (query_metrics, query_inventory) that answer related but different questions, so the tool is clearly distinguishable 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: use query_metrics for S&S units/sales/stockout loss over a period and query_inventory for projected units next to days of inventory. It also gives a concrete daily-check recipe (section=changes with sinceDays 1, filtered on subscriptionsCancelled or SUSPENDED with previousSubscriptions > 0) and section-by-section guidance, so when-to-use and when-not-to-use are both covered.

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.