Skip to main content
Glama

rr_get_product_expiry_risk

Read-onlyIdempotent

Estimate expiry risk for one product: see each location's inferred lots, expiry dates, expected sell-through, and units or cost at risk. Use it to target markdowns and avoid write-offs.

Instructions

Expiry risk for one product marked as expiring: at each location holding it, the recorded lots estimated to be still on hand (lot code, expiry date, and the date the lot becomes unusable), whether each is expected to sell before that date, and the units and cost at risk. These are estimates: Amazon does not report which lot it sold, so the lots on hand are inferred from arrival order (oldest first at Amazon FBA, earliest expiry first at the seller's own locations) and projected against the product's sales rate. A lot becomes unusable a set number of days before it expires: Amazon's removal window at FBA, the product's days-to-consume elsewhere. A location with status no_demand has no sales rate to project, so its lots are not scored. At Amazon FBA each position also carries old_stock_bound (the most older stock that can still be there, from Amazon's own count) and next_arrival: when the next shipment should arrive so the stock there is nearly sold through and the product stays in stock (status window with earliest and latest dates), or, when both cannot hold, the latest date that keeps it in stock and the units likely still there then (overlap), or late. The latest date is never later than ReplenishRadar's stock-out forecast allows (past its 30 days it is continued at the current rate, and says so). A dated next_arrival carries ship_by: when the shipment must leave to arrive in time, the arrival dates less the store's transit to Amazon (learned from its own received shipments, or its FBA transit setting); passed with arrives_if_sent_today when that date has gone; status unknown when ReplenishRadar has no transit it can stand behind, never a guessed default. A product not marked as expiring returns requires_expiration false and no positions. Cost fields are null unless the key may read cost data. For the lots at risk across the whole catalog, use rr_list_expiring_lots.

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": "rr_get_product_expiry_risk"
  }
}

Input Schema

NameRequiredDescriptionDefault
skuNoThe product's SKU, used when item_id is not given.
item_idNoThe product's item id. Give this or sku; item_id wins if both are given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.3.1

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description still discloses a great deal beyond them: the data is inferred rather than reported by Amazon, the allocation rule differs by channel (oldest-arrival at FBA vs earliest-expiry at own locations), no_demand locations go unscored, next_arrival can be window/overlap/late/unknown, and cost fields are null without the right key. An agent knows exactly how much to trust each field.

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?

The core purpose is front-loaded in a strong first sentence, but the remainder is one unbroken, deeply nested paragraph mixing lot-allocation logic, next_arrival states, ship_by, transit learning, and cost permissions. Much of it is necessary because there is no output schema, yet the lack of any structure makes it hard to scan and some clauses read as run-ons.

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?

With no output schema and a genuinely complex, nested return shape, the description carries the full burden and does so: it explains the lot fields, the risk scoring, the FBA-only extras (old_stock_bound, next_arrival, ship_by), the 30-day forecast continuation, and the empty-result case. An agent can interpret the response without further documentation.

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

Parameters3/5

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

Schema coverage is 100%, and the schema already explains that sku is used when item_id is absent and that item_id wins on conflict. The description adds no further meaning about these two identifiers, so the baseline 3 applies.

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 opening sentence names a specific resource and scope: expiry risk for ONE product marked as expiring, broken down per location with lot-level detail. It is clearly separable from the sibling rr_list_expiring_lots, which the description itself identifies as the catalog-wide counterpart.

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?

It states the applicability condition (the product must be marked as expiring) and the outcome when it is not (requires_expiration false, no positions), and it routes catalog-wide needs to rr_list_expiring_lots. What is missing is any steer against the other per-product siblings such as rr_get_inventory_position or rr_get_demand_forecast, which an agent could plausibly confuse with this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.