deweloperuch-mcp

Ceny transakcyjne w czasie

get_transaction_statistics

Read-only

Retrieves actual apartment sale prices and transaction counts per city from RCN, monthly (secondary market) or quarterly, for real market analysis.

Instructions

Zwraca ceny transakcyjne mieszkań w mieście z Rejestru Cen Nieruchomości (RCN) od 2017 r., w kolejnych miesiącach albo kwartałach: liczbę transakcji i ceny za m². To ceny faktycznych sprzedaży, a nie ceny ofertowe deweloperów (search_offers, get_market_statistics) ani oficjalne ceny NBP (get_government_statistics).

granularity=month (domyślnie): tylko rynek wtórny; mediana i średnia ceny za m², mediana metrażu i mediana ceny mieszkania. granularity=quarter: tylko mediana ceny za m² i liczba transakcji; rynek nieokreślony. Miesiące i kwartały to różne statystyki: nie łącz ich w jeden wykres ani szereg.

Ograniczenia: tylko mieszkania i całe miasta (city_slug z search_locations; bez dzielnic, ulic, agregatów (np. 7-miast) i całej Polski). Domyślnie ostatnie 12 okresów; truncated=true znaczy, że są starsze (zwiększ periods, najwyżej 60; całą historię od 2017 r. daje tylko quarter). Dane RCN spływają z opóźnieniem, więc najnowsze okresy są niepełne: okres z incomplete=true pomiń, nie podawaj jego cen jako trendu. Okres bez transakcji nie ma cen. Trend kończ na last_complete_period (jego dane też mogą się zmienić); brak pola (za mało transakcji): czytaj hint.

Input Schema

Name	Required	Description	Default
`city`	Yes	city_slug miasta z search_locations, np. warszawa, krakow, gdansk (małe litery bez polskich znaków). Statystyki są dla całych miast; dzielnice, ulice, agregaty miast (np. 7-miast) i cała Polska (polska) nie są obsługiwane.
`periods`	No	Ile ostatnich okresów (miesięcy albo kwartałów) zwrócić, 1–60, domyślnie 12. 60 miesięcy to ok. 9 tys. znaków; dla trendu wieloletniego wybierz quarter zamiast wielu miesięcy.
`granularity`	No	month (domyślnie): miesiące, tylko rynek wtórny, z medianą i średnią ceny za m², medianą metrażu i medianą ceny mieszkania; quarter: kwartały, tylko mediana ceny za m² i liczba transakcji (rynek nieokreślony), za to cała historia od 2017 r. w jednym wywołaniu (periods=60).	month

Output Schema

Name	Required	Description
`hint`	No	Co zrobić dalej: gdy wynik jest obcięty, ma okresy incomplete albo za mało transakcji, by je ocenić.
`note`	Yes	Uwaga do danych: najnowsze okresy są niepełne.
`total`	Yes	Wszystkie okresy, które serwis ma dla miasta.
`periods`	Yes	Okresy od najstarszego; okres bez transakcji nie ma cen ani metrażu.
`returned`	Yes	Okresy w wyniku: ostatnie z nich.
`city_slug`	Yes
`stats_url`	No	Strona statystyk transakcji na deweloperuch.pl dla ludzi: podaj ją użytkownikowi jako link.
`truncated`	Yes	true: są starsze okresy niż pokazane; co dalej, mówi hint.
`granularity`	Yes	month (miesiące) albo quarter (kwartały).
`available_from`	Yes	Najstarszy okres, jaki ma serwis.
`last_complete_period`	No	Najnowszy okres ze zwykłą liczbą transakcji (nie incomplete), pokazany lub nie; na nim kończ trend, choć jego dane mogą się jeszcze zmienić. Brak pola: za krótka historia albo za mało transakcji, by to ocenić.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedv0.2.0Nov 5, 2026

changedInput schema / properties / city / description

Previous value: -"city_slug miasta z search_locations, np. warszawa, krakow, gdansk (małe litery bez polskich znaków). Statystyki są dla całych miast; dzielnice, ulice i cała Polska (polska) nie są obsługiwane."New value: +"city_slug miasta z search_locations, np. warszawa, krakow, gdansk (małe litery bez polskich znaków). Statystyki są dla całych miast; dzielnice, ulice, agregaty miast (np. 7-miast) i cała Polska (polska) nie są obsługiwane."

changedInput schema / properties / granularity / description

Previous value: -"month (domyślnie): miesiące, z medianą i średnią ceny za m², medianą metrażu i medianą ceny mieszkania; quarter: kwartały, tylko średnia cena za m² i liczba transakcji, ale dłuższa historia."New value: +"month (domyślnie): miesiące, tylko rynek wtórny, z medianą i średnią ceny za m², medianą metrażu i medianą ceny mieszkania; quarter: kwartały, tylko mediana ceny za m² i liczba transakcji (rynek nieokreślony), za to cała historia od 2017 r. w jednym wywołaniu (periods=60)."

changedOutput schema / $defs / TransactionPeriodItem / properties / average_price_per_m2 / description

Previous value: -"Średnia cena transakcyjna 1 m² w PLN."New value: +"Średnia cena transakcyjna 1 m² w PLN (tylko granularity=month)."

addedOutput schema / $defs / TransactionPeriodItem / properties / incomplete

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "true: okres ma mniej niż połowę zwykłej liczby transakcji, bo dane RCN są jeszcze niepełne; nie wyciągaj wniosków z jego cen ani liczby transakcji. Pole jest tylko przy takich okresach.",
+  "title": "Incomplete"
+}

changedOutput schema / $defs / TransactionPeriodItem / properties / median_area_m2 / description

Previous value: -"Mediana metrażu w m² (tylko month)."New value: +"Mediana metrażu w m² (tylko granularity=month)."

changedOutput schema / $defs / TransactionPeriodItem / properties / median_price / description

Previous value: -"Mediana ceny transakcyjnej mieszkania w PLN (tylko month)."New value: +"Mediana ceny transakcyjnej mieszkania w PLN (tylko granularity=month)."

changedOutput schema / $defs / TransactionPeriodItem / properties / median_price_per_m2 / description

Previous value: -"Mediana ceny transakcyjnej 1 m² w PLN (tylko month)."New value: +"Mediana ceny transakcyjnej 1 m² w PLN."

changedOutput schema / properties / hint / description

Previous value: -"Co zrobić dalej, gdy wynik jest obcięty."New value: +"Co zrobić dalej: gdy wynik jest obcięty, ma okresy incomplete albo za mało transakcji, by je ocenić."

addedOutput schema / properties / last_complete_period

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Najnowszy okres ze zwykłą liczbą transakcji (nie incomplete), pokazany lub nie; na nim kończ trend, choć jego dane mogą się jeszcze zmienić. Brak pola: za krótka historia albo za mało transakcji, by to ocenić.",
+  "title": "Last Complete Period"
+}

First observedv0.1.3Oct 16, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Beyond the readOnly/openWorld annotations it discloses non-obvious behaviour: default of 12 periods, truncated=true meaning older data exists, the 60-period ceiling, publication lag causing incomplete periods, periods with no transactions, and that last_complete_period is still provisional with a hint field for suppressed values. That is substantive operational context, though the response envelope itself is left to the output schema.

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?

Structure is deliberate: purpose and sibling disambiguation first, then granularity semantics, then constraints and data-quality caveats. It is dense and the long run-on sentence about truncated, incomplete and last_complete_period packs several distinct rules together, but no sentence is filler.

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?

For a read-only three-parameter statistics tool with a full output schema, the description covers everything an agent needs: scope limits, mode trade-offs, pagination ceiling, data-lag handling and how to treat incomplete or empty periods. Return-value detail is correctly delegated to the output schema.

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% and the schema descriptions already define the month/quarter trade-offs, the 1–60 range and the city_slug format, so the description largely restates rather than adds. The only marginal additions are the pairing of truncated with periods and the note that periods=60 gives full history only for quarter.

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 (transaction prices for flats in a city from RCN since 2017) plus the measures returned, and explicitly separates this tool from three named siblings: search_offers, get_market_statistics and get_government_statistics. An agent can pick this tool over its neighbours without opening any schema.

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?

It states when to use each mode (month = secondary market with full medians; quarter = long history but fewer measures) and explicitly warns not to merge the two series. Hard exclusions are spelled out: flats only, whole cities only, no districts, streets, aggregates or Poland-wide data.

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

Deploy Server