Deweloperuch MCP
Server Details
Polish flat prices on deweloperuch.pl: RCN sale prices (valuation, stats, rankings), asking prices.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
TDQS
Scored across 10 tools
The 10 tools partition cleanly into two explicitly-labelled price families (developers' asking prices vs. RCN transaction prices) plus two slug-lookup helpers, and each description states when to prefer a sibling (e.g. get_investment vs get_offer, market_statistics vs transaction_statistics, rank_locations vs get_transaction_statistics). The get/search distinction is also spelled out: searches turn names into slugs, getters return data. No two tools appear to do the same thing.
Every tool follows the same deweloperuch_<verb>_<noun> pattern with verbs drawn from a small, predictable set (search_, get_, estimate_, rank_). Resource nouns match the domain vocabulary used in the descriptions (locations, investments, offers, developers, building).
Ten tools is well inside the sweet spot and each one covers a distinct step of the workflow: resolve a place/developer slug, browse projects, inspect an investment, drill into an offer, and four complementary market-data views. Nothing looks redundant or padded.
The surface covers the full path from location lookup through project/offer browsing to valuation and both statistics families, with sensible limits and STOP-handling documented. Minor dead ends remain: powiat_id is returned by rank_locations but no tool accepts it, there is no district-level filtering anywhere, and there is no direct developer-detail or offer search filtered by price/area (only city aggregates).
Available Tools
10 toolsdeweloperuch_estimate_property_valueEstimate a flat's valueARead-onlyInspect
Estimate the value of a flat of a given area at a point (lat, lng) in Poland from nearby transaction prices of the Real Estate Price Register (RCN), via deweloperuch.pl. The result is approximate: a comparison with nearby sales, not a professional appraisal. Use it when the user asks what a flat may be worth or whether its price is market. Needs coordinates — it does not geocode an address: take them from the user, from deweloperuch_search_locations (a street or district: an approximate point) or from the user's own data. Every call is a request to the site: do not value many points in a series. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Result shape: { lat, lng, area_m2, estimated_value (PLN, or null when the site gave no estimate — read the hint), low_confidence? (true when fewer than 5 comparable transactions: quote the estimate only as indicative, with the caveat from hint), price_per_m2?, radius_m?, period_months? (where and how long ago the comparables are from), stats?: { count, median_price_per_m2, average_price_per_m2, min_price_per_m2, max_price_per_m2 }, comparables_total, comparables_returned, comparables_omitted, truncated, hint?, source, comparables: [{ address?, date?, price, area_m2, price_per_m2, floor?, distance_m (rounded by the site to 50 m), market ('primary' | 'secondary'), building_slug? (for deweloperuch_get_building) }] } — the list key is comparables, the nearest first, at most limit of them (0 = only the estimate and stats). Do not assume estimated_value = price_per_m2 × area_m2: the site may ignore a fractional area.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude of the point in Poland in degrees, e.g. 52.2297 (lat of a street or district from deweloperuch_search_locations, not just a city). | |
| lng | Yes | Longitude of the point in Poland in degrees, e.g. 21.0122. | |
| limit | No | How many nearest comparable transactions to return, 0–50. Default 10 (about 210 characters each); 0 = only the estimate and stats. | |
| address | No | Optional address text, 3–200 characters, e.g. Marszałkowska 100, Warszawa. Sent to the site but it does not set the location: lat and lng do. | |
| area_m2 | Yes | Area of the flat in m², 10–500, e.g. 48.5. |
Output Schema
| Name | Required | Description |
|---|---|---|
| lat | Yes | |
| lng | Yes | |
| hint | No | |
| stats | No | |
| source | Yes | |
| area_m2 | Yes | |
| radius_m | No | |
| truncated | Yes | |
| comparables | Yes | |
| price_per_m2 | No | |
| period_months | No | |
| low_confidence | No | |
| estimated_value | Yes | |
| comparables_total | Yes | |
| comparables_omitted | Yes | |
| comparables_returned | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnly/openWorld annotations it discloses rate/load behavior ('every call is a request to the site', one request at a time, results cached), the STOP error protocol (retry nothing, no workaround, tell the user), the no-geocoding constraint, and the meaning of low_confidence and null estimated_value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and constraints are front-loaded, but the single dense paragraph then enumerates the whole result shape, which duplicates the output schema and buries the warning about mixing price regimes in the middle of a very long sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a network-dependent, open-world estimator with an output schema, it supplies everything an agent needs: coordinate sourcing, request etiquette, failure handling, and interpretation caveats for low-confidence or null results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so it starts at baseline 3; the description adds meaning the schema lacks — that address is sent but does not set the location, that limit=0 yields only the estimate and stats, and that estimated_value may not equal price_per_m2 × area_m2.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Estimate the value of a flat of a given area at a point in Poland') plus the data source (RCN transaction prices). It explicitly separates itself from the asking-price siblings, so an agent can route without opening another schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the triggering user question ('what a flat may be worth or whether its price is market'), names concrete sources for the required coordinates (user, deweloperuch_search_locations, user's own data) and warns against batching many points. It also groups siblings into two price regimes that must not be mixed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_get_buildingBuilding with transactionsARead-onlyInspect
A building of the Real Estate Price Register (RCN): address, coordinates, the site's average prices and the flats sold in it with the date, price, price per m², market, kind and parties of each transaction. These are the prices the flats sold for, not developers' asking prices. building_slug is the last part of the address of the building's page with transaction prices on deweloperuch.pl, e.g. 23-marca-79c-sopot — comparables of deweloperuch_estimate_property_value carry one in building_slug; when you have none, ask the user for the link of that page. building_url is that page. Order: the unit with the newest transaction first, each unit's transactions oldest first. Do not average transactions whose classification is not 'regular' (share, enforcement, discount…) with regular sales: they are not ordinary sales at a market price; non_regular_transactions counts them. Limits: buildings with flats only, not houses. Returns at most limit units (default 10); truncated and units_omitted say whether and how many were left out, units_total and transactions_total count the whole building. The newest months are often incomplete (the register lags). include_trend=true adds the mean price per m² of transactions around the building (radius radius_km) in the latest 12 quarters — one more request. Buyers and sellers appear only as a type, never by name. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Fields ending in _url are pages of deweloperuch.pl: give them to the user as links. Result shape: { building_slug, name? (the address as the register writes it; absent when it gives none — the place is then in city), building_url, city, city_slug, street?, lat, lng, avg_price?, avg_area_m2?, avg_price_per_m2? (the site's averages; a value of 0 or less is omitted), first_transaction_date, last_transaction_date, units_total, transactions_total, non_regular_transactions? (e.g. { share: 1 }), units: [{ floor?, rooms?, area_m2, transactions: [{ date, price, price_per_m2, currency? (absent = PLN), market ('primary' | 'secondary'), classification ('regular' | 'share' | 'bulk' | 'government' | 'enforcement' | 'discount' | 'anomaly_low' | 'anomaly_high'), buyer, seller ('natural_person' | 'legal_person'), share? (only when a share was sold) }] }], units_returned, units_omitted, truncated, hint?, neighbourhood_trend?: { radius_km?, total, returned, truncated, quarters: [{ period, avg_price_per_m2?, transactions? }] }, source } — the list key is units.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most units in the result (those with the newest transactions), default 10, at most 50; 0 = only the building summary. About 200 characters per transaction. | |
| building_slug | Yes | Building slug, e.g. 23-marca-79c-sopot: lowercase letters without Polish characters, digits and hyphens, from the building's page address or from comparables in deweloperuch_estimate_property_value. | |
| include_trend | No | true: add the mean price per m² of transactions around the building in the latest 12 quarters (one more request). Default false. |
Output Schema
| Name | Required | Description |
|---|---|---|
| lat | No | |
| lng | No | |
| city | Yes | |
| hint | No | |
| name | No | |
| units | Yes | |
| source | Yes | |
| street | No | |
| avg_price | No | |
| city_slug | Yes | |
| truncated | Yes | |
| avg_area_m2 | No | |
| units_total | Yes | |
| building_url | No | |
| building_slug | Yes | |
| units_omitted | Yes | |
| units_returned | Yes | |
| avg_price_per_m2 | No | |
| transactions_total | Yes | |
| neighbourhood_trend | No | |
| last_transaction_date | No | |
| first_transaction_date | No | |
| non_regular_transactions | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint already set, the description adds substantial context: ordering rules, non-regular transaction exclusions, truncation behavior, incomplete register months, the extra request for include_trend, and STOP error handling. It also discloses that parties appear only as types, never names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and key warnings are front-loaded, but the description is very long and repeats the entire result shape even though an output schema exists. Much of the price-taxonomy and return-field detail could be shortened without losing invocation guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, open-world read tool with an output schema, the definition covers limits, ordering, truncation, error handling, data caveats, and result interpretation. The remaining return-value details are also available in the output schema, so the description is operationally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input fields are already fully documented. The description adds provenance for building_slug and truncation behavior for limit, but it also refers to a radius_km value that is not an input parameter in the schema, which may confuse an agent about how to set include_trend.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states the exact resource and contents: an RCN building with address, coordinates, averages, and individual flat transactions. It also clearly separates this tool from sibling groups by naming which tools expose asking prices versus RCN transaction prices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly separates developers' asking-price tools from RCN transaction tools and explains how to obtain building_slug, including asking the user when none is available. However, it does not spell out how to choose between get_building and the other RCN transaction siblings such as get_transaction_statistics or estimate_property_value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_get_investmentInvestment with offersARead-onlyInspect
An investment (developer project): city, street, coordinates, developer, the average prices of active offers, the number of offers and the list of offers (active first, then archived). Use it to see the flats of one project. investment_slug comes from deweloperuch_search_investments. investment_url and developer_url are the investment's and developer's pages on deweloperuch.pl: give them to the user as links. Limits: returns at most limit offers (default 20); offers_returned, truncated and offers_omitted say what was left out — offers_total is the site's count (also archived). With a large investment do not raise the limit without need. include_history=true adds the price history of every returned offer: the result is longer and takes one more request. For a single offer use deweloperuch_get_offer. These are developers' asking prices. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Result shape: { investment_slug, name, status ('active' | 'archived'), investment_url?, city, city_slug, street?, lat?, lng?, currency?, developer: { developer_slug, name, website?, description? }, developer_url?, avg_price?, avg_area_m2?, avg_price_per_m2? (active offers, PLN), offers_active?, offers_total?, offers: [{ offer_id, name, status, price?, currency?, area_m2?, price_per_m2?, price_change_since_start? (PLN; negative = cheaper), price_change_since_start_pct?, creation_date?, last_event_date?, last_change_date?, price_history?: [{ date?, kind ('offer' | 'archived' | 'restored'), price? }] }], offers_returned, offers_omitted, truncated, source } — the list key is offers; kind: offer is every asking-price entry of the history, the first price and each change.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most offers in the result (active first), 0–200, default 20; 0 = only the investment summary. About 300 characters per offer, a few hundred more with the price history. | |
| include_history | No | true: add the price history of every returned offer (a longer result, one more request). Default false. | |
| investment_slug | Yes | investment_slug from deweloperuch_search_investments, e.g. smolna. |
Output Schema
| Name | Required | Description |
|---|---|---|
| lat | No | |
| lng | No | |
| city | Yes | |
| name | Yes | |
| offers | Yes | |
| source | Yes | |
| status | Yes | |
| street | No | |
| currency | No | |
| avg_price | No | |
| city_slug | Yes | |
| developer | Yes | |
| truncated | Yes | |
| avg_area_m2 | No | |
| offers_total | No | |
| developer_url | No | |
| offers_active | No | |
| investment_url | No | |
| offers_omitted | Yes | |
| investment_slug | Yes | |
| offers_returned | Yes | |
| avg_price_per_m2 | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/openWorldHint already declared, the description still adds substantial behavior: a polite one-request-at-a-time cached access model, include_history costing one extra request and a longer result, truncation semantics (offers_returned, offers_omitted, truncated, offers_total including archived), and the STOP-error protocol. It also warns that two price universes (asking vs. RCN transaction) must not be mixed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and usage before the limits and result shape, and nearly every sentence carries operational value. It is on the long side, and the exhaustive result-shape listing plus the eight-tool price-taxonomy boilerplate overlaps with the existing output schema and shared context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered read with three params, the description covers provenance of the slug, how to present URLs, pagination/truncation flags, optional price history cost, cross-tool price-type disambiguation, and a failure protocol. Nothing an agent needs to invoke it correctly or interpret the response is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters including the 0–200 range, default 20, and the cost of include_history. The description reinforces limit/history behavior and slug provenance but adds little syntax or format detail beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource precisely (an investment/developer project) and enumerates what it carries: city, street, coordinates, developer, average prices of active offers, and the offer list. It also differentiates from siblings explicitly — 'For a single offer use deweloperuch_get_offer' and the slug source is deweloperuch_search_investments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the use case ('see the flats of one project'), names the alternative for a single offer, and tells the agent not to raise the limit unnecessarily on large investments. It also states exactly what to do when a result is a STOP error: stop, no retries, no workarounds, inform the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_get_market_statisticsCity offer market statisticsARead-onlyInspect
Statistics of the developers' offer market in one city: the number of offers, investments and developers, the distribution of prices (PLN), prices per m² (PLN/m²) and areas (m²) as min, p25, median, p75 and max, and the largest developers by number of offers (developer_slug, offers, investments, median_price_per_m2, developer_url; developer_slug is an identifier — the developer's name is not part of the result). Optionally only offers within a price and area range. Use it when the question is about a city's market (typical prices, who has the most offers), not about particular flats. Limits: active offers only (no archived) and one city only (city_slug from deweloperuch_search_locations; polska does not work). The figures are computed here from the site's compact list of the city's active offers (the list itself never leaves; Warsaw's is 1.3 MB, so a call can take a few seconds) and can differ slightly from the site's own offer totals. These are developers' asking prices, not transaction prices. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Fields ending in _url are pages of deweloperuch.pl: give them to the user as links. Result shape: { city_slug, offers (matching active offers), investments, developers, price?, price_per_m2?, area_m2? (each { min, p25, median, p75, max }), top_developers: [{ developer_slug, offers, investments, median_price_per_m2?, developer_url? }], developers_returned, developers_omitted, truncated, hint? (also explains an empty result), list_url? (the same offers on deweloperuch.pl), source } — the list key is top_developers.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | city_slug of one city from deweloperuch_search_locations, e.g. krakow (not polska). | |
| area_max | No | Largest area in m². | |
| area_min | No | Smallest area in m². | |
| price_max | No | Highest offer price in PLN. | |
| price_min | No | Lowest offer price in PLN. | |
| top_developers | No | How many of the largest developers to show, 1–30. Default 10. |
Output Schema
| Name | Required | Description |
|---|---|---|
| hint | No | |
| price | No | |
| offers | Yes | |
| source | Yes | |
| area_m2 | No | |
| list_url | No | |
| city_slug | Yes | |
| truncated | Yes | |
| developers | Yes | |
| investments | Yes | |
| price_per_m2 | No | |
| top_developers | Yes | |
| developers_omitted | Yes | |
| developers_returned | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantially beyond readOnlyHint/openWorldHint: results are computed locally from a large underlying list (Warsaw ~1.3 MB, so calls can take seconds), figures may differ from the site's own totals, prices are asking not transaction prices, and it defines the STOP-error protocol plus the rule that _url fields go to the user as links. Minor deduction only because the RCN/price-family enumeration and STOP paragraph are boilerplate repeated across the tool family rather than tool-specific.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly — purpose first, then result fields, then limits and behavioral caveats. But it is a dense block that spends sentences on sibling tool lists for price-type separation and on a generic STOP-handling paragraph that is not specific to this tool, so it is longer than this tool alone requires.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, open-world, six-parameter filter tool with a full output schema, it covers everything an agent needs: required city source, optional filters, what is excluded (archived offers, multi-city), latency expectations, and the shape of an empty result via the hint field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description still adds meaning by framing the price/area parameters as an optional narrowing filter on the offer set and by tying top_developers to the returned list. It does not add units or default details beyond the schema, so it stays just above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource+scope: statistics of the developers' offer market in one city, then enumerates exactly what is returned (offer/investment/developer counts, price/price-per-m²/area distributions, top developers). It explicitly contrasts with sibling tools ('not about particular flats') and names the cross-cutting price-type boundary with the transaction tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('city's market — typical prices, who has the most offers'), when-not-to ('not about particular flats'), and which siblings belong to which price family. It also names prerequisites (city_slug from deweloperuch_search_locations) and exclusions (active offers only, one city only, polska does not work).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_get_offerOffer with price historyARead-onlyInspect
One offer with its full price history, investment and developer. Use it to see how a flat's asking price changed. Needs offer_id and investment_slug (both come from deweloperuch_get_investment; investment_slug also from deweloperuch_search_investments): offer_id alone is not enough. investment_url and developer_url are the investment's and developer's pages on deweloperuch.pl: give them to the user as links. price_flags (as of today; prices from offer and restored events, a withdrawal ends the price in effect; an archived offer is judged up to the day it was withdrawn): lowest_price_30d and lowest_price_90d are the lowest price in effect over the last 30 and 90 days, including one set before the window; price_changes is the number of price changes; largest_drop_pct and largest_rise_pct are the largest single drop and rise as a % of the previous price; suspicious_reduction=true when the latest drop came within 30 days after a rise and the new price is not below the lowest of the 30 days before it (a 'promotion' after a price increase). These are developers' asking prices, not transaction prices. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Result shape: { offer_id, name, status ('active' | 'archived'), price? (PLN, asking), currency?, area_m2?, price_per_m2?, price_change_since_start? (PLN; negative = cheaper), price_change_since_start_pct?, creation_date?, last_event_date?, last_change_date?, investment_slug, investment_name, investment_url?, city, city_slug, developer: { developer_slug, name, website?, description? }, developer_url?, price_history: [{ date?, kind ('offer' | 'archived' | 'restored'), price? }], price_flags: { lowest_price_30d?, lowest_price_90d?, price_changes, largest_drop_pct?, largest_rise_pct?, suspicious_reduction }, source } — the list key is price_history, oldest first. A flag with no basis (no drop yet) is omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes | offer_id from deweloperuch_get_investment. | |
| investment_slug | Yes | investment_slug of this offer's investment, e.g. smolna (from deweloperuch_search_investments or deweloperuch_get_investment). |
Output Schema
| Name | Required | Description |
|---|---|---|
| city | Yes | |
| name | Yes | |
| price | No | |
| source | Yes | |
| status | Yes | |
| area_m2 | No | |
| currency | No | |
| offer_id | Yes | |
| city_slug | Yes | |
| developer | Yes | |
| price_flags | No | |
| price_per_m2 | No | |
| creation_date | No | |
| developer_url | No | |
| price_history | Yes | |
| investment_url | No | |
| investment_name | Yes | |
| investment_slug | Yes | |
| last_event_date | No | |
| last_change_date | No | |
| price_change_since_start | No | |
| price_change_since_start_pct | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only readOnly and openWorld, so the description carries the rest and does it well: polite single-request access with caching, the STOP error protocol (retry nothing, report unavailability), the fact that price_flags are computed as of today with withdrawal/archival cutoffs, the exact definition of suspicious_reduction, and the caveat that these are asking rather than transaction prices.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and prerequisites are front-loaded, but the body is a single dense paragraph that dumps the entire result shape and repeats the asking-vs-transaction tool roster twice. Since an output schema already exists, the long field enumeration is largely redundant padding that could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity — derived price flags, mixed-source price data, an error protocol — the description leaves essentially nothing an agent needs unexplained. Even where it overlaps the output schema, the extra semantics (flag definitions, ordering 'oldest first', omission of baseless flags) remove ambiguity rather than repeat types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 real meaning: both parameters are mandatory and interdependent, and offer_id alone is insufficient. It also notes that investment_url and developer_url in the result are meant to be surfaced to the user as links.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb-and-resource statement: a single offer retrieved together with its price history, investment and developer, and adds the differentiating detail that prices are developers' asking prices. The sibling tools are named with their distinct price universes, so an agent can tell this apart from deweloperuch_get_investment or deweloperuch_get_transaction_statistics without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit use case ('to see how a flat's asking price changed') and an explicit prerequisite constraint: both offer_id and investment_slug are required and 'offer_id alone is not enough,' with the source tools named. It also states an exclusionary rule — do not mix these asking prices with RCN transaction prices from six named siblings — and spells out what to do on a STOP error.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_get_transaction_statisticsTransaction prices over timeARead-onlyInspect
Transaction prices of flats in one city from the Real Estate Price Register (RCN), month by month or quarter by quarter: the number of transactions and the prices per m². These are prices flats actually sold for, not developers' asking prices. granularity=month (default): median and mean price per m², median area and median flat price. granularity=quarter: only the mean price per m² and the count, but a longer history. Months and quarters are different statistics: do not join them in one chart or series. Limits: flats only and whole cities only (city_slug from deweloperuch_search_locations; no districts, streets or whole Poland). Default: the latest 12 periods; truncated=true means older ones exist (raise periods, at most 60). The newest periods are incomplete (the RCN lags by months): skip a period with incomplete=true — do not quote its prices as a trend — and end a trend at last_complete_period (even its data may still change). Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Fields ending in _url are pages of deweloperuch.pl: give them to the user as links. Result shape: { city_slug, granularity, total, returned, truncated, available_from, last_complete_period?, hint?, note, stats_url, source, periods: [{ period ('2025-08' | '2025-Q3'), transactions, incomplete? (only when true), median_price_per_m2?, average_price_per_m2?, median_area_m2?, median_price? }] } — the list key is periods, oldest first; a period without transactions has no prices. last_complete_period is omitted when the history is too short or has too few transactions to judge; then read hint. Read note before describing a trend.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | city_slug of a city from deweloperuch_search_locations, e.g. warszawa, krakow, gdansk (lowercase, no Polish characters). Whole cities only: not districts, streets or polska. | |
| periods | No | How many latest periods (months or quarters) to return, 1–60. Default 12. 60 months is about 9,000 characters; for a multi-year trend choose quarter. | |
| granularity | No | month (default): months with median and mean price per m², median area and median price; quarter: quarters with only the mean price per m² and the count, but a longer history. |
Output Schema
| Name | Required | Description |
|---|---|---|
| hint | No | |
| note | Yes | |
| total | Yes | |
| source | Yes | |
| periods | Yes | |
| returned | Yes | |
| city_slug | Yes | |
| stats_url | No | |
| truncated | Yes | |
| granularity | Yes | |
| available_from | Yes | |
| last_complete_period | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare read-only and open-world; the description adds substantial operational context: the RCN lags by months so the newest periods are incomplete, truncation semantics (truncated=true, raise periods up to 60), a politeness/rate constraint (one request at a time, cached), and a STOP-error protocol telling the agent to halt rather than retry. That is far beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then caveats, then result shape — well ordered and every paragraph carries real information. It is dense and repeats the granularity semantics already in the schema, and the result-shape block duplicates the output schema, so it is slightly heavier than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a data-retrieval tool: input sourcing, granularity trade-offs, truncation and incompleteness handling, error protocol, and where to read trend caveats (note, hint) are all covered. Nothing an agent needs in order to call and interpret this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are already documented, but the description adds meaning: the statistical output differs by granularity, the default is 12 periods, and the city parameter must be a whole-city slug sourced from another tool. It largely restates the schema's granularity text, keeping it short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — transaction prices per m² and transaction counts for flats in one city from the RCN — with an explicit scope (city-level, flats only). It also draws the crucial distinction against siblings: RCN sold prices versus developers' asking prices, naming both sets of tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when/when-not guidance: pull city_slug from deweloperuch_search_locations, no districts/streets/Poland, choose quarter when a multi-year history is needed, never join months and quarters in one series, skip incomplete=true periods and end trends at last_complete_period. It also names the sibling price tools that must not be mixed with this data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_rank_locationsRank cities and powiatsARead-onlyInspect
A ranking of localities (level=city) or powiats (level=powiat) in Poland by Real Estate Price Register (RCN) transactions: the number of transactions and the transaction price per m². Use it to compare many cities; for the trend of one city over time use deweloperuch_get_transaction_statistics. These are transaction prices, not asking prices. Limits: the site gives no period and does not say whether prices and areas are means or medians — present them as the values the site gives. Powiat transaction counts cover many years: they only order the list, are not the current volume and must not be compared with locality counts. Sorting by price leaves out places with fewer than 20 transactions by default (a price from a handful of sales is chance); min_transactions=0 shows all places, 50 gives steadier prices. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Fields ending in _url are pages of deweloperuch.pl: give them to the user as links. Result shape: { level, sort, min_transactions (the threshold applied), total (places with at least that many transactions), returned, truncated, hint?, ranking_url? (city level), source, items: [{ name, city_slug? (city) | powiat_id? (informational: no tool takes it), transaction_count, price_per_m2?, area_m2?, price? }] } — the list key is items. A place without a price has no price fields and sorts last by price.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | transactions_desc (default): most transactions; price_per_m2_desc: highest price per m²; price_per_m2_asc: lowest price per m². Places without a price come last. | |
| level | No | city (default): localities — cities, small towns and villages; powiat: powiats (no ranking_url and no counterpart in deweloperuch_search_locations). | |
| limit | No | How many top entries of the ranking to return, 1–100. Default 20 (about 120 characters each). To see more places narrow min_transactions rather than raising the limit. | |
| min_transactions | No | Fewest transactions a place needs to be ranked. Omitted = the default threshold: 20 when sorting by price, 0 for transactions_desc. 0 = all places; e.g. 50 gives steadier prices. |
Output Schema
| Name | Required | Description |
|---|---|---|
| hint | No | |
| sort | Yes | |
| items | Yes | |
| level | Yes | |
| total | Yes | |
| source | Yes | |
| returned | Yes | |
| truncated | Yes | |
| ranking_url | No | |
| min_transactions | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint and openWorldHint; the description adds far more: no stated period, unknown mean/median, powiat counts spanning many years that only order the list, the default 20-transaction price threshold and why it exists, one-request-at-a-time caching, and a STOP error protocol that forbids retries. It also tells the agent to hand _url fields to the user as links.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The scoping constraint and the alternative are front-loaded, and nearly every sentence carries operational content. It is dense to the point of being a wall of text with no paragraph breaks, and the long sibling enumeration in the 'two kinds of prices' passage could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All four parameters, the result semantics, the failure mode and the linking convention are covered. Restating the result shape is somewhat redundant given the output schema, but it adds interpretation (price-less places sort last, `items` is the list key) rather than just repeating field names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the enum values and limits are already documented. The description adds interpretive meaning beyond that: the rationale for the 20-transaction threshold ('a price from a handful of sales is chance') and the warning that powiat counts must not be compared with locality counts, which no parameter description conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names the exact resource (localities or powiats in Poland), the source (RCN transactions) and the two metrics returned (transaction count and price per m²). It also immediately distinguishes the tool from deweloperuch_get_transaction_statistics, so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: 'Use it to compare many cities; for the trend of one city over time use deweloperuch_get_transaction_statistics.' It also names the sibling group whose prices must not be mixed with these and states when to raise or lower min_transactions, which is exactly the decision an agent faces.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_search_developersSearch developersARead-onlyInspect
Find developers (primary market) by a fragment of the name, e.g. atal or dom development. Use it to turn a developer's name into the developer_slug that deweloperuch_search_investments takes (with city) to list that developer's investments. Returns no offers or prices. truncated=true means more developers match than shown: refine the name or raise limit (at most 20); total is null when it is only known that there are more. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Fields ending in _url are pages of deweloperuch.pl: give them to the user as links. Result shape: { total: number | null, returned, truncated, hint?, items: [{ developer_slug, name, offer_count? (the site's count of the developer's offers across Poland), developer_url? }] } — the list key is items. developer_url is the developer's profile for the whole of Poland on deweloperuch.pl.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Fragment of a developer name, 2–100 characters, e.g. atal, Dom Development. | |
| limit | No | Most developers in the result, 1–20, default 5 (about 150 characters each). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld annotations, it discloses that no offers or prices are returned, explains truncation and null total, describes polite rate limiting and caching, and gives explicit STOP-error handling. It also explains that _url fields should be presented to the user as links.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and usage are front-loaded, followed by behavioral constraints and result shape. Despite its length, each section carries operational value for calling the tool correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description supplies the full result shape, field meanings, truncation semantics, and error behavior. This is complete enough for an agent to call the tool and interpret its output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already well documented. The description reinforces the name-fragment use case and the limit/truncation relationship but does not add much syntax or meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: find developers by a name fragment. It distinguishes itself from deweloperuch_search_investments by explaining that this tool produces the developer_slug used there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage guidance: use it to turn a developer name into a developer_slug for deweloperuch_search_investments with a city. It also explains what to do when truncated=true: refine the name or raise limit, with a maximum of 20.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_search_investmentsSearch investmentsARead-onlyInspect
Search investments (developer projects, primary market). Two modes: with city (full data) or with name alone (whole Poland; only investment_slug, name and offers_active, in the site's order). Use it when the question is about projects rather than single flats: e.g. the cheapest per m² in a city, the investments of one developer (city + developer_slug from deweloperuch_search_developers), the slug of an investment by its name. With city it returns the investments the site shows on the city's map (those with active offers; ones without may be missing) with averages over active offers; name and developer_slug narrow the list, sort orders it (default: most active offers; entries without an average come last). Offers and details of one investment come from deweloperuch_get_investment (investment_slug); a particular offer's price history from deweloperuch_get_offer. No price or area filter here — for those ranges use deweloperuch_get_market_statistics. city=polska does not work. These are developers' asking prices. Two kinds of prices must not be mixed: developers' asking prices (deweloperuch_search_investments, deweloperuch_get_investment, deweloperuch_get_offer, deweloperuch_get_market_statistics), RCN transaction prices (deweloperuch_estimate_property_value, deweloperuch_get_transaction_statistics, deweloperuch_rank_locations, deweloperuch_get_building) — what flats actually sold for, from the Real Estate Price Register. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Fields ending in _url are pages of deweloperuch.pl: give them to the user as links. Result shape: { total: number | null (null when the site does not say — a search by name), returned, truncated, hint?, source, items: [with city: { investment_slug, name, city_slug?, district?, street?, status? ('active' | 'archived'), offers_active?, offers_total?, avg_price?, avg_area_m2?, avg_price_per_m2? (active offers only, as the site counts them), developer_slug?, developer_name?, investment_url?, developer_url? } | by name: { investment_slug, name, offers_active? }] } — the list key is items.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | city_slug of one city from deweloperuch_search_locations, e.g. warszawa, sopot (not polska). | |
| name | No | Fragment of an investment name, 2–100 characters, e.g. Kolibki. With city, case and Polish characters do not matter; without city the site searches the whole country. | |
| sort | No | Only with city. active_offers (default): most active offers; price_per_m2_asc / price_per_m2_desc: average price per m²; price_asc / price_desc: average price; name: alphabetical. Entries without an average come last. | |
| limit | No | Most investments in the result, 1–30, default 10 (about 550–750 characters each with links). | |
| developer_slug | No | developer_slug from deweloperuch_search_developers or from results of the investment tools, e.g. atal. Only with city. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a read-only, open-world tool, and the description adds substantial operational context beyond them: polite one-request-at-a-time querying, caching, STOP-error handling, and what happens when market data is temporarily unavailable. It also explains the result shape, truncation fields, and sort behavior for entries lacking averages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is front-loaded with purpose, modes, and usage, and most of its length is justified by the tool's complexity and the need to prevent mixing asking prices with RCN transaction prices. It is dense and somewhat repetitive in places, but the structure remains navigable and no major section is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the five parameters, multiple search modes, absence of an output schema, and the risk of confusing this tool with pricing/transaction siblings, the description is complete. It covers return shape, field meanings, mode-dependent behavior, error handling, and cross-tool boundaries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the schema already documents city, name, sort, limit, and developer_slug in detail. The description reinforces the city-versus-name-only distinction and notes that name and developer_slug narrow the list, but it does not add much parameter-specific detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Search investments (developer projects, primary market)') and immediately defines two modes: city search with full data versus name-only search across Poland. It clearly distinguishes this from siblings such as deweloperuch_get_investment and deweloperuch_get_offer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use examples (cheapest per m² in a city, investments of one developer, finding a slug by name) and names alternatives for excluded cases: offer details go to deweloperuch_get_investment, price history to deweloperuch_get_offer, and price/area ranges to deweloperuch_get_market_statistics. It also warns that city=polska does not work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deweloperuch_search_locationsSearch locationsARead-onlyInspect
Find cities, districts and streets in Poland by a fragment of the name. Use it first, to turn a place name into the city_slug the other deweloperuch_* tools take (and the lat/lng of a street or district for deweloperuch_estimate_property_value — an approximate point, not a particular building). Returns no prices. A locality with offer_count 0 has no developer offers. Costs two requests to deweloperuch.pl. deweloperuch.pl is a free community project queried politely (one request at a time, results cached): if a result is an error starting with STOP, stop using the deweloperuch_* tools, retry nothing, look for no workaround and tell the user that market data is temporarily unavailable. Result shape: { total: number | null, returned, truncated, hint?, items: [{ kind: 'city' | 'district' | 'street', name, city, city_slug, district?, street?, lat?, lng?, offer_count? }] } — the list key is items. total is null when more match than shown (truncated=true: refine the name). offer_count is the site's count of developer offers (exact for districts, approximate for streets and cities). A district or street carries the city_slug of its city (this server's tools have no district filter). Nothing matching is not an error: returned=0 with a hint.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Fragment of a city, district or street name, 2–100 characters, Polish characters allowed, e.g. Kraków, Mokotów. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/openWorld, but the description adds cost ('Costs two requests to deweloperuch.pl'), throttling and caching behavior, a precise STOP-error protocol with explicit instructions to retry nothing and find no workaround, and the fact that no prices are returned. This is operationally significant context that annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and the 'use it first' instruction, then grouped into cost/behavior, result shape, and edge cases. The result-shape block is long, but with no output schema it is load-bearing rather than filler; the only marginal sentence is 'Returns no prices', which is still a useful exclusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully specifies the return shape including the `items` key, the total/returned/truncated/hint fields, per-item kind/name/city_slug/lat/lng/offer_count, and the exact-vs-approximate caveat on offer_count. Combined with the error protocol and rate-limit notes, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already specifies the 2–100 character constraint and Polish character support, so the description does not need to carry parameter burden. It still adds genuine meaning by characterizing the input as a name fragment and explaining that the resulting slug is the key other tools consume. No syntax or format gap remains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource set ('Find cities, districts and streets in Poland by a fragment of the name') and immediately differentiates itself from siblings by stating it is the entry point that produces city_slug for the other deweloperuch_* tools. It also carves out a distinct secondary consumer (lat/lng for deweloperuch_estimate_property_value), so an agent can place it in the tool graph 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit ordering guidance ('Use it first, to turn a place name into the city_slug the other deweloperuch_* tools take') and names the sibling that consumes the coordinates. It also handles the negative case — 'Nothing matching is not an error: returned=0 with a hint' and 'A locality with offer_count 0 has no developer offers' — preempting the two most likely misuse paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
10 tool updates
- First observed
deweloperuch_estimate_property_value - First observed
deweloperuch_get_building - First observed
deweloperuch_get_investment - First observed
deweloperuch_get_market_statistics - First observed
deweloperuch_get_offer - First observed
deweloperuch_get_transaction_statistics - First observed
deweloperuch_rank_locations - First observed
deweloperuch_search_developers - First observed
deweloperuch_search_investments - First observed
deweloperuch_search_locations
Related MCP Connectors
Polish real-estate prices from notarial deeds: area stats, plot and building reports, valuations.
Polish property on Gratka.pl/Morizon.pl (one database): flats, houses, plots, premises, buy or rent.
41Polish real-estate deed prices and parcel checks: zoning plan, utilities, flood risk
Polish real estate for AI: 8M+ deed transaction prices (RCN) + per-parcel context by cadastral ID
Related MCP Servers
AlicenseAqualityAmaintenance7M+ real estate transactions from Poland's RCN registry. Search, compare, and analyze prices30105 npm1MIT- AlicenseAqualityBmaintenanceEnables AI assistants to query real Polish real-estate transaction prices for flats, houses, and building plots from the official notarial registry. It returns median price per square meter, price ranges, room breakdowns, market type, yearly trends, and recent sales within a radius of any Polish address, street, town, or coordinates.4569 npmMIT
- AlicenseAqualityAmaintenanceEnables AI assistants to query Polish new-build housing data: developers' asking prices with price history, real transaction prices from the RCN register, and GUS/NBP market statistics, plus searchable locations, offers, investments and developers. Exposes thirteen read-only tools over the public deweloperuch.pl data, usable from any MCP client or the bundled CLI.1384 PyPI29MIT
- AlicenseAqualityDmaintenanceEnables searching Polish administrative areas and retrieving real estate transaction data from the official registry via geoportal.gov.pl.31GPL 3.0
Glama MCP Gateway
Add one secure layer between your agents and this server.