Skip to main content
Glama

rr_list_top_sellers

Read-onlyIdempotent

Rank products by units sold over a lookback window to identify high-demand items and guide inventory and replenishment decisions.

Instructions

Get top-selling products ranked by units sold over the whole window, one row per product however many SKU labels its sales carry. total_skus is how many products have sales rows in the window (the name is historical); truncated_to_top_n is true when that is more than the page returned (this ranking has no next page).

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

Input Schema

NameRequiredDescriptionDefault
daysNoLookback days (default 30, max 90)
limitNoNumber of results (default 20, max 100)
monthsNoRank over this many calendar months instead of days (max 36), on net demand units, for a window longer than 90 days.
store_idNoOnly sales from this store.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.3.1

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description's added burden is low. It does contribute real value by disclosing a non-obvious behavioral trait: the ranking has no next page and is truncated (signalled by truncated_to_top_n), and that total_skus is a historically named count rather than a SKU tally. It stops short of explaining ordering ties or the default window, keeping it at a solid 3.

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

Conciseness4/5

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

Two front-loaded sentences with no filler; the deduplication rule comes before the response-shape caveats. The parenthetical 'however many SKU labels its sales carry' is slightly convoluted, but each clause carries information.

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 shoulders the return-value burden and does it: it names total_skus and truncated_to_top_n and explains what each means, and it warns there is no next page. Missing only minor details such as tie-breaking order and the default window, which is acceptable for a simple read tool.

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 description coverage is 100%, so days, limit, months, and store_id are already documented with defaults and maxima. The description adds no per-parameter syntax or precedence detail, notably nothing about how months interacts with days when both are supplied. Baseline 3 is appropriate when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Get top-selling products ranked by units sold over the whole window,' plus the grain ('one row per product'). That clearly separates it from a raw sales listing, but it never names or contrasts a sibling such as rr_list_slow_movers or rr_list_sales_history, leaving differentiation implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the ranking semantics and the 'whole window' framing, but there is no explicit when-to-use statement, no statement of when to prefer rr_list_sales_history, and no prerequisites or exclusions. An agent must infer the choice from the description's phrasing alone.

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