deweloperuch-mcp

Szukaj ofert mieszkań

search_offers

Read-only

Find primary-market apartment offers from Polish developers by city or district, filtered by price, area, price per m², status, and price drops, with sorting and paginated results.

Instructions

Wyszukuje oferty mieszkań od deweloperów (tylko rynek pierwotny, ceny ofertowe, nie transakcyjne) w jednym mieście albo w jego dzielnicy; city=polska nie działa. city_slug i nazwę dzielnicy daje search_locations. Filtry: cena, metraż, cena za m², dzielnica, status (aktywne, archiwalne) i obniżka od pierwszej ceny; sortowanie po cenie, cenie za m², metrażu albo największej obniżce; lista ofert nie filtruje po pokojach ani piętrze, ani po deweloperze (jego inwestycje daje get_developer).

Zwraca jedną stronę: total (wszystkie pasujące), returned, page, per_page, pages_available, truncated, hint, list_url i items (offer_id, investment_slug, investment_url, name, cena w PLN, metraż w m², cena za m², status, inwestycja z dzielnicą, deweloper z developer_slug, zmiany ceny w procentach). Pozycje są skrócone; szczegóły oferty i historię ceny daje get_offer. Linki podawaj użytkownikowi.

Ograniczenia: można przejrzeć najwyżej 20 stron po per_page ofert. Gdy truncated=true, zawęź filtry (np. dzielnica, cena) zamiast przeglądać kolejne strony. Wszystkie oferty jednej inwestycji daje get_investment, ceny całego miasta get_market_statistics.

Input Schema

Name	Required	Description	Default
`city`	Yes	city_slug jednego miasta z search_locations, np. warszawa, krakow (nie polska: serwis nie ma listy ofert całego kraju).
`page`	No	Numer strony wyników, 1–20 (dalej serwis nie udostępnia: zawęź filtry).
`sort`	No	price_asc: od najtańszych, price_desc: od najdroższych, price_per_m2_asc i price_per_m2_desc: po cenie za m², area_asc i area_desc: po metrażu, biggest_drop: najpierw największa obniżka od pierwszej ceny (w %); brak: domyślna kolejność serwisu (nie jest gwarantowana; zwykle najstarsze oferty, grupami po inwestycji; to nie ranking), więc do przeglądu miasta podaj sort.
`status`	No	active (domyślnie): oferty obecnie w cennikach; archived: tylko wycofane; all: aktywne i wycofane (total przy all może być większy niż suma active i archived: serwis liczy je niejasno).	active
`area_max`	No	Największy metraż w m².
`area_min`	No	Najmniejszy metraż w m².
`district`	No	Nazwa dzielnicy, np. Mokotów albo Praga-Południe (wielkość liter, polskie znaki, spacje i myślniki nie mają znaczenia); razem z city_slug jej miasta. Lista dzielnic: search_locations (kind=district).
`per_page`	No	10 albo 50. Pozycja to ok. 500 znaków wyniku (z linkiem), więc 50 daje ok. 25 tys.; zwykle wystarcza 10.
`price_max`	No	Najwyższa cena oferty w PLN.
`price_min`	No	Najniższa cena oferty w PLN.
`price_dropped`	No	true: tylko oferty, których obecna cena jest niższa od pierwszej ceny (liczy się zmiana od pierwszej ceny, nie ostatnia zmiana).
`price_per_m2_max`	No	Najwyższa cena za m² w PLN.
`price_per_m2_min`	No	Najniższa cena za m² w PLN.

Output Schema

Name	Required	Description
`hint`	No
`page`	Yes
`items`	Yes
`total`	Yes
`list_url`	No	Ta lista ofert na deweloperuch.pl (te same filtry, sortowanie i strona): podaj ją użytkownikowi jako link.
`per_page`	Yes
`returned`	Yes
`truncated`	Yes	true: pasujących ofert jest więcej, niż można przejrzeć (najwyżej 20 stron); zawęź filtry.
`pages_available`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.2.0Nov 5, 2026

changedInput schema / properties / city / description

Previous value: -"city_slug miasta z search_locations (np. warszawa, krakow) albo polska dla całego kraju."New value: +"city_slug jednego miasta z search_locations, np. warszawa, krakow (nie polska: serwis nie ma listy ofert całego kraju)."

changedInput schema / properties / district / description

Previous value: -"Nazwa dzielnicy dokładnie tak, jak podaje ją search_locations (kind=district, pole name), np. Mokotów; tylko z miastem tej dzielnicy, nie z polska."New value: +"Nazwa dzielnicy, np. Mokotów albo Praga-Południe (wielkość liter, polskie znaki, spacje i myślniki nie mają znaczenia); razem z city_slug jej miasta. Lista dzielnic: search_locations (kind=district)."

changedInput schema / properties / page / description

Previous value: -"Numer strony wyników, 1–20."New value: +"Numer strony wyników, 1–20 (dalej serwis nie udostępnia: zawęź filtry)."

changedInput schema / properties / sort / description

Previous value: -"price_asc: od najtańszych, price_desc: od najdroższych, price_per_m2_asc i price_per_m2_desc: po cenie za m², area_asc i area_desc: po metrażu, biggest_drop: najpierw największa obniżka od pierwszej ceny (w %); brak: domyślna kolejność serwisu (nie jest gwarantowana)."New value: +"price_asc: od najtańszych, price_desc: od najdroższych, price_per_m2_asc i price_per_m2_desc: po cenie za m², area_asc i area_desc: po metrażu, biggest_drop: najpierw największa obniżka od pierwszej ceny (w %); brak: domyślna kolejność serwisu (nie jest gwarantowana; zwykle najstarsze oferty, grupami po inwestycji; to nie ranking), więc do przeglądu miasta podaj sort."

changedInput schema / properties / status / description

Previous value: -"active (domyślnie): oferty obecnie w cennikach; archived: tylko wycofane; all: aktywne i wycofane."New value: +"active (domyślnie): oferty obecnie w cennikach; archived: tylko wycofane; all: aktywne i wycofane (total przy all może być większy niż suma active i archived: serwis liczy je niejasno)."

removedOutput schema / $defs / OfferItem / properties / city

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Tylko przy city=polska.",
-  "title": "City"
-}

removedOutput schema / $defs / OfferItem / properties / city_slug

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Tylko przy city=polska.",
-  "title": "City Slug"
-}

addedOutput schema / $defs / OfferItem / properties / district

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Dzielnica inwestycji, nazwa jak w search_locations (kind=district): można ją podać w district. Brak, gdy serwis jej nie podaje (np. Sopot).",
+  "title": "District"
+}

changedOutput schema / $defs / OfferItem / properties / last_price_change_kind / description

Previous value: -"increase, decrease albo no_change."New value: +"increase, decrease, no_change albo new_offer (oferta bez zmiany ceny od dodania)."

addedOutput schema / $defs / OfferItem / properties / name / description

Added value: +"Oznaczenie mieszkania u dewelopera (np. A2, D1.1.1.4); nazwa inwestycji jest w investment_name."

First observedv0.1.3Oct 16, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. Beyond that the description discloses genuinely useful behaviour: a hard 20-page ceiling, what truncated=true means and the instruction to narrow filters rather than page further, and the caveat that status=all totals are computed inconsistently upstream. These are substantive additions, but return-format detail overlaps with the output schema, so it sits comfortably above a bare baseline rather than at the top.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded and organised into purpose, return shape and limits, and each block carries real information. However the semicolon-chained sentences are dense, and the item-field enumeration duplicates the existing output schema, which is exactly the kind of repetition that dilutes a definition without adding value.

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?

For a 13-parameter, paginated, cross-referenced search tool this covers what an agent needs: entry prerequisites, filter capabilities, pagination limits and truncation handling, plus routing to get_offer and get_investment for depth. Given an output schema already exists, the field-by-field return listing is redundant rather than filling a gap, which is the only shortfall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, yet the description still adds meaning the schema lacks: it enumerates the supported filter set, explains that an omitted sort yields an unguaranteed, non-ranking default order (so an agent should always pass sort), and warns that price_dropped keys off the change from the first price. It also documents the negative space — no room, floor or developer filters — which is parameter semantics no schema can express.

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 gives a specific verb and resource ('Wyszukuje oferty mieszkań od deweloperów') plus hard scope boundaries: primary market only, asking prices rather than transaction prices, one city or one district, and the explicit caveat that city=polska does not work. It also names the siblings that serve different purposes (get_offer, get_investment, get_developer, search_locations), so an agent can separate this tool from 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 call it (city or district level search) and when not to (no room/floor/developer filtering; use get_developer for a developer's projects, get_investment for all offers in one investment, get_market_statistics for city-wide price levels). It also gives the exact preconditions: obtain city_slug and district names from search_locations, because the city value must be a single-city slug.

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

Deploy Server