ru-marketplace-mcp

Ozon Product Reviews

ozon_reviews

Read-onlyIdempotent

Fetch Ozon product review texts, star distribution, and per-review details like score, helpfulness, author, and date. Automatically paginates up to your limit, deduplicates, and returns partial results if a later page fails.

Instructions

Fetch Ozon product review texts + star distribution via composer-api.bx.

Tier-1 (curl_cffi) tried first, Tier-2 (Chrome CDP) fallback — same path as ozon_card. Returns review texts (comment/positive/negative), per-review score, helpfulness votes, author first name, date, plus the overall star distribution and total count.

Pages are walked automatically (30/page) until limit texts are collected or pages run out, deduplicating by review uuid. Hard cap of 10 pages.

Reviews are pooled per card family, not per product

Ozon shows one shared pool for every variant of a card, and those variants are frequently different products — different wattage, different brand. So rating_score and distribution describe the POOL, not the SKU asked for. Each review carries item_id, the SKU it is really about; own_reviews counts the returned reviews whose item_id matches requested_item_id, and pool_variants names every SKU in the pool. Filter by item_id before drawing any conclusion about a product, and say so when own_reviews is 0 — a headline 4.8 can be borrowed entirely from neighbours.

Return Format

OzonReviewsResponse: {status, sort, rating_score, reviews_count, distribution, returned, partial, stop_reason, last_error, requested_limit, reviews, requested_item_id, own_reviews, pool_variants, meta} on success. A later-page failure with reviews already collected is a PARTIAL SUCCESS (partial=True, stop_reason set), NOT an error.

Error Format

Raises ToolError on validation (BadRequestError), transport/block (TransportDownError), or parser drift (ParserDriftError) — but ONLY when no reviews have been collected yet. Once at least one page yielded reviews, a later-page failure degrades to a partial-success return.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sort`	No	Review ordering. Aliases: "recent"/"default" -> newest, "best"/"highest" -> highest rated first, "worst"/"lowest"/"complaints" -> LOWEST rated first. Raw API values published_at_desc/score_desc/score_asc also accepted.	recent
`limit`	No	Max review texts to return (1..100). Distribution+total always full.
`sku_or_path`	Yes	SKU integer-as-string, full Ozon URL, or /product/<digits>/ path. Normalized to /product/<digits>/reviews/ (SSRF-allowlisted).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`url`	No
`sort`	No
`_meta`	No
`status`	No
`partial`	No
`reviews`	No
`returned`	No
`tier_used`	No
`last_error`	No
`own_reviews`	No
`stop_reason`	No
`distribution`	No
`rating_score`	No
`pages_fetched`	No
`pool_variants`	No
`reviews_count`	No
`requested_limit`	No
`requested_item_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.1.0Sep 9, 2026
- addedOutput schema / properties / own_reviews
```
Added value: +{}
```
- addedOutput schema / properties / pool_variants
```
Added value: +{}
```
- addedOutput schema / properties / requested_item_id
```
Added value: +{}
```
First observedv1.5.1Aug 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial behavioral context beyond those: pagination behavior (30/page, hard cap of 10 pages), deduplication by review uuid, partial-success semantics (later-page failure with collected reviews is partial=True, not an error), and error-raising conditions (only when no reviews collected yet). It also discloses the surprising pooled-reviews behavior, which is exactly the kind of non-obvious behavioral trait an agent needs. No contradiction with annotations.

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?

The description is longer than average, but every section earns its place: the opening line states the core function, the pagination paragraph explains limits and dedup, the pooled-reviews warning is critical domain knowledge, and the return/error formats are clearly separated with headers. It is well-structured with markdown headers and bolded warnings, making it scannable. It loses one point for length — the return format enumeration and error format could be slightly tightened — but it is not bloated or redundant.

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?

Given the tool's complexity (3 params, output schema present, partial-success semantics, pooled reviews, tiered fetch), the description is remarkably complete. It covers the return shape, error conditions, pagination, deduplication, and the critical interpretation caveat about pooled reviews. The output schema exists, so the description needn't enumerate every field, but it does name the key fields and their meaning. An agent has everything needed to invoke this tool correctly and interpret its results.

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 description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the pagination semantics tied to `limit` ('Pages are walked automatically (30/page) until `limit` texts are collected'), clarifying that distribution and total are always full regardless of limit, and giving the normalization behavior for `sku_or_path` (normalized to /product/<digits>/reviews/, SSRF-allowlisted). The `sort` aliases are already in the schema, but the description's mention of the review pool and `item_id` filtering adds interpretive meaning to the returned data rather than the parameters themselves. A 4 is appropriate because the description enriches parameter understanding without fully documenting every edge case.

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 description opens with a specific verb and resource: 'Fetch Ozon product review texts + star distribution via composer-api.bx.' It clearly distinguishes this from sibling tools like ozon_card (product card) and wb_reviews (Wildberries reviews) by naming the platform and the data returned. The title 'Ozon Product Reviews' is reinforced, not merely restated, with concrete detail about review texts, scores, helpfulness votes, author, date, and star distribution.

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?

The description explicitly explains the tiered fetch strategy (Tier-1 curl_cffi first, Tier-2 Chrome CDP fallback) and notes it follows the same path as ozon_card, giving an agent a clear sense of when this tool is appropriate. It also provides critical usage guidance about the pooled review pool per card family, warning that rating_score and distribution describe the pool not the SKU, and instructing to filter by item_id and to say so when own_reviews is 0. This is explicit when-to-use and how-to-interpret guidance beyond any sibling comparison.

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