ru-marketplace-mcp

Yandex Market Search

yandex_search

Read-onlyIdempotent

Search Yandex Market products to retrieve current prices, ratings, and seller details, helping you compare offers and check what an item costs in Russia.

Instructions

Search Yandex Market and return products with both prices, ratings and sellers.

Yandex Market aggregates many sellers per product, which makes it the best single source for "what does this cost right now" across the Russian market — including goods Wildberries and Ozon do not carry.

Each result reports price_rub (what anyone pays — the price the SERP snippet's cart button charges, cross-verified against product cards) and price_with_plus (requires a Yandex Plus subscription, typically 25-30% lower). Prefer price_rub when quoting a price to a person; price_old_rub is the struck-through reference price and must never be quoted as the price.

A search row describes the SERP snippet's offer, which may be a different member of the product family than the offer yandex_card for the same product_id defaults to (live example: search shows REDMOND KM243 sku 4668084807 while the card for that id defaults to a KM245 offer at another price). The row is SERP-faithful — reconcile it with a card by sku_id, not by the product URL.

Note rating_count counts star ratings, not written reviews; the written count is available per product via yandex_card.

price_rub is None when absent — never 0; zero results is NOT an error: the page's own "nothing found" banner makes the empty answer healthy, and meta.warnings says so.

Full field list and error codes: guide://yandex/yandex_search.

Input Schema

Name	Required	Description
`page`	No	Page number, 1-based.
`limit`	No	Maximum products to return from the page.
`query`	Yes	Free-text search query in Russian, e.g. 'iphone 15' or 'стиральная машина узкая'.

Output Schema

Name	Required	Description	Default
`meta`	No
`page`	No
`items`	No
`query`	No
`returned`	No
`page_count`	No
`has_next_page`	No
`total_available`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.5.1Aug 17, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already cover read-only, idempotent, open-world and non-destructive behavior, and the description adds materially more: `price_rub` vs subscription-gated `price_with_plus` (25-30% lower), the prohibition on quoting `price_old_rub`, `price_rub` being None rather than 0 when absent, and that empty results are signalled via `meta.warnings` rather than an error. That is exactly the semantic/safety context annotations cannot express.

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?

Front-loads the core purpose and then groups the price semantics, SERP-vs-card caveat and empty-result behavior into distinct paragraphs, all of which are actionable. The concrete SKU example (KM243 4668084807 vs KM245) is illustrative but is the wordiest portion and could be trimmed without losing meaning.

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 an output schema present, the description correctly avoids enumerating return fields and instead explains the semantics an agent would otherwise get wrong (`rating_count` is star ratings, not reviews; price fields' reliability ranking). It closes with a pointer to `guide://yandex/yandex_search` for the full field list and error codes, so nothing essential is missing.

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 `query`, `page` and `limit` are already documented with bounds, defaults and a Russian-language example. The description adds no syntax, language or paging guidance beyond the schema; the one hint it supplies (Russian market scope) is already implied by the resource name.

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 and resource ("Search Yandex Market and return products with prices, ratings and sellers") and positions the tool against siblings: it is the single-source price check across the Russian market for goods Wildberries and Ozon do not carry. It further distinguishes this search tool from `yandex_card` by explaining that the SERP row and the card can describe different family members.

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?

Gives clear usage context — use it for current Russian-market pricing, prefer `price_rub` when quoting, reconcile rows with `yandex_card` by `sku_id` rather than product URL, and treat zero results as a healthy answer. It stops short of an explicit exclusion statement naming when to pick `wb_search`/`ozon_search` instead, leaving cross-marketplace routing to inference.

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