Amazon Seller MCP Server — AgentXray

How today is going for the connected Amazon seller account, as ONE short paragraph written to be read aloud: units sold so far today in the store's own time zone, the money Amazon has actually POSTED recently (today's fees do not exist yet — they post 7.5-13 days after purchase), ad spend, and at most two things that need attention. Use this for 'how did today go', 'what happened today', 'give me my morning brief'. The result carries a 'narrative' field that is already composed from measured numbers: read it out word for word and do not recompute, re-round or add numbers of your own.

The MEASURED outcome of changes this seller approved and applied through AgentXray: what changed, when, and what happened to conversion in the fortnight afterwards. Verdicts are deliberately conservative — at low volume 'inconclusive' is the honest answer and the reasons say exactly why (thin traffic, day-to-day swing, another change to the same listing inside the window). A change whose window has not closed yet reports status 'measuring' with the date it can first be read. Use for 'did that change work', 'was it worth it'.

Account health for each connected Amazon seller account: Amazon's own Account Health rating and account status, every problem the latest check found (with the SKUs it touches and what to do), and unacknowledged alerts of the last 14 days. Use it for 'is my account healthy', 'am I at risk of suspension', 'any policy problems'. Its narrative is the answer.

Net contribution per ad group, priced with the seller's own economics measured from their settlement (price, Amazon fees, storage, saved unit costs): spend, ad sales, ACoS, CPC, the highest CPC each ad group can afford, and kill candidates. Read its narrative as the answer.

Advertising per product (advertised SKU): each SKU's own spend, ad sales, ACoS, its measured break-even and the net contribution its ads made after Amazon fees, product cost and ads. Read its narrative as the answer.

Campaigns on the connected Amazon Ads account WITH their Amazon campaign ids, state, daily budget, measured spend and sales, and budget utilisation. Call this before proposing a budget or a pause: both need the campaign id, and utilisation is what a budget decision turns on — a campaign running at 40% of its budget is not budget-constrained, so raising it buys nothing.

Per-DAY advertising spend, sales, clicks and ACoS — the series that answers 'when did it change', which a 30-day rollup cannot. Use for pacing, for finding the day a change took effect, and before claiming any trend. A day Amazon did not report is ABSENT, not zero.

Every negative keyword on the account, with its campaign and ad group and a self_block flag. self_block means the seller also bids on that exact term in the same ad group — the campaign blocks a keyword it pays for. A negative is invisible by construction, so this list is the only way to see one.

Amazon Advertising performance for the connected account: whether the Ads connection exists, and per-campaign spend, sales, clicks, orders, ACoS and ROAS over a window. Ad spend is billed separately from Amazon settlements, so it is NOT part of the profit tools — call this as well when a question is about total profitability.

Top-of-Search impression share and placement stats per campaign, from Amazon's own spCampaigns daily reports: share of eligible top-of-search impressions won, plus top-of-search impressions, clicks and spend against total impressions. Use for visibility questions — why impressions are flat, whether a campaign shows at the top of search. Absence from the result means no report rows in the window, not zero share.

What to change in Sponsored Products now, and why: bid cuts and raises against each target's own measured break-even CPC, search terms to negate (clicks with no order), converting search terms to add as EXACT keywords, budget raises and cuts, placement adjustments, and campaigns to pause because every advertised product is out of stock. Each item carries its evidence, the risk screen a draft would get, and a ready draft ({tool, args}) — file it with that draft tool ONLY after the seller agrees, then offer schedule_follow_up on follow_up_on (the 14-day verdict day). Reading this changes nothing. Use it for 'what should I change in my ads', 'optimise my PPC', 'audit my campaigns'.

Customer search terms that triggered ads, with clicks, orders and spend, the campaign and ad group they came through, and whether each is ALREADY negated. Call this before proposing a negative keyword. Zero orders on single-digit clicks is not evidence of a bad term — it is what a normal conversion rate looks like most of the time.

