Cenogram - Polish Real Estate Data

get_price_spread

Read-only

EXPERIMENTAL (beta): may change or be withdrawn; no critical workflows on it. Asking-vs-transaction price spread for a Polish city or county: how far the median asking price per m² of apartments for sale sits above (or below) the median apartment transaction price per m² (RCN). spread_pct = (asking − transaction) / transaction × 100; it can be NEGATIVE in premium-secondary cities (a valid answer). Different sources, so an approximation; not comparable across cities with different as_of dates. Both sides need at least 5 samples or the result is suppressed. marketType 'all' (default) = whole market; 'secondary' or 'primary' narrows both sides to that segment. Coverage: counties (miasta na prawach powiatu) plus Warszawa's 18 districts, only cities with asking-sale data. A gmina name resolves to its county (shown in the answer); a name shared by gminas in several counties returns candidates. Aggregates exclude fractional shares and non-market deeds.

Input Schema

Name	Required	Description
`teryt`	No	TERYT: 4 digits = county (1465 = Warszawa); 6 digits = a Warszawa district (146510 = Śródmieście); other longer codes truncate to the county. Wins over location.
`location`	No	County-level city name (a miasto na prawach powiatu or a catalog entry, e.g. 'Warszawa', 'Gdańsk'); a Warszawa district ('Mokotów') narrows to it, 'Kraków-Podgórze' resolves to its parent county; an osiedle 404s - use teryt. This OR teryt.
`areaBucket`	No	Apartment area range in m², restricting both sides (all = whole stock, default). Buckets are not additive.
`marketType`	No	Transaction-side segment: 'all' (default, matched to mixed sale offers), 'secondary' or 'primary'.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 31, 2026

changedInput schema / properties / areaBucket / description

Previous value: -"Apartment area range in m² (all = whole stock, default). Buckets are not additive."New value: +"Apartment area range in m², restricting both sides (all = whole stock, default). Buckets are not additive."

changedInput schema / properties / location / description

Previous value: -"County-level city name (a miasto na prawach powiatu or a catalog entry, e.g. 'Warszawa', 'Gdańsk'); a Warszawa district ('Mokotów') narrows to it, 'Kraków-Podgórze' resolves to its parent county. A gmina name resolves to its county (candidates if shared by gminas in several counties); an osiedle 404s - use teryt. This OR teryt."New value: +"County-level city name (a miasto na prawach powiatu or a catalog entry, e.g. 'Warszawa', 'Gdańsk'); a Warszawa district ('Mokotów') narrows to it, 'Kraków-Podgórze' resolves to its parent county; an osiedle 404s - use teryt. This OR teryt."

Changed1 schema field changedOct 24, 2026

changedInput schema / properties / location / description

Previous value: -"County-level city name (a miasto na prawach powiatu or a catalog entry, e.g. 'Warszawa', 'Gdańsk'); a Warszawa district ('Mokotów') narrows to it, 'Kraków-Podgórze' resolves to its parent county. A town in a larger powiat or an osiedle 404s - check the catalog or use teryt. This OR teryt."New value: +"County-level city name (a miasto na prawach powiatu or a catalog entry, e.g. 'Warszawa', 'Gdańsk'); a Warszawa district ('Mokotów') narrows to it, 'Kraków-Podgórze' resolves to its parent county. A gmina name resolves to its county (candidates if shared by gminas in several counties); an osiedle 404s - use teryt. This OR teryt."

Changed4 schema fields changedOct 23, 2026

changedInput schema / properties / areaBucket / description

Previous value: -"Apartment area range in m2: all (default, whole stock), 0-30, 30-40, 40-50, 50-60, 60-80, 80+. Bucket values are not additive."New value: +"Apartment area range in m² (all = whole stock, default). Buckets are not additive."

changedInput schema / properties / location / description

Previous value: -"County-level city name — a miasto na prawach powiatu or a catalog entry from list_price_spread_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A Warszawa district name (e.g. 'Mokotów') narrows to that district; another city's delegatura (e.g. 'Kraków-Podgórze') resolves to its parent county. A town within a larger powiat or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."New value: +"County-level city name (a miasto na prawach powiatu or a catalog entry, e.g. 'Warszawa', 'Gdańsk'); a Warszawa district ('Mokotów') narrows to it, 'Kraków-Podgórze' resolves to its parent county. A town in a larger powiat or an osiedle 404s - check the catalog or use teryt. This OR teryt."

