Skip to main content
Glama

rr_list_expiring_lots

Read-onlyIdempotent

Lists lots at risk of expiring unsold or already past their unusable date, ordered by earliest cutoff, showing remaining and at-risk units by product and location to guide markdowns or write-offs.

Instructions

List the lots across the whole catalog that are estimated to be left unsold when they become unusable (status at_risk), or that have already reached that date with units left (past_cutoff), earliest unusable date first, at Amazon FBA and at the seller's own locations. Each row names the product, the location, the lot code, the expiry and unusable dates, the units remaining and the units at risk. These are estimates: Amazon does not report which lot it sold, so the lots on hand are inferred from arrival order and projected against each product's sales rate. An empty list does not mean nothing will expire. summary counts, across the whole catalog whatever status asks for, what the list cannot show: positions_without_demand and units_without_demand (lots at a location with no sales rate to project), units_with_no_lot (stock with no lot on record), units_without_expiry_date (lots recorded with no expiry date), positions_at_disconnected_stores, positions_unreadable, and positions_arrival_overlap (Amazon locations whose next shipment must arrive before the stock there is nearly sold through to stay in stock, or is already late; each row carries its location's next_arrival with its ship_by dates), positions_ship_by_unknown (Amazon locations with an arrival date and no ship-by date, because the store's transit to Amazon is not known); products_with_expiring_stock is how many products marked as expiring have stock on hand at all. Cost fields are null unless the key may read cost data. For every lot of one product, including those on track to sell, use rr_get_product_expiry_risk.

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_list_expiring_lots"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoRows per page (default 100, max 500).
cursorNonext_cursor from the previous page. Pass it with the same other inputs until has_more is false.
statusNoOnly lots with this status. Omit for both.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.3.1

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive and closed-world, so the safety bar is covered. The description goes well beyond them by disclosing the estimation methodology (lots inferred from arrival order and projected against sales rate, since Amazon does not report which lot it sold) and the permission-dependent nulling of cost fields. That is real behavioral context, though the description never states pagination behavior in prose beyond the schema's cursor 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 purpose is front-loaded and no sentence is pure filler, but the middle section is a single dense run-on that enumerates seven summary counters and two arrival-overlap sub-fields in one breath without grouping or formatting. Since there is no output schema, that detail is necessary, yet the wall-of-text structure makes it hard to parse on first read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining return shape, and it does so for both the row fields and the summary object, including the important caveat that summary counts cover the whole catalog regardless of status filter. It also flags the cost-field null condition and the sibling alternative, leaving little an agent needs missing — only pagination behavior is left implicit.

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 baseline is 3; the description earns above baseline by defining what 'at_risk' and 'past_cutoff' actually mean rather than leaving the enum labels to inference. It does not elaborate on limit or cursor, but those are fully documented in the schema.

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 verb ('List the lots'), the exact scope ('across the whole catalog'), the two qualifying statuses with plain-language definitions, the sort order ('earliest unusable date first'), and the locations covered (Amazon FBA and the seller's own). An agent can distinguish this from rr_get_product_expiry_risk without opening either 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?

Explicitly routes the per-product case elsewhere: 'For every lot of one product, including those on track to sell, use rr_get_product_expiry_risk.' It also gives a when-not-to-worry condition ('An empty list does not mean nothing will expire'), which is exactly the kind of usage caveat an agent needs before drawing conclusions.

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