Skip to main content
Glama

Nova Amazon MCP Server

query_listing_health

Read-only

Current listing-health STATE per SKU — the same source as the app's Listing Health page, so statuses, suppression flags, and severity match the dashboard. Point-in-time entity state (NOT a metrics/date-range query — no from/to). Each row has: status, is_buyable, the per-issue flags (is_removed, is_suppressed, is_search_suppressed, is_attribute_suppressed, image_not_applied, is_compliance_risk, is_quality_issue, is_incomplete — a listing Amazon reports buyable is never is_suppressed: Amazon lists LISTING_SUPPRESSED on buyable, selling listings, so that notice counts as is_quality_issue instead; an action Amazon marks exempt never lights a flag), a severity_label + health_summary + the driving issue (top_issue_code/message/enforcement), the worst-wins alert_band (0 cash-loss · 1 degraded · 2 watch · 3 none), trailing-90d sales/units, the buy-box competition block (buy-box owner/price, hijack entrant, price undercut, contested), and a content block with the PUBLISHED catalog content (brand, manufacturer, productType, browse node id+name, variationTheme, titleHighlights (Amazon's item highlights, the second half of the new title format; null when the listing has none, and always null on Vendor Central), bulletPoints, productDescription, mainImageUrl full-size — NOT the small imageUrl render — imageCount, contentLanguage) plus the seller's SUBMITTED backendKeywords. Content gotchas: catalog fields are NULL until the catalog capture covers the ASIN (gate: contentFetchedAt=null); keywordsScanned=false means the Listings scope has not reached this SKU yet — backendKeywords NULL then means 'not looked at', never 'none written'. Answers: which listings are removed / suppressed / not buyable right now, what to fix first, who is losing the buy box, and content audits (missing bullets/description/backend keywords, image count, wrong content language). Filter by problems (per-issue checks), bands, or statuses; sort='severity' surfaces the worst listings first. CHANNELS: omit channels to read the Seller Central (3P) listings whenever the accounts of the call include a Seller Central account, else the Vendor Central (1P) ones (a vendor-only scope, or a Vendor Central account named alone in accounts); pass channels=['VENDOR'] for the Vendor Central (1P) listings, or ['SELLER','VENDOR'] for both in one list (next to a Seller Central account, a Vendor Central account is read only when VENDOR is asked for; a channel none of the accounts of the call sells on returns an empty list, not an error). Each row carries channel ('SELLER' = Seller Central, 'VENDOR' = Vendor Central). A Vendor Central row is one listing: its vendorProductIdentifier (the identifier Amazon shows in Vendor Central) in one marketplace under one vendorCode; the same ASIN under two vendor codes is two rows. The 90-day sales of a Vendor Central ASIN are Amazon's for the ASIN on its marketplace, not per listing: they are served once, on the ASIN's first row (sales90d, salesEur90d, units90d); its other rows read 0 and name in salesSharedWith the vendor codes of the row that carries them ([] on that row, on a Seller Central row and on an ASIN without sales), so a sum over the rows counts each ASIN once. statusLabel is the word the page shows for the status: 'Removed by Amazon' when Amazon removed the product from its catalogue (the Removed check), whatever the listings report says, 'Not in report' when the listings report no longer carries the SKU (outOfReportSince), else status; the statuses filter reads status. Its sku is the product SKU of the ASIN, as in the app's Copilot and Cockpit (the vendor's product code, or the ASIN when there is none), shared by the listings of that ASIN; skus filters on it. Vendor Central does not report five of the checks: not buyable, buy box lost, hijacker, price undercut and Incomplete never flag a Vendor Central row (Amazon is the seller: no offers block, offers is null, isFbm is null, status is Active or Inactive only). DATES AND CAUSES: statusSince is the day the listing's status last changed in Amazon's listings report (null when no change of status has been observed since the status history began on 2026-11-07); outOfReportSince is the day after the last listings report that carried the SKU, from which the listing is served Inactive (null while the report carries it). notBuyableCause says why a listing is not buyable, the first cause that applies: buyable_twin (another SKU of yours on the same ASIN and marketplace is buyable, so the product page still sells through it), out_of_report (the listing has dropped out of Amazon's listings report), no_stock (nothing to sell: no sellable FBA unit, or an FBM quantity of 0), amazon (Amazon blocks the listing: the top issue carries an enforcement action), inactive (the listing is Inactive in the report, most often closed by the seller), no_offer (the product page has no offer at all), offer_not_ours (the product page has offers, none of them yours), unknown (none of the above); null when the listing is buyable or has no signal. All three are null on Vendor Central rows: Amazon does not report them (isBuyable and flags.notBuyable are null there too, and the summary never claims buyable). CURRENCY: currency is the organization's reporting currency (the one its P&L is read in), never the marketplace's, on every row that has sales (a row without 90-day sales carries its marketplace currency); sales90d is the trailing 90 days converted day by day at each day's rate, where the Listing Health page shown in another display currency converts the whole 90 days at one average rate, so the two can differ by a few percent; offer prices carry their own offers.currency, the marketplace's. EMPTY ANSWERS carry a note: the accounts of the call that sell through another channel than the one read, or the ASINs / SKUs no listing matches; relay it rather than concluding that nothing is wrong.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "query_listing_health"
  }
}