changedInput schema / properties / marketType / description

Previous value: -"Transaction denominator segment: 'all' (default, composition-matched to mixed sale offers), 'secondary', or 'primary'."New value: +"Transaction-side segment: 'all' (default, matched to mixed sale offers), 'secondary' or 'primary'."

changedInput schema / properties / teryt / description

Previous value: -"TERYT code. 4 digits = county (e.g. 1465 = Warszawa). 6 digits = dzielnica where available (today: Warszawa's 18 districts, e.g. 146510 = Śródmieście) → spread for that district. Other longer codes (gmina/precinct) are truncated to the county. Wins over location when both are provided."New value: +"TERYT: 4 digits = county (1465 = Warszawa); 6 digits = a Warszawa district (146510 = Śródmieście); other longer codes truncate to the county. Wins over location."

Changed1 schema field changedSep 20, 2026

changedInput schema / properties / location / description

Previous value: -"County-level city name — must be a miasto na prawach powiatu or a catalog entry from list_price_spread_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A town within a larger powiat, a non-Warszawa district, or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."New value: +"County-level city name — a miasto na prawach powiatu or a catalog entry from list_price_spread_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A Warszawa district name (e.g. 'Mokotów') narrows to that district; another city's delegatura (e.g. 'Kraków-Podgórze') resolves to its parent county. A town within a larger powiat or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."

Changed1 schema field changedJul 11, 2026

changedInput schema / properties / location / description

Previous value: -"City name, resolves to a county (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). Use this OR teryt."New value: +"County-level city name — must be a miasto na prawach powiatu or a catalog entry from list_price_spread_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A town within a larger powiat, a non-Warszawa district, or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."

Changed1 schema field changedJul 8, 2026

changedInput schema / properties / teryt / description

Previous value: -"TERYT county code (4 digits, e.g. 1465 = Warszawa). Longer codes (gmina/precinct) are truncated to the county. Wins over location when both are provided."New value: +"TERYT code. 4 digits = county (e.g. 1465 = Warszawa). 6 digits = dzielnica where available (today: Warszawa's 18 districts, e.g. 146510 = Śródmieście) → spread for that district. Other longer codes (gmina/precinct) are truncated to the county. Wins over location when both are provided."

AddedJul 7, 2026
RemovedJun 17, 2026

Changed1 schema field changedJun 11, 2026

addedInput schema / properties / areaBucket

Added value: +{
+  "description": "Apartment area range in m2: all (default, whole stock), 0-30, 30-40, 40-50, 50-60, 60-80, 80+. Bucket values are not additive.",
+  "enum": [
+    "all",
+    "0-30",
+    "30-40",
+    "40-50",
+    "50-60",
+    "60-80",
+    "80+"
+  ],
+  "type": "string"
+}

AddedJun 9, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description layers substantial extra behavior on top: beta/experimental status, a 5-sample suppression rule on both sides, that the two sides come from different sources and are therefore approximate, and that aggregates exclude fractional shares and non-market deeds. These are non-obvious operational facts an agent could not infer from 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 beta warning is correctly front-loaded, followed by the metric definition and then caveats in descending importance. It is dense and a few clauses run long (coverage and gmina resolution are compressed into single sentences), but no sentence is filler.

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 carries the return burden and does explain the key output field (spread_pct), that the resolved county appears in the answer, and that ambiguous names return candidates. It does not describe the rest of the response shape or whether sample counts are returned, which would matter for judging the 5-sample suppression.

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 all four parameters are already documented, including enum meanings and the teryt-over-location precedence. The description mostly restates that 'all' means the whole market and that primary/secondary narrow both sides, which duplicates the schema rather than adding new parameter-level meaning; the genuinely additive bits (spread definition, suppression threshold) are not parameter-specific.

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 names a specific metric (asking-vs-transaction price spread per m²), states the exact formula (spread_pct = (asking − transaction) / transaction × 100), and scopes it to Polish counties and Warszawa districts. It is clearly separable from siblings like get_price_statistics or get_price_distribution, which do not compute an asking/transaction gap.

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?

It gives real usage context: coverage limits (only cities with asking-sale data), the caveat that results are not comparable across different as_of dates, that a negative spread is a valid answer, and that a gmina name resolves to its county while ambiguous names return candidates. It stops short of explicitly routing the agent to a sibling (e.g. list_price_spread_locations for coverage discovery or get_price_statistics for absolute prices).

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

All Cenogram - Polish Real Estate Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?