deweloperuch-mcp

Ranking miast i powiatów

rank_locations

Read-only

Compare and rank Polish cities, towns, or counties by real estate transaction counts, price per m², or GUS/NBP indicators to identify housing market leaders.

Instructions

Porównanie wielu miejsc w jednym okresie; nie zwraca szeregu czasowego. Dwa tryby: (1) bez indicator: ranking miejscowości (level=city) albo powiatów (level=powiat) wg transakcji z RCN (liczba, cena za m²); (2) z indicator: ranking 66 miast na prawach powiatu wg wskaźnika GUS lub NBP. Trend jednego miasta w czasie: get_transaction_statistics (RCN) albo get_government_statistics (GUS, NBP). Bez indicator to ceny transakcyjne z RCN, nie ofertowe; nbp_price_per_m2 to oficjalna cena NBP, nie RCN.

Zwraca total, returned, truncated, hint i items. Transakcje: min_transactions (zastosowany próg), items (name, city_slug albo powiat_id, transaction_count, price_per_m2, area_m2, price); dla city ranking_url (link dla użytkownika); dla powiat market i okres 12 miesięcy period_start–period_end. Wskaźnik: indicator, unit, period, items (name, city_slug, value, stats_url: link dla użytkownika).

Ograniczenia: serwis nie mówi, czy ceny i metraż to średnie, czy mediany. Okresu miejscowości serwis nie podaje; nie porównuj liczb transakcji miejscowości i powiatów. Sortowanie po cenie domyślnie pomija miejsca poniżej 20 transakcji (cena bywa przypadkowa); min_transactions=0 pokazuje wszystkie.

Input Schema

Name	Required	Description	Default
`sort`	No	transactions_desc: najwięcej transakcji (domyślnie bez indicator); price_per_m2_desc, price_per_m2_asc: najwyższa, najniższa cena za m² (miejsca bez ceny na końcu); value_desc (domyślnie z indicator), value_asc: najwyższa, najniższa wartość wskaźnika, tylko z indicator.
`level`	No	city: miejscowości (miasta, także małe miasteczka i wsie), domyślnie; powiat: powiaty, tylko transakcje (market); powiaty nie mają city_slug ani ranking_url i nie ma ich w search_locations. Z indicator tylko city.	city
`limit`	No	Ile pierwszych pozycji rankingu zwrócić, 1–100, domyślnie 20. Pozycja to ok. 120 znaków wyniku. Dla pełnych list zawężaj min_transactions, nie podnoś limitu bez potrzeby.
`market`	No	Tylko level=powiat. secondary: rynek wtórny (domyślnie); primary: pierwotny; all: oba rynki w zestawieniu serwisu (jego liczba transakcji nie zawsze równa się secondary + primary). Powiaty bez danych dla rynku są pominięte (hint).
`indicator`	No	Ranking 66 miast na prawach powiatu według wskaźnika zamiast transakcji (bez level=powiat, min_transactions i market): unemployment_rate: stopa bezrobocia rejestrowanego (%) w miesiącu; average_wage: przeciętne miesięczne wynagrodzenie brutto (PLN), średnia za rok period (jak dataset=wages w get_government_statistics); dwellings_completed, dwellings_started: mieszkania oddane, rozpoczęte w 12 miesiącach do miesiąca period; average_dwelling_area: powierzchnia mieszkania (m²) podana przez serwis za okres period; nie porównuj jej z average_area z get_government_statistics (inna definicja); natural_increase: przyrost naturalny (osoby) w roku; nbp_price_per_m2: cena transakcyjna rynku wtórnego wg NBP (PLN/m²) w kwartale, tylko 17 miast. Miasta bez wartości są pominięte (hint).
`min_transactions`	No	Brak = próg domyślny: 20 przy sortowaniu po cenie, 0 przy transactions_desc. 0 = wszystkie miejsca. Pomija miejsca z mniejszą liczbą transakcji; np. 50 daje stabilniejsze ceny. Nie działa z indicator.

Output Schema