Input Schema

NameRequiredDescriptionDefault
skusNo
sortNo'sales' (default) = biggest sellers first; 'severity' = worst alert band first.
tagsNo"Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations). A tag NAME is rejected — resolve it with list_tags first.
asinsNo
bandsNoAlert bands to keep: 0 cash-loss · 1 degraded · 2 watch · 3 none.
limitNoMax rows (1–1000, default 50).
offsetNoRow offset for pagination (default 0).
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.
channelsNoSelling channels to read: 'SELLER' = Seller Central (3P) listings, 'VENDOR' = Vendor Central (1P) listings, both = one list. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR.
problemsNoKeep only listings failing ANY of these per-issue checks (OR union).
statusesNoMerchant-listing statuses to include. Omit = all statuses (the app defaults to ['Active']).
parentAsinsNoFamily keys — coalesce(parent_asin, asin), the cockpit parent-ASIN grain.
marketplacesNoRestrict to these marketplace IDs.

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?

Goes far beyond the readOnly/non-destructive annotations: it discloses null semantics (contentFetchedAt gating, keywordsScanned=false meaning 'not looked at'), currency conversion differences versus the dashboard, shared vendor sales rows, channel defaulting rules, and empty-answer notes to relay. These are exactly the behavioral traps an agent would otherwise hit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core state semantics correctly, but the body is a very long, densely packed run of caveats with repeated vendor/seller phrasing and nested parentheticals. Most facts earn their place individually, yet the wall-of-text form makes it hard to scan and could be split into shorter, prioritized statements.

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 14-parameter, no-output-schema query tool spanning two channels, it covers statuses, causes, currency, null gotchas, sorting, and empty responses. Nothing an agent needs to call it correctly or interpret results is conspicuously missing.

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

Parameters5/5

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

Schema coverage is already 86%, yet the description still adds real meaning: the channel default logic and Vendor Central scoping, that `statuses` reads `status` rather than `statusLabel`, that `skus` filters the ASIN-level product SKU, and the mental model behind `problems`/`bands`/`severity` ordering. This is genuine value beyond the schema text.

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?

States a specific noun and scope ('Current listing-health STATE per SKU — the same source as the app's Listing Health page') and explicitly distinguishes it from a metrics/date-range query. An agent can immediately tell this is a point-in-time state read, not an aggregate time-series tool.

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 concrete usage contexts ('which listings are removed / suppressed / not buyable right now, what to fix first, who is losing the buy box') and explicit exclusions ('NOT a metrics/date-range query — no from/to'). It does not name sibling tools such as query_metrics or get_listing_content as alternatives, so the routing guidance is contextual rather than fully explicit.

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.