deweloperuch-mcp

Ranking miast i powiatów

rank_locations

Read-only

Compare Polish cities or counties by RCN transaction count and price per m² to see where activity is high or prices are low.

Instructions

Ranking miejscowości (level=city) albo powiatów (level=powiat) w Polsce według transakcji z Rejestru Cen Nieruchomości (RCN): liczba transakcji i cena transakcyjna za m². Dla porównania wielu miast (gdzie najwięcej transakcji, gdzie najdrożej, gdzie najtaniej): to narzędzie; dla trendu jednego miasta w czasie: get_transaction_statistics. To ceny transakcyjne, nie ofertowe; oferty deweloperów daje search_offers.

Zwraca total (miejsca z co najmniej min_transactions transakcji), returned, truncated, hint i items (name, city_slug albo powiat_id, transaction_count, price_per_m2, area_m2, price); dla city także ranking_url (strona rankingu na deweloperuch.pl: podaj ją użytkownikowi jako link). powiat_id jest informacyjny: żadne narzędzie go nie przyjmuje.

Ograniczenia: serwis nie podaje okresu ani tego, czy ceny i metraż to średnie, czy mediany: przedstawiaj je jako wartości podane przez serwis. Liczby transakcji powiatów obejmują wiele lat: służą tylko do uporządkowania, nie są bieżącym wolumenem; nie porównuj ich z liczbami miejscowości. Przy sortowaniu miejscowości po cenie podaj min_transactions (np. 50): przy kilku transakcjach cena bywa przypadkowa.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sort`	No	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.	transactions_desc
`level`	No	city: miejscowości (miasta, także małe miasteczka i wsie), domyślnie; powiat: powiaty (bez ranking_url i bez odpowiednika w search_locations).	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.
`min_transactions`	No	Pomiń miejsca z mniejszą liczbą transakcji; domyślnie 0 (wszystkie). Przy sortowaniu miejscowości (level=city) po cenie podaj np. 50.

Output Schema

TableJSON Schema

Name	Required	Description
`hint`	No	Co zrobić, gdy wynik jest obcięty albo pusty.
`sort`	Yes	Kolejność rankingu, jak w argumencie sort.
`items`	Yes
`level`	Yes	city (miejscowości) albo powiat (powiaty).
`total`	Yes	Wszystkie miejsca tego poziomu z co najmniej min_transactions transakcji.
`returned`	Yes	Pozycje w items: pierwsze z rankingu.
`truncated`	Yes	true: miejsc jest więcej, niż pokazano; co dalej, mówi hint.
`ranking_url`	No	Strona rankingu miast na deweloperuch.pl (tylko level=city): podaj ją użytkownikowi jako link.
`min_transactions`	Yes	Próg z argumentu min_transactions (0 = wszystkie miejsca).

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?

Annotations only declare readOnlyHint/openWorldHint; the description adds substantial behavioral context the annotations cannot: return envelope (total, returned, truncated, hint, items), the ranking_url for city level, the fact powiat_id is informational and accepted by no tool, and data-quality caveats (no period given, mean/median unknown, powiat counts span many years and are not comparable to city counts).

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?

Dense but well-structured: purpose and routing first, then return shape, then constraints. All sentences carry information, though the return-shape detail is somewhat redundant given the tool has an output schema.

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 ranking tool with a full output schema and 100% parameter coverage, the description covers routing, data caveats, and result interpretation (ranking_url to hand to the user, non-comparable powiat counts). Nothing an agent needs to call and present it correctly 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 description coverage is 100%, so the schema already explains sort, level, limit and min_transactions; the description's parameter value is mostly reinforcement plus practical guidance (e.g., set min_transactions≈50 when sorting by price, don't raise limit unnecessarily). It adds some real advice beyond the schema but does not carry the primary burden.

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 verb+resource: ranking of Polish towns (level=city) or powiatów by RCN transactions, with metrics (transaction count, price per m²). It explicitly distinguishes itself from get_transaction_statistics (single-city trend) and search_offers (offer prices), so an agent can route without opening the 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: comparing many cities (most transactions, most expensive, cheapest) → this tool; single city over time → get_transaction_statistics; developer offer prices → search_offers. It also gives a concrete usage rule (supply min_transactions ~50 when sorting cities by price).

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

Deploy Server