ru-marketplace-mcp

Cian Real-Estate Search

cian_search

Read-onlyIdempotent

Search Cian property listings by deal type (sale, long-term rent, daily rent), price, area, rooms, and region filters. Compare prices only within matching units to ensure accurate rental or sale results.

Instructions

Search Cian offers by filters (there is no free-text search).

Long-term rent (deal='rent') and daily rent (deal='daily') are two separate markets: one page never mixes them, and their prices are not comparable — a daily offer is priced per night. price_unit on every item says which it is.

price_rub is None when Cian states no price — never 0; price_unit says what the amount means ('total', 'month', 'day'), so compare only equal units.

Full field list and error codes: guide://cian/cian_search.

Input Schema

Name	Required	Description	Default
`deal`	Yes	'sale' (купить), 'rent' (снять на длительный срок) or 'daily' (снять посуточно). 'rent' and 'daily' are separate markets on Cian and never mix in one result page; a 'daily' price is per night, a 'rent' price per month — read price_unit on each item.
`page`	No	Result page (1-based), 28 offers per page.
`rooms`	No	Flats only: room counts to include, any of 1..6; 7 = свободная планировка, 9 = студия. Omit for any number of rooms. Ignored for room/house/commercial.
`region`	No	Cian region id, digits only: 1 = Москва, 2 = Санкт-Петербург, 4593 = Московская область, 4588 = Ленинградская область. Other regions need their Cian id. Default CIAN_REGION (1).
`area_max`	No	Maximum total area in m².
`area_min`	No	Minimum total area in m².
`price_max`	No	Maximum price in rubles: total for sale, per month for rent, per night for daily.
`price_min`	No	Minimum price in rubles: total for sale, per month for rent, per night for daily.
`offer_type`	No	Property type: 'flat' (квартира), 'room' (комната), 'house' (дом/участок), 'commercial'. 'commercial' has no daily market on Cian and is rejected with deal='daily'.	flat

Output Schema

Name	Required	Description	Default
`deal`	No
`page`	No
`_meta`	No
`count`	No
`items`	No
`region`	No
`status`	No
`tier_used`	No
`offer_type`	No
`total_count`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.8.0Nov 3, 2026

changedInput schema / properties / rooms / anyOf

Previous value: -[
-  {
-    "items": {
-      "type": "integer"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "enum": [
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        9
+      ],
+      "type": "integer"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

Addedv2.2.0Sep 12, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered; the description instead adds data-shape behavior an agent could not infer — pages never mix deal markets, price_rub is None rather than 0 when absent, and price_unit governs comparability. It also points to guide://cian/cian_search for the full field list and error codes, which is genuinely useful context.

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-loaded with the core purpose and the no-free-text constraint, followed by two short paragraphs on the two most common mistakes. Slight redundancy: the price_unit caveat appears in both the prose and the `deal`/`price_max` schema descriptions, so a little text is duplicated rather than earned.

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

Completeness3/5

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

With 100% schema coverage and an output schema, the description need not re-document fields or return values, and it correctly delegates full details to the guide resource. However, for a nine-parameter open-world search tool it says nothing about pagination limits in prose or about what the result set contains, leaving those entirely to structured fields.

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 coverage is 100%, so the schema already documents all nine parameters, and the description's notes on deal/price_unit largely restate the enum description on `deal`. Baseline 3 is appropriate — the description reinforces the most error-prone parameter but adds little that is not already in the schema.

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?

"Search Cian offers by filters" names a specific verb and resource, and "there is no free-text search" immediately separates it from the query-driven *_search siblings. It stops short of naming cian_card as the tool for a single known offer, so the sibling routing is only partly done.

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?

The description gives a clear constraint (filters only, no free-text) and explains that rent and daily are separate markets whose prices cannot be compared in one pass. That is interpretive guidance rather than when-to-use guidance: it never says when to pick cian_search over cian_card, nor any prerequisite about region defaults.

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