deweloperuch-mcp

Ceny transakcyjne w czasie

get_transaction_statistics

Read-only

Fetch actual apartment sale prices per square meter and transaction counts for Polish cities by month or quarter from the RCN registry to analyze real market trends.

Instructions

Zwraca ceny transakcyjne mieszkań w mieście z Rejestru Cen Nieruchomości (RCN) 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): mediana i średnia ceny za m², mediana metrażu i mediana ceny mieszkania. granularity=quarter: tylko średnia cena za m² i liczba transakcji, za to dłuższa historia. Miesiące i kwartały to różne statystyki: nie łącz ich w jeden wykres ani szereg.

Zwraca periods (od najstarszego; okres bez transakcji nie ma cen) oraz total, returned, truncated, available_from, hint, note i stats_url (link dla użytkownika).

Ograniczenia: tylko mieszkania i całe miasta (city_slug z search_locations; bez dzielnic, ulic i całej Polski). Domyślnie ostatnie 12 okresów; truncated=true znaczy, że są starsze (zwiększ periods, najwyżej 60). Najnowsze miesiące są niepełne, bo transakcje trafiają do RCN z kilkumiesięcznym opóźnieniem: mają zaniżoną liczbę transakcji i niepewne ceny, więc ich spadku nie traktuj jako trendu (przeczytaj note).

Input Schema

TableJSON 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 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, 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.	month

Output Schema

TableJSON Schema

Name	Required	Description
`hint`	No	Co zrobić dalej, gdy wynik jest obcięty.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.3Oct 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses reporting latency ('transakcje trafiają do RCN z kilkumiesięcznym opóźnieniem'), that recent months are incomplete with understated counts and uncertain prices, that truncated=true signals older data exists, and that empty periods carry no prices. These caveats directly affect interpretation of results.

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, then distinctions, then behavioral caveats — good ordering. It is dense and repeats the month-vs-quarter field list that the granularity schema description already carries, which costs a little efficiency but the repetition is defensible for a statistical tool.

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?

Even though an output schema exists, the description enumerates the return envelope (periods, total, returned, truncated, available_from, hint, note, stats_url) and, more importantly, supplies the interpretive caveats (incomplete recent months, truncation semantics) an agent needs to use the output correctly. Nothing material is missing.

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 coverage is 100%, so the baseline is 3, but the description adds genuinely new guidance: the 60-period cap implies ~9k characters and the recommendation to use quarter for long-term trends. It also restates the scope restriction (whole cities only, no districts/streets/polska) that the schema already covers.

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 ('Zwraca ceny transakcyjne mieszkań w mieście z Rejestru Cen Nieruchomości') plus the unit of analysis (miesiące/kwartały: liczba transakcji i ceny za m²). It explicitly distinguishes itself from three siblings (search_offers, get_market_statistics, get_government_statistics) by contrasting actual sale prices against offer prices and NBP figures.

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?

Explicitly routes the agent: use search_offers/get_market_statistics for offer prices, get_government_statistics for official NBP prices, this tool for actual RCN transactions. It also states when to pick quarter over month ('dla trendu wieloletniego wybierz quarter zamiast wielu miesięcy') and warns not to combine months and quarters in one series.

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

Deploy Server