Search terms judged over every term: wasted (twice the account's clicks-per-order and no order), best sellers against the measured break-even, and harvest candidates not yet an exact keyword. Read its narrative as the answer.

Keyword and product targets WITH their Amazon target ids, current bid, ad group and campaign ids, and measured clicks, orders, spend and sales. Call this before proposing a bid change: the clicks and orders are what let the proposal be priced against this seller's own break-even CPC rather than a rule of thumb.

What Amazon itself is asking this seller to do, from Amazon's Action Items API: issues to fix, recommendations to pursue and tasks that need action, each with Amazon's own impact (cost, benefit or enforcement, with a money estimate when Amazon gives one), the due date, and the Seller Central link that resolves it. Use it for 'what does Amazon want me to do', 'any recommendations from Amazon', 'is anything overdue', 'what should I fix first'. Read-only. Its narrative is the answer.

AMAZON's own suggested bid range for the live keywords in one ad group - what the auction currently costs. A DIFFERENT number from the seller's break-even CPC, which is priced against their measured margin. Report both, say which is which, never average them.

A+ content (brand-registered sellers): every A+ document with its status (APPROVED, SUBMITTED, REJECTED, DRAFT…) and the ASINs it covers, and which of the seller's own listed ASINs have NO A+ content. Use it for 'which products have no A+', 'was my A+ approved'.

Brand Analytics, analysed (brand-registered sellers): (1) search terms where this seller's product gets a click share like a competitor's but a lower conversion share — a detail-page problem (price, reviews, images), not a keyword one; (2) search terms the seller's own buyers use that the listing's title, bullets and backend keywords do not carry, each with a ready draft (draft_listing_update carrying the FULL backend keyword set — the field is replaced, never appended). File a draft only after the seller agrees. Use it for 'which keywords am I missing', 'why do competitors convert better', 'improve my listing for search'.

Amazon's own weekly Brand Analytics search-term ranking for one marketplace on the connected seller account: which customer search terms rank where, the ASINs shoppers clicked on each, and how each term moved against the previous week. Rank 1 is the most-searched term, so a smaller rank is better. Requires Brand Registry; an unenrolled seller gets a named refusal rather than an estimate. Requires a marketplace id from list_my_marketplaces.

Best Seller Rank over time for your own products: one point per day, the category, the 7- and 30-day change, and whether the latest day is a sharp drop, a rise or steady (lower rank is better). History starts the day AgentXray first read the product. Use it for 'is my rank going up or down', 'which products lost rank this week'.

Buy Box performance for one marketplace on the connected seller account: win rate over a window, SKUs currently losing the Buy Box with the competing price gap, recent held-to-lost transitions, and per listing how many sellers offer it, who holds the Buy Box and each other seller's price, FBA/Prime and feedback with a storefront link (listing_competition; read its summary out first). A listing Amazon returned no offer data for is unmeasured, never 'only seller'. Requires a marketplace id from list_my_marketplaces.

What kind of change has worked on THIS account: every change applied through AgentXray, grouped by type (bid, negative, budget, placement, listing, price…) and by who drafted it, with how many moved net contribution up, down, were inconclusive, had no data, or are still measuring, and the summed net contribution of the judged ones. Use it before recommending a kind of change, and for 'what has worked', 'is the AI helping'.

Competitor ASINs AgentXray watches for this seller (added by hand, from a product targeting campaign, or discovered in Brand Analytics), each with its latest Buy Box price, offer count, availability, rating and review count where read, and weakness events of the last 30 days (out of stock, lost Buy Box, price jump). Use it for 'what are my competitors doing', 'is a competitor out of stock'.

The seller's follow-ups: what is due now first, then what is still waiting. Call it at the start of a conversation. status: active (default: open + due), due, open, done, cancelled or all. Its narrative is the answer.

FBA inbound shipments: which are on their way, units sent vs units Amazon has received, status and destination warehouse, and closed shipments where Amazon received fewer units than were sent. Use it for 'where is my shipment', 'has Amazon received my stock', 'is anything missing from a shipment'. Its narrative is the answer.

FBA inventory age for one marketplace on the connected seller account: how stock is distributed across age buckets and which SKUs are approaching long-term storage fees. Use this for 'is my stock getting old', 'will I be charged storage fees'. Requires a marketplace id from list_my_marketplaces.

UNITS ONLY — says nothing about money, balances or payouts (use get_payout_balance for money). Units Amazon's own Inventory Ledger has not reconciled for one marketplace on the connected seller account, with Amazon's reference id for each row, plus the ledger's event totals in units (receipts, shipments, adjustments). Use this for 'am I missing units', 'is Amazon holding stock it never accounted for'. This reads Amazon's own Unreconciled Quantity column — it does not derive a shortfall from a formula. Requires a marketplace id from list_my_marketplaces.

One listing's problems with the exact fix for each, read LIVE from Amazon: which door fixes it (draft the text, draft an attribute, a new image, a Seller Central case with the case text ready, or a category approval), how bad it is (not sellable / hidden from search / attribute hidden), and for every attribute an issue names, what Amazon's product-type schema requires (sub-fields, allowed values, limits), the current value and a value skeleton in the exact patch shape. Use it after get_listing_issues, before drafting any listing fix. Its narrative is the answer.

One listing's image slots read LIVE from Amazon (main + 8), with the pictures themselves so you can see them: what buyers are shown per slot, size and zoom, empty slots, images Amazon has flagged, and slots where another contributor's image wins over the seller's. Returns the six roles a complete image stack fills (main image that wins the click, what's in the box, the difference, a five-second infographic, lifestyle in use, the objection handler). Look at the images, say which role each fills and which roles are missing; draft a replacement with draft_image_swap once the seller has the new image. Its narrative is the measured part.

Listings with problems Amazon reported (errors that block a listing from selling, and warnings), with Amazon's own message per SKU, and listing deadlines that are still open. A listing that is simply not buyable (often no stock) is counted separately, not reported as a problem. Use it for 'are any of my listings suppressed', 'listing errors', 'why can't my product be bought'. Its narrative is the answer.

Brands registered to this seller in Amazon Brand Registry, with the brand entity id, as Amazon's Advertising API reports them. Call this before proposing anything brand-gated — Sponsored Brands, A+ Content, Brand Analytics and Vine all require an enrolled brand. An empty list distinguishes 'no brand enrolled' from 'not synced yet'.

Changes applied through AgentXray and where each stands in its proof: the 14-day net-contribution verdict, or status 'measuring' when the window has not matured; amazon_state says where Amazon stands on each (sent / amazon_processing / verified / problem) — Amazon accepting a change is not the change being live; plus waiting_for_approval, the drafts not yet approved, and journal: every draft, rejection (with the seller's reason) and Amazon outcome in order, with open_measurements — read it before drafting more, never re-propose what was rejected. Use before claiming a past change worked.

The product costs (COGS) saved in this AgentXray workspace: SKU, marketplace, unit cost, currency and validity dates. Call this when a profit answer depends on whether costs are actually recorded — a SKU with no saved cost is counted at zero cost, which makes profit look better than it is.

Orders for one marketplace over the last N days (default 7, max 30), by the store's own calendar day. days=1 is TODAY so far only; for yesterday or any single date pass day='yesterday' / day='YYYY-MM-DD'. Never call a day with no orders in the result a zero day unless it is inside first_day..last_day. Returns orders, units, cancelled, still unshipped, order value by currency, the best-selling SKUs and the most recent orders with their status. Never includes the buyer's name or address — AgentXray does not hold them. Pending orders have no final value yet and are counted, not priced. For profit use get_profit_summary.

The seller's Amazon payout balance and why it moved, from Amazon's own settlement lines: what the current settlement started from (negative = still owed to Amazon), what is released and held now, and the last settlements broken into buckets with the posting date of every advertising invoice, debt adjustment and carried balance. Use it for 'why is my balance negative', 'what triggered −X', 'what did Amazon deduct', 'when do I get paid'. Money only — units live in get_inventory_reconciliation.

The Buy Box price, from Amazon's Pricing API: for each SKU, the listing price at or below which the seller's offer can expect to win the Buy Box (featured offer), the competing offer that holds it now, and the reference prices Amazon keeps for the product (was-price, competitive price threshold), which a deal or price discount needs. Each price to win is set against the seller's own measured economics: contribution per unit and break-even ACoS at that price. Use it for 'what price wins the Buy Box back', 'why was my deal rejected for no reference price', 'can I afford to match'. Without a sku it checks the SKUs where another seller is on the listing. Read-only: it never changes a price (draft_price_change does, with approval). Its narrative is the answer.

Product (ASIN) and category targets: clicks, orders, spend and sales per target, its measured break-even CPC against its bid, and — when that ASIN is a watched competitor — its latest Buy Box price, offer count and weakness signal. Use it for 'which competitor ASINs should I target', 'are my product targets profitable', 'is the competitor I target out of stock'.

Per-SKU profit ranking for the connected seller account over a window: units, revenue, fees, COGS, net profit and margin per SKU. Use this for 'which product makes money', 'which SKU is losing money', 'what should I stop selling'.

Real profit and loss for the connected Amazon seller account over a window: revenue, Amazon fees, COGS, net profit and margin, grouped per currency. Numbers come from posted Amazon fee events joined to the seller's own orders and saved product costs, so fees include the consumption tax Amazon actually charged (such as AU GST). Use this for 'what did I actually make', 'was last month profitable', 'what are my fees'.

Did a promotion (coupon, deal, price discount, multi-buy) make money? Compares the promotion's days with the same number of days before and after it, for the products it covers: units per day, average price, conversion, contribution per unit at that price (the seller's settled economics), ad spend, and PROFIT PER DAY. Judges by profit per day, not ACoS, and says when the period has not settled yet. Without promotion_id it uses the most recent promotion that has ended (else the running one). Use it for 'did my deal work', 'was the Black Friday discount worth it'. Its narrative is the answer.

The seller's Amazon promotions — coupons, deals, price discounts and multi-buy promotions — read from Amazon's Promotions API: what is running now and when it ends, what is scheduled and when it starts (with the Amazon event, e.g. Black Friday), what ended in the last 30 days, the discount, the budget set, which SKUs it covers, and any problem Amazon reports. Use it for 'what promotions do I have', 'when does my coupon end', 'is my Black Friday deal approved', 'why was my promotion rejected'. AgentXray CANNOT create, edit or end a promotion (Amazon's Promotions API is read-only): when the seller wants one, say so and give them how_to_create (where in Seller Central). Its narrative is the answer.

What to reorder, how much, by when and from whom, per SKU: stock (Amazon's, or the seller's own shelf for merchant-fulfilled listings), the 30-day sales rate, days until it runs out, the lead time used and where it came from, the supplier and their minimum order. Use it for 'what should I reorder' and 'when do I run out'.

Customer returns for one marketplace over a window: units returned against units sold in the same window (a same-window rate), the most returned products, the reasons Amazon recorded and customers' own comments. Use it for 'how many returns', 'why are customers returning', 'which product has the most returns'. Its narrative is the answer.

Amazon 'Request a Review' solicitations on the connected account: how many were sent (last 30 days and in total), orders that can still be asked, why requests did not go out, and whether AgentXray sends them automatically. The last send date and the purchase dates of askable orders are included. Use it for 'did my buyers get review requests', 'how many review requests did I send', 'can I ask for more reviews'. To send, draft_review_requests. Its narrative is the answer.

Brand Analytics Search Query Performance, per ASIN per week (brand-registered sellers): the search queries that led to the product, with impressions, clicks, add-to-carts and purchases — the product's share against all of Amazon on each query. Rows are passed through in Amazon's own field names, unchanged. An EMPTY week means Amazon returned no rows (a Generic ASIN, or no searches yet), not zero traffic. Use it for 'which searches find my product', 'where do I lose buyers between click and purchase'.

Search frequency rank of Brand Analytics search terms week by week (1 = most searched), with this seller's own click share and conversion share on the term in each week they appear in its top three. Pass search_term for one term (substring match), or omit it for the terms where the seller appears. Use it for 'is demand for this keyword growing', 'am I gaining share on this term'.

One SKU over time on one marketplace: units per day, the price buyers actually paid after promotions against the listed price, sessions, conversion and Buy Box %, and settled net profit per week. Use it for 'how is this product doing over time', 'did my price change hurt conversion', 'what do buyers really pay'.

Sponsored Brands campaigns (brand-registered sellers): spend, sales, ACoS, orders, and new-to-brand orders and sales per campaign over a window, from Amazon's own Sponsored Brands report. Says whether SB was collected at all for this store — no campaign and never collected are different answers. Use it for 'how are my Sponsored Brands ads doing', 'how many new customers do my brand ads bring'.

Sponsored Display campaigns: spend, sales, ACoS, orders, detail page views and new-to-brand orders per campaign over a window, from Amazon's own Sponsored Display report. Display sales include view-through purchases under Amazon's attribution, so they are not comparable one-to-one with Sponsored Products. Use it for 'how are my display ads doing', 'is retargeting worth it'.

How long one SKU has been in stock on one marketplace and what running out cost: days in stock, out of stock, not launched yet and unknown (no snapshot), each stock-out period, the first receipt, units per day on in-stock days only, and an ESTIMATE of sales lost while out of stock. Use it for 'how long has this been selling', 'how many days was it out of stock', 'what did running out cost'.

TACoS — ad spend divided by ALL sales ordered in the same store days — in total and per SKU, beside ACoS (ad spend ÷ ad-attributed sales) and the share of each SKU's sales the ads claim. Use it for 'what is my TACoS', 'how dependent am I on ads', 'are my organic sales growing'. Organic sales are DERIVED (ordered sales − ad-attributed sales) and labelled so.

Sessions, page views and conversion rate per ASIN from Amazon's Sales & Traffic report, for the connected seller account. This is the metric that separates the two halves of the funnel: clicks with no orders can be a targeting problem OR a detail-page problem, and unit-session percentage is the only field that tells them apart. Conversion is computed from the window's summed units and sessions. Check it before recommending any listing change.

List the Amazon seller accounts connected to this workspace, with the marketplaces each one covers. An agency has one per client; a single seller has one. Every marketplace-scoped tool takes an 'account' argument naming which of them to answer about, and refuses rather than guessing when several could apply.

List the Amazon marketplaces on the seller account connected to this AgentXray workspace. Call this FIRST whenever a question needs a marketplace id (Buy Box, inventory age) so you never guess one.

The seller's saved goals, rules, decisions and notes for this workspace — call it at the start of a conversation and before advising, and follow the goals and rules in every answer. Optional kind filters to one kind; optional sku returns that SKU's memories plus the general ones. Its narrative is the answer.

What AgentXray can do for THIS seller: every area it reads (profit, stock, Buy Box, shipments, listings, promotions, ads, brand), which are ready on this account and which need a connection first (with the link), good first questions, what it watches without being asked, the changes it can prepare for approval, and what only Seller Central can do. Call it when the seller asks 'what can you do', 'how do I start', 'what can I ask'. Its narrative is the answer.

The honest limits of this account's data, measured live for the connected seller: which SKUs have unrecorded costs (profit overstated), how many recent orders Amazon has not fully posted yet, whether ad spend is invisible, and the structural limits that apply to everyone. Call this BEFORE drawing conclusions from the other tools, and whenever the seller asks how much to trust the numbers.