Name	Required	Description
`hint`	No	Co zrobić, gdy wynik jest obcięty albo pusty, oraz co pominięto: małe miejsca przy sortowaniu po cenie (domyślny próg), powiaty bez danych dla market, miasta bez wskaźnika.
`sort`	Yes	Kolejność rankingu, jak w argumencie sort.
`unit`	No	Jednostka value: %, PLN/mies., mieszkania (suma 12 miesięcy), m², osoby albo PLN/m².
`items`	Yes
`level`	Yes	city (miejscowości) albo powiat (powiaty).
`total`	Yes	Wszystkie miejsca spełniające kryteria: z co najmniej min_transactions transakcji, z danymi dla market albo z wartością wskaźnika.
`market`	No	Rynek rankingu powiatów: secondary, primary albo all.
`period`	No	Okres wartości wskaźnika: miesiąc (RRRR-MM), kwartał (RRRR-Qn) albo rok (RRRR); dla dwellings_completed i dwellings_started ostatni miesiąc okna 12 miesięcy.
`returned`	Yes	Pozycje w items: pierwsze z rankingu.
`indicator`	No	Wskaźnik rankingu, jak w argumencie.
`truncated`	Yes	true: miejsc jest więcej, niż pokazano; co dalej, mówi hint.
`period_end`	No	Ostatni miesiąc okresu transakcji powiatów (RRRR-MM), wliczony w okres.
`ranking_url`	No	Strona rankingu miast na deweloperuch.pl (tylko level=city bez indicator): podaj ją użytkownikowi jako link.
`period_start`	No	Pierwszy dzień okresu transakcji powiatów (RRRR-MM-01).
`min_transactions`	No	Zastosowany próg: min_transactions z argumentu, a bez niego domyślny: 20 przy sortowaniu po cenie, 0 przy transactions_desc (0 = wszystkie miejsca). Brak przy indicator.

Schema Changelog

Changes observed during successful MCP inspections.

Changed35 schema fields changedv0.2.0Nov 5, 2026

addedInput schema / properties / indicator

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "unemployment_rate",
+        "average_wage",
+        "dwellings_completed",
+        "dwellings_started",
+        "average_dwelling_area",
+        "natural_increase",
+        "nbp_price_per_m2"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Ranking 66 miast na prawach powiatu według wskaźnika zamiast transakcji (bez level=powiat, min_transactions i market): unemployment_rate: stopa bezrobocia rejestrowanego (%) w miesiącu; average_wage: przeciętne miesięczne wynagrodzenie brutto (PLN), średnia za rok period (jak dataset=wages w get_government_statistics); dwellings_completed, dwellings_started: mieszkania oddane, rozpoczęte w 12 miesiącach do miesiąca period; average_dwelling_area: powierzchnia mieszkania (m²) podana przez serwis za okres period; nie porównuj jej z average_area z get_government_statistics (inna definicja); natural_increase: przyrost naturalny (osoby) w roku; nbp_price_per_m2: cena transakcyjna rynku wtórnego wg NBP (PLN/m²) w kwartale, tylko 17 miast. Miasta bez wartości są pominięte (hint).",
+  "title": "Wskaźnik"
+}

changedInput schema / properties / level / description

Previous value: -"city: miejscowości (miasta, także małe miasteczka i wsie), domyślnie; powiat: powiaty (bez ranking_url i bez odpowiednika w search_locations)."New value: +"city: miejscowości (miasta, także małe miasteczka i wsie), domyślnie; powiat: powiaty, tylko transakcje (market); powiaty nie mają city_slug ani ranking_url i nie ma ich w search_locations. Z indicator tylko city."

addedInput schema / properties / market

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "secondary",
+        "primary",
+        "all"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Tylko level=powiat. secondary: rynek wtórny (domyślnie); primary: pierwotny; all: oba rynki w zestawieniu serwisu (jego liczba transakcji nie zawsze równa się secondary + primary). Powiaty bez danych dla rynku są pominięte (hint).",
+  "title": "Rynek"
+}

addedInput schema / properties / min_transactions / anyOf

Added value: +[
+  {
+    "maximum": 10000000,
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / min_transactions / default
```
Previous value: -0New value: +null
```

changedInput schema / properties / min_transactions / description

Previous value: -"Pomiń miejsca z mniejszą liczbą transakcji; domyślnie 0 (wszystkie). Przy sortowaniu miejscowości (level=city) po cenie podaj np. 50."New value: +"Brak = próg domyślny: 20 przy sortowaniu po cenie, 0 przy transactions_desc. 0 = wszystkie miejsca. Pomija miejsca z mniejszą liczbą transakcji; np. 50 daje stabilniejsze ceny. Nie działa z indicator."

removedInput schema / properties / min_transactions / maximum
```
Removed value: -10000000
```
removedInput schema / properties / min_transactions / minimum
```
Removed value: -0
```
removedInput schema / properties / min_transactions / type
```
Removed value: -"integer"
```

addedInput schema / properties / sort / anyOf

Added value: +[
+  {
+    "enum": [
+      "transactions_desc",
+      "price_per_m2_desc",
+      "price_per_m2_asc",
+      "value_desc",
+      "value_asc"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / sort / default

Previous value: -"transactions_desc"New value: +null

changedInput schema / properties / sort / description

Previous value: -"transactions_desc: najwięcej transakcji (domyślnie); price_per_m2_desc: najwyższa cena za m²; price_per_m2_asc: najniższa cena za m². Miejsca bez ceny są na końcu."New value: +"transactions_desc: najwięcej transakcji (domyślnie bez indicator); price_per_m2_desc, price_per_m2_asc: najwyższa, najniższa cena za m² (miejsca bez ceny na końcu); value_desc (domyślnie z indicator), value_asc: najwyższa, najniższa wartość wskaźnika, tylko z indicator."

removedInput schema / properties / sort / enum

Removed value: -[
-  "transactions_desc",
-  "price_per_m2_desc",
-  "price_per_m2_asc"
-]

removedInput schema / properties / sort / type
```
Removed value: -"string"
```

addedOutput schema / $defs / RankedLocationItem / properties / stats_url

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Link do strony wskaźnika miasta na deweloperuch.pl (tylko z indicator): podaj go użytkownikowi.",
+  "title": "Stats Url"
+}

addedOutput schema / $defs / RankedLocationItem / properties / transaction_count / anyOf
```
Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
```
addedOutput schema / $defs / RankedLocationItem / properties / transaction_count / default
```
Added value: +null
```

changedOutput schema / $defs / RankedLocationItem / properties / transaction_count / description

Previous value: -"Liczba transakcji wg serwisu; okresu serwis nie podaje (dla powiatów wiele lat: tylko do uporządkowania)."New value: +"Liczba transakcji wg serwisu: dla powiatu w okresie period_start–period_end, dla miejscowości w okresie, którego serwis nie podaje."

removedOutput schema / $defs / RankedLocationItem / properties / transaction_count / type
```
Removed value: -"integer"
```

addedOutput schema / $defs / RankedLocationItem / properties / value

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Wartość wskaźnika (indicator) w jednostce unit za okres period.",
+  "title": "Value"
+}

changedOutput schema / $defs / RankedLocationItem / required

Previous value: -[
-  "name",
-  "transaction_count"
-]New value: +[
+  "name"
+]

changedOutput schema / properties / hint / description

Previous value: -"Co zrobić, gdy wynik jest obcięty albo pusty."New value: +"Co zrobić, gdy wynik jest obcięty albo pusty, oraz co pominięto: małe miejsca przy sortowaniu po cenie (domyślny próg), powiaty bez danych dla market, miasta bez wskaźnika."

addedOutput schema / properties / indicator

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Wskaźnik rankingu, jak w argumencie.",
+  "title": "Indicator"
+}

addedOutput schema / properties / market

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Rynek rankingu powiatów: secondary, primary albo all.",
+  "title": "Market"
+}

addedOutput schema / properties / min_transactions / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / min_transactions / default
```
Added value: +null
```

changedOutput schema / properties / min_transactions / description

Previous value: -"Próg z argumentu min_transactions (0 = wszystkie miejsca)."New value: +"Zastosowany próg: min_transactions z argumentu, a bez niego domyślny: 20 przy sortowaniu po cenie, 0 przy transactions_desc (0 = wszystkie miejsca). Brak przy indicator."

removedOutput schema / properties / min_transactions / type
```
Removed value: -"integer"
```

addedOutput schema / properties / period

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Okres wartości wskaźnika: miesiąc (RRRR-MM), kwartał (RRRR-Qn) albo rok (RRRR); dla dwellings_completed i dwellings_started ostatni miesiąc okna 12 miesięcy.",
+  "title": "Period"
+}

addedOutput schema / properties / period_end

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Ostatni miesiąc okresu transakcji powiatów (RRRR-MM), wliczony w okres.",
+  "title": "Period End"
+}

addedOutput schema / properties / period_start

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Pierwszy dzień okresu transakcji powiatów (RRRR-MM-01).",
+  "title": "Period Start"
+}

changedOutput schema / properties / ranking_url / description

Previous value: -"Strona rankingu miast na deweloperuch.pl (tylko level=city): podaj ją użytkownikowi jako link."New value: +"Strona rankingu miast na deweloperuch.pl (tylko level=city bez indicator): podaj ją użytkownikowi jako link."

changedOutput schema / properties / total / description

Previous value: -"Wszystkie miejsca tego poziomu z co najmniej min_transactions transakcji."New value: +"Wszystkie miejsca spełniające kryteria: z co najmniej min_transactions transakcji, z danymi dla market albo z wartością wskaźnika."

addedOutput schema / properties / unit

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Jednostka value: %, PLN/mies., mieszkania (suma 12 miesięcy), m², osoby albo PLN/m².",
+  "title": "Unit"
+}

changedOutput schema / required

Previous value: -[
-  "level",
-  "sort",
-  "min_transactions",
-  "total",
-  "returned",
-  "truncated",
-  "items"
-]New value: +[
+  "level",
+  "sort",
+  "total",
+  "returned",
+  "truncated",
+  "items"
+]

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 readOnlyHint/openWorldHint by disclosing data-quality caveats an agent could not infer: the service doesn't say whether prices/area are mean or median, city period is not reported, price sorting silently drops places below 20 transactions unless min_transactions=0, market=all totals may not equal secondary+primary, and nbp_price_per_m2 covers only 17 cities. It also explains that omitted places are surfaced via 'hint', which directly affects how results should be interpreted.

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 purpose and the two modes, then constraints — good ordering. It is long, and the paragraph enumerating return fields overlaps with the existing output schema, which is the one place wording does not fully earn its space.

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 six-parameter, two-mode ranking tool with heavy cross-tool definitional traps, the description covers mode selection, incompatibilities, default thresholds, data caveats and result interpretation. Combined with the output schema, an agent has everything needed to call it correctly and to avoid the documented pitfalls.

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 already 100%, so this is above baseline: the description adds cross-field constraints the schema only partially implies (indicator excludes level=powiat, min_transactions and market), a usage tip for limit ('zawężaj min_transactions, nie podnoś limitu'), and a definitional warning that average_dwelling_area is not comparable to average_area from get_government_statistics. Slightly redundant in restating enum semantics already documented per-parameter.

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 opening sentence names a specific verb+resource ('Porównanie wielu miejsc w jednym okresie') and immediately states the negative scope ('nie zwraca szeregu czasowego'), then splits it into two explicit modes (with/without indicator). It names the sibling tools that cover the excluded case, so an agent can route 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?

Explicit when-to-use routing: 'Trend jednego miasta w czasie: get_transaction_statistics (RCN) albo get_government_statistics (GUS, NBP)'. Mode selection conditions are stated (level=city vs powiat without indicator, indicator forces city-only), and it warns against an invalid comparison ('nie porównuj liczb transakcji miejscowości i powiatów').

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

Deploy Server