Retrieve buyer reviews for any Etsy listing by ID. Get structured review data with sort and offset options for pagination.
Get Etsy listing reviews. Returns buyer reviews for an Etsy listing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Numeric Etsy listing id | |
| sort | No | Review sort order | |
| offset | No | 0-based review offset |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the tool is a read operation that returns buyer reviews, which is transparent for a simple GET, but it omits details like pagination behavior, default sort order, or any API constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with two sentences that clearly state the function. The second sentence is slightly redundant with the first but adds the 'buyer reviews' detail, so minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of both annotations and an output schema, the description provides only high-level return information ('buyer reviews'). It does not describe the review content, sorting defaults, or how offset works, leaving gaps for a tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema; it does not explain how 'sort' or 'offset' affect results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('Etsy listing reviews'), clearly stating the tool retrieves buyer reviews for a single Etsy listing. This distinguishes it from sibling tools like etsy_shop_reviews, which target shop-level reviews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or how it differs from etsy_shop_reviews or other review tools, leaving the agent to infer usage from the name and parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.