@cenogram/mcp-server 0.5.0 → 0.11.0

package/dist/tools.js

@@ -1,11 +1,11 @@
 import { Sentry } from "./sentry.js";
 import { z } from "zod";
-import { getStats, getTransactions, getPricePerM2, getDistricts, getLocations, getPriceHistogram, getTransactionsSummary, searchParcels, resolveParcel, getParcelReport, searchByPolygon, compareLocations, getRentalYield, getRentalYieldLocations, getPriceSpread, getPriceSpreadLocations, getValuation, getBuildingBreakdown, getTransactionFlood, getTransactionHeritage, getTransactionLandslide, getTransactionSurroundings, getTransactionTransit, getTransactionPermits, getTransactionPlanning, getTransactionFarmland, getDemographics, getInfrastructureSignals, decodeOAuthCtx, OAUTH_CTX_PREFIX, } from "./api-client.js";
+import { getStats, getTransactions, getPricePerM2, getDistricts, getLocations, searchLocations, getPriceHistogram, getTransactionsSummary, searchParcels, resolveParcel, listParcels, getParcelsMap, searchParcelsByPolygon, getParcelReport, getParcelLandClass, searchByPolygon, compareLocations, getRentalYield, getRentalYieldLocations, getPriceSpread, getPriceSpreadLocations, getFloodRisk, getFloodRiskLocations, getValuation, getBuildingBreakdown, getTransactionFlood, getTransactionHeritage, getTransactionLandslide, getTransactionNature, getTransactionSubsurface, getTransactionSurroundings, getTransactionRoads, getTransactionTransit, getTransactionPermits, getTransactionPlanning, getTransactionFarmland, getDemographics, getInfrastructureSignals, decodeOAuthCtx, isExpectedApiError, OAUTH_CTX_PREFIX, } from "./api-client.js";
 import { signupUrl } from "./error-messages.js";
 import { channelSrc, isHttpMode } from "./transport-mode.js";
 import { sanitizeForLog } from "./auth-dispatch.js";
-import { formatTransactionList, formatMarketOverview, formatPriceStats, formatHistogram, formatParcelResults, formatParcelResolve, formatParcelReport, formatSpatialResults, formatCompareResults, formatLocationHierarchy, formatRentalYield, formatRentalYieldLocations, formatPriceSpread, formatPriceSpreadLocations, formatValuation, formatBuildingBreakdown, formatFloodBreakdown, formatHeritageBreakdown, formatLandslideBreakdown, formatSurroundings, formatTransitBreakdown, formatPermitsBreakdown, formatPlanningBreakdown, formatFarmland, formatDemographics, formatInfrastructureSignals, MARKET_CAVEAT, } from "./formatters.js";
-import { mapPropertyType, mapMarketType, mapUnitFunction, mapBuildingType, mapOwnershipTypes, mapTransactionTypes, radiusKmToBbox, filterByLocation, resolveDistrict, tryResolveCityKey, } from "./mappings.js";
+import { formatTransactionList, formatMarketOverview, formatPriceStats, formatHistogram, formatParcelResults, formatParcelResolve, formatParcelList, formatParcelFeatures, formatParcelReport, formatParcelLandClass, formatSpatialResults, formatCompareResults, formatLocationHierarchy, formatLocationSearch, formatRentalYield, formatRentalYieldLocations, formatPriceSpread, formatPriceSpreadLocations, formatFloodRisk, formatFloodRiskLocations, formatValuation, formatBuildingBreakdown, formatFloodBreakdown, formatHeritageBreakdown, formatLandslideBreakdown, formatNatureBreakdown, formatSubsurfaceBreakdown, formatSurroundings, formatRoads, formatTransitBreakdown, formatPermitsBreakdown, formatPlanningBreakdown, formatFarmland, formatDemographics, formatInfrastructureSignals, MARKET_CAVEAT, } from "./formatters.js";
+import { mapPropertyType, mapMarketType, mapUnitFunction, mapBuildingType, mapOwnershipTypes, mapTransactionTypes, radiusKmToBbox, filterByLocation, resolveDistrict, tryResolveCityKey, stripDiacritics, } from "./mappings.js";
 function sanitizeInput(s, maxLen = 50) {
     return s.replace(/[<>]/g, "").slice(0, maxLen);
 }
@@ -52,7 +52,9 @@ async function withErrorHandling(toolName, apiKey, fn) {
         }
         catch (error) {
             success = false;
-            Sentry.captureException(error, { tags: { tool: toolName, error_layer: "tool_execution" } });
+            if (!isExpectedApiError(error)) {
+                Sentry.captureException(error, { tags: { tool: toolName, error_layer: "tool_execution" } });
+            }
             const message = error instanceof Error ? error.message : String(error);
             return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
         }
@@ -72,16 +74,27 @@ async function withErrorHandling(toolName, apiKey, fn) {
 export function experimentalToolsEnabled() {
     return process.env.CENOGRAM_EXPERIMENTAL_TOOLS === "1";
 }
+const landUseParam = z.array(z.enum([
+    "gruntyZabudowaneIZurbanizowane",
+    "gruntyRolne",
+    "gruntyLesne",
+    "terenyKomunikacyjne",
+    "inne",
+    "unknown",
+])).optional().describe("Recorded land-use category of the transaction's land. Multi-select from: gruntyZabudowaneIZurbanizowane (built-up and urbanised), gruntyRolne (agricultural), gruntyLesne (forest), terenyKomunikacyjne (transport), inne (other). 'unknown' = no category recorded for the land (NULL) — a legitimate bucket, never a claim that the land has no use. Values are case-sensitive. E.g. ['gruntyRolne'] for farmland, or ['gruntyZabudowaneIZurbanizowane','gruntyRolne'] to compare developed vs farmland.");
+const buildingStoreysParam = z.array(z.string().regex(/^(\d+|\d+plus|unknown)$/i, "Invalid buildingStoreys token - use a non-negative integer (e.g. '1','2'), 'Nplus' (e.g. '3plus'), or 'unknown'.")).optional().describe("Number of above-ground storeys of the building. Multi-select buckets: exact non-negative integers (e.g. '1','2'), 'Nplus' e.g. '3plus' = 3 or more, 'unknown' = no storey count recorded (NULL). Recorded ONLY for single-building transactions, so 'unknown' covers BOTH a deed with several buildings (no single storey count exists) and a single building with missing data — never read it as 'a building with no storeys'. This is NOT the floor of a unit (see floor). Without 'unknown', rows with no storey count are excluded.");
+const minFootprintAreaParam = z.number().optional().describe("Minimum building footprint (ground-plan) area in m², summed over all buildings of the transaction. Distinct from minArea, which measures usable floor area (units) or land/parcel area. Set only where every linked building has footprint data, so this bound selects only measured rows — absence means 'not measured', not 'no building'.");
+const maxFootprintAreaParam = z.number().optional().describe("Maximum building footprint (ground-plan) area in m², summed over all buildings of the transaction. Distinct from maxArea, which measures usable floor area (units) or land/parcel area. Set only where every linked building has footprint data, so this bound selects only measured rows — absence means 'not measured', not 'no building'.");
 export function registerTools(server, apiKey) {
     server.tool("search_transactions", `Search Polish real estate transactions from the national RCN registry (8M+ records).
 Returns transaction details: address, date, price, area, price/m², property type.
-Use list_locations first to find valid location names.
+Call list_locations(search=...) first to resolve a place: prefer the returned TERYT code as teryt= (exact administrative match). Pass a name to location= only when the result flags it as an RCN district (rcn_district) — most TERYT names are not valid location= values and silently return zero rows.
 Example: search for apartments in Mokotów sold in 2024 above 500,000 PLN.
 Data notes: marketType is NULL for ~55% of records (notary didn't classify) - filtering by marketType excludes them. ~1.7% of records have no transaction_date.
 Permalink: every result is shareable on the map. From a result's "id:" line and its "Location: <A>°N, <B>°E" line, build https://cenogram.pl/ceny-transakcyjne?src=${channelSrc()}#v=1&lat=<A>&lng=<B>&z=16&tx=<id> (drop the °N/°E; lat = the °N number, lng = the °E number) — opens that exact transaction on the map. Omit &tx=<id> for the area only.
 Field provenance: values are from the notarial deed (RCN) by default; computed values (parcel area summed across plots or converted from hectares, an inferred/reclassified property type) and approximated streets are flagged inline with a neutral [...] note.
 Location matches TERYT districts only - for neighborhoods (osiedla), use search_by_area instead.`, {
-        location: z.string().optional().describe("Location name - city (e.g. 'Warszawa', 'Kraków', 'Gdańsk') or district (e.g. 'Mokotów', 'Kraków-Podgórze'). 'Warszawa', 'Kraków', 'Łódź' auto-expand to all sub-districts. Use list_locations to find valid names."),
+        location: z.string().optional().describe("Location name - city (e.g. 'Warszawa', 'Kraków', 'Gdańsk') or district (e.g. 'Mokotów', 'Kraków-Podgórze'). 'Warszawa', 'Kraków', 'Łódź' auto-expand to all sub-districts. Prefer teryt= for exact matches; call list_locations(search=...) to confirm a name is valid here — it flags valid ones as rcn_district."),
         teryt: z.string().min(1).optional().describe("TERYT administrative code(s) for precise area filtering. Comma-separated, max 10. 2-digit (voivodeship), 4-digit (county), 6-digit (municipality), or full precinct code (e.g. '321705_2.0054'). Use list_locations to find codes. More precise than 'location' - avoids name ambiguity."),
         propertyType: z.enum(["land", "building", "developed_land", "unit"]).optional()
             .describe("Property type filter"),
@@ -111,11 +124,15 @@ Location matches TERYT districts only - for neighborhoods (osiedla), use search_
         maxPrice: z.number().optional().describe("Maximum price in PLN"),
         dateFrom: z.string().optional().describe("Start date (YYYY-MM-DD)"),
         dateTo: z.string().optional().describe("End date (YYYY-MM-DD)"),
-        street: z.string().optional().describe("Street name filter (partial match, e.g. 'Puławska', 'Trakt Lubelski')"),
+        street: z.string().optional().describe("Street name filter, matched anywhere inside the name (e.g. 'Puławska', 'Trakt Lubelski'). Give it in the NOMINATIVE and with its Polish diacritics — matching is literal, so 'Karmelickiej' does not find 'Karmelicka' and 'Marszalkowska' does not find 'Marszałkowska'. Either mistake answers with nothing, which reads exactly like 'no such transactions'."),
         buildingNumber: z.string().optional().describe("Building/house number (e.g. '251C', '12A'). Requires location or street to be set."),
         parcelId: z.string().optional().describe("Exact parcel ID as returned in search results (e.g. '146518_8.0108.27'). Must match exactly - copy from a previous search result's parcel_id field."),
         minArea: z.number().optional().describe("Minimum area in m²"),
         maxArea: z.number().optional().describe("Maximum area in m²"),
+        landUse: landUseParam,
+        buildingStoreys: buildingStoreysParam,
+        minFootprintArea: minFootprintAreaParam,
+        maxFootprintArea: maxFootprintAreaParam,
         limit: z.number().min(1).max(50).default(10)
             .describe("Number of results (1-50, default 10)"),
         sort: z.enum(["price", "date", "area", "pricePerM2", "district", "rooms", "floor"]).default("date")
@@ -163,6 +180,10 @@ Location matches TERYT districts only - for neighborhoods (osiedla), use search_
             parcelId: params.parcelId,
             minArea: params.minArea,
             maxArea: params.maxArea,
+            landUse: params.landUse?.join(","),
+            buildingStoreys: params.buildingStoreys?.join(","),
+            minFootprintArea: params.minFootprintArea,
+            maxFootprintArea: params.maxFootprintArea,
             limit: params.limit,
             sort: params.sort,
             order: params.order ?? "desc",
@@ -218,6 +239,7 @@ ${MARKET_CAVEAT}`, {
         return textResponse(formatHistogram(bins) + formatCreditFooter(creditInfo));
     }));
     server.tool("search_by_area", `Search real estate transactions within a geographic radius.
+Returns TRANSACTIONS — deeds and prices — despite the name. For the land plots themselves in an area, use list_parcels_in_area.
 Best tool for neighborhood/osiedle searches (neighborhoods are not TERYT districts).
 Radius guide: 0.3-0.5 km for a street, 0.5-1 km for a neighborhood, 2-5 km for a city area.
 Example: apartments in Wrocław's Nowy Dwór (lat 51.143, lng 16.993, radiusKm=0.7).
@@ -260,6 +282,10 @@ Field provenance: values are from the notarial deed (RCN) by default; computed v
             .describe("Heritage-listing filter. listed = a protected monument on/at the property's land; zone = the land lies within a protected urban layout or the designated surroundings of a monument. Selects ONLY transactions where a listing was detected; absence of a detection is never asserted as 'not listed'. Multi-select; e.g. ['listed'] = individually listed properties only."),
         landslideRisk: z.array(z.enum(["landslide", "threatened"])).optional()
             .describe("Landslide-hazard filter, from official landslide-hazard maps (1:10,000 scale). 'landslide' = the land intersects a mapped landslide area; 'threatened' = an area threatened by mass movements. Selects ONLY transactions whose land intersects a mapped hazard area — an intersection means overlap with a mapped area, not that the parcel itself is a landslide; absence of a zone is never asserted as 'safe'. Multi-select; e.g. ['landslide','threatened'] = any mapped hazard."),
+        landUse: landUseParam,
+        buildingStoreys: buildingStoreysParam,
+        minFootprintArea: minFootprintAreaParam,
+        maxFootprintArea: maxFootprintAreaParam,
         limit: z.number().min(1).max(50).default(20)
             .describe("Number of results (1-50, default 20)"),
     }, { readOnlyHint: true, destructiveHint: false, title: "Search Transactions by Radius" }, async (params) => withErrorHandling("search_by_area", apiKey, async () => {
@@ -282,6 +308,10 @@ Field provenance: values are from the notarial deed (RCN) by default; computed v
             maxPrice: params.maxPrice,
             minArea: params.minArea,
             maxArea: params.maxArea,
+            landUse: params.landUse?.join(","),
+            buildingStoreys: params.buildingStoreys?.join(","),
+            minFootprintArea: params.minFootprintArea,
+            maxFootprintArea: params.maxFootprintArea,
             dateFrom: params.dateFrom,
             dateTo: params.dateTo,
             limit: params.limit,
@@ -306,11 +336,12 @@ ${MARKET_CAVEAT}`, {}, { readOnlyHint: true, destructiveHint: false, title: "Mar
 1. TERYT hierarchy (parent param): Navigate voivodeship → county → municipality → precinct. Returns TERYT codes for use in search_transactions(teryt=...).
    - No parent: 16 voivodeships (2-digit codes)
    - 2-digit: counties (4-digit), 4-digit: municipalities (6-digit), 6-digit: precincts
-2. Name search (search param): Find districts by name (flat list, legacy).
+2. Name search (search param): Look up a place by name across all levels (voivodeship, county, municipality, precinct). Each match comes with its TERYT code, its parent unit, and the exact follow-up calls to make — use teryt= for precise administrative filtering. Rows also flagged as RCN districts additionally accept the name in search_transactions(location=)/compare_locations. RCN district names that have no TERYT code are listed separately.
 If both provided, parent takes precedence.
+Returns administrative units — never streets. A street is not a level of this hierarchy and has no code of its own; to search for parcels on one, pass the name straight to list_parcels_in_area as street=.
 Use 'location' for quick city searches, 'teryt' for precise administrative filtering (avoids name ambiguity, e.g. 'Wałcz' is both a county and a municipality).`, {
         parent: z.string().min(1).optional().describe("TERYT parent code to browse children. 2-digit (voivodeship → counties), 4-digit (county → municipalities), 6-digit (municipality → precincts). Omit for all voivodeships."),
-        search: z.string().min(1).optional().describe("Filter locations by name (case-insensitive partial match, e.g. 'Krak' for Kraków districts). Ignored when parent is set."),
+        search: z.string().min(1).optional().describe("Look up a place by name (case-insensitive, diacritics-insensitive partial match, e.g. 'wejher' for Wejherowo). Returns TERYT codes plus, where applicable, RCN district names. Ignored when parent is set."),
     }, { readOnlyHint: true, destructiveHint: false, title: "List Locations & TERYT Codes" }, async (params) => withErrorHandling("list_locations", apiKey, async () => {
         requireApiKey(apiKey);
         if (params.parent !== undefined) {
@@ -326,38 +357,67 @@ Use 'location' for quick city searches, 'teryt' for precise administrative filte
             const { data: locations, creditInfo } = await getLocations(undefined, apiKey);
             return textResponse(formatLocationHierarchy(locations) + formatCreditFooter(creditInfo));
         }
-        let districts;
-        let creditInfo;
-        const city = tryResolveCityKey(params.search);
+        const query = params.search;
+        let rcnDistricts;
+        let rcnCreditInfo;
+        const city = tryResolveCityKey(query);
         if (city) {
-            districts = city;
-            creditInfo = null;
+            rcnDistricts = city;
+            rcnCreditInfo = null;
         }
         else {
             const res = await getDistricts(apiKey);
-            creditInfo = res.creditInfo;
-            districts = filterByLocation(params.search, res.data);
+            rcnCreditInfo = res.creditInfo;
+            rcnDistricts = filterByLocation(query, res.data);
         }
-        if (districts.length === 0) {
-            const msg = params.search
-                ? `No locations found matching "${params.search}".`
-                : "No locations available.";
-            return textResponse(msg + formatCreditFooter(creditInfo));
+        let terytItems = [];
+        let terytCreditInfo = null;
+        if (wordCharCount(query) >= TERYT_SEARCH_MIN_WORD_CHARS) {
+            try {
+                const res = await searchLocations(query, apiKey);
+                terytItems = res.data;
+                terytCreditInfo = res.creditInfo;
+            }
+            catch {
+                terytItems = [];
+                terytCreditInfo = null;
+            }
         }
-        const lines = [`Found ${districts.length} locations:\n`];
-        const shown = params.search ? districts : districts.slice(0, 50);
-        for (const d of shown) {
-            lines.push(`  - ${d}`);
+        if (city && terytItems.length > 0) {
+            const cityNorm = stripDiacritics(query.trim().toLowerCase());
+            const countyRow = terytItems.find((it) => it.level === "county" && stripDiacritics(it.name.toLowerCase()) === cityNorm);
+            if (countyRow) {
+                try {
+                    const { data: children } = await getLocations(countyRow.code, apiKey);
+                    const rcnNorms = new Set(rcnDistricts.map((d) => stripDiacritics(d.toLowerCase())));
+                    const present = new Set(terytItems.map((it) => stripDiacritics(it.name.toLowerCase())));
+                    for (const child of children) {
+                        const childNorm = stripDiacritics(child.name.toLowerCase());
+                        if (rcnNorms.has(childNorm) && !present.has(childNorm)) {
+                            terytItems.push({ ...child, rcn_district: true });
+                            present.add(childNorm);
+                        }
+                    }
+                }
+                catch {
+                }
+            }
         }
-        if (!params.search && districts.length > 50) {
-            lines.push(`\n...and ${districts.length - 50} more. Use search parameter to filter.`);
+        const terytNames = new Set(terytItems.map((it) => stripDiacritics(it.name.toLowerCase())));
+        const rcnOnly = rcnDistricts.filter((d) => !terytNames.has(stripDiacritics(d.toLowerCase())));
+        const creditInfo = terytCreditInfo ?? rcnCreditInfo;
+        if (terytItems.length === 0 && rcnOnly.length === 0) {
+            return textResponse(`No locations found matching "${query}".` + formatCreditFooter(creditInfo));
         }
-        return textResponse(lines.join("\n") + formatCreditFooter(creditInfo));
+        return textResponse(formatLocationSearch(terytItems, rcnOnly, query) + formatCreditFooter(creditInfo));
     }));
     server.tool("search_parcels", `Search for land parcels by parcel ID prefix (autocomplete).
+Matches on the ID PREFIX only, never on an area: to list the parcels in a place or a shape use list_parcels_in_area, and to turn an address, a coordinate or 'locality + number' into one parcel use resolve_parcel.
 Returns matching parcels with their district, area, and GPS coordinates.
 Useful for finding exact parcel IDs, then searching transactions nearby.
-Example: search for parcels starting with '146518_8.01'.`, {
+Example: search for parcels starting with '146518_8.01'.
+Coverage: this searches the cadastral register we hold — near-complete national coverage, though not the whole of it and not live — so an empty result more likely means a recent change or a mistyped prefix than that no such parcel exists. Do not report a missing match as "this parcel does not exist". The answer carries a corpus_coverage block with the measured figures for the county the prefix names, and resolve_parcel with the FULL id can still confirm and add a parcel we do not yet hold.
+Free: searching for parcels costs no API tokens.`, {
         q: z.string().min(3).describe("Parcel ID prefix to search for (min 3 chars). E.g. '146518_8.01'"),
         limit: z.number().min(1).max(10).default(10).optional()
             .describe("Max results (1-10, default 10)"),
@@ -368,12 +428,12 @@ Example: search for parcels starting with '146518_8.01'.`, {
     }));
     server.tool("resolve_parcel", `Resolve a land parcel to its cadastral identity using exactly ONE of:
 - parcelId: a full cadastral id, either raw '/' form ('142907_2.0014.342/5') or URL-safe '-' form ('142907_2.0014.342-5'), or the internal UUID from search results.
-- q: a full cadastral id, a UUID, OR free-text 'locality name + parcel number' (e.g. 'Sabnie 342/5'). Name matching is exact on the locality (case-insensitive) — an unusual spelling may miss.
+- q: a full cadastral id, a UUID, OR free-text 'locality name + parcel number' (e.g. 'Sabnie 342/5'). The name may be a gmina name or a cadastral precinct (obręb) name; matching is exact and case-insensitive, so an unusual spelling may miss. A precinct name is not unique nationwide, so an ambiguous name comes back as several candidates rather than a guess. This is NOT a street address: it is a locality name plus a PARCEL number, never a street name plus a building number. For a city address (street + building number) use list_parcels_in_area(street=, buildingNumber=) instead — resolve_parcel will not turn 'Marszałkowska 12' into a parcel.
 - lat & lng: a WGS84 point inside the parcel (returns the parcel(s) containing that point).
-Returns a list of matching parcels with district, area, and coordinates; 'truncated' when the name+number match was capped. When nothing matches, coverage is not_covered and the credit is refunded.
+Returns a list of matching parcels with district, area, and coordinates; 'truncated' when the name+number match was capped. When nothing matches, coverage is not_covered — and what that means depends on the mode. With a FULL cadastral id we confirm the parcel live and add it if it exists, so not_covered there really does mean we could not confirm one. With the DISCOVERY modes (locality name + number, or a coordinate) we only look at the register we hold — near-complete national coverage, though not the whole of it and not live — so not_covered means "not among the parcels we hold", which is a weaker statement, and a fresh change or an unusual spelling is a likelier cause than the parcel not existing. Never report it as "no such parcel". The corpus_coverage block in each answer says how much of the register was actually searched. When the lookup could not be completed at all — a live confirmation that failed, or a name carried by more precincts than one search covers and nothing found among them — coverage is not_computed instead: that is not a statement that the parcel does not exist. Matches found before such a search ran out are returned normally, with 'truncated'.
 Use this to turn an address point, a coordinate, or a locality+number into a concrete parcel id — then feed that id to search_transactions (parcelId) to see its sale history.
-Costs 1 API token (refunded when nothing matches).`, {
-        q: z.string().max(200).optional().describe("Full cadastral id, a UUID, or 'locality name + parcel number' (e.g. 'Sabnie 342/5'). Mutually exclusive with parcelId and lat/lng."),
+Free: resolving a parcel costs no API tokens.`, {
+        q: z.string().max(200).optional().describe("Full cadastral id, a UUID, or 'locality name + parcel number' (e.g. 'Sabnie 342/5') — the name may be a gmina or a cadastral precinct (obręb). NOT a street address: for a street + building number use list_parcels_in_area instead. Mutually exclusive with parcelId and lat/lng."),
         parcelId: z.string().max(200).optional().describe("Full cadastral id (slash or dash form) or internal UUID. Mutually exclusive with q and lat/lng."),
         lat: z.number().min(-90).max(90).optional().describe("Latitude WGS84. Must be paired with lng. Mutually exclusive with q and parcelId."),
         lng: z.number().min(-180).max(180).optional().describe("Longitude WGS84. Must be paired with lat. Mutually exclusive with q and parcelId."),
@@ -393,18 +453,182 @@ Costs 1 API token (refunded when nothing matches).`, {
         const { data, creditInfo } = await resolveParcel({ q: params.q, parcelId: params.parcelId, lat: params.lat, lng: params.lng }, apiKey);
         return textResponse(formatParcelResolve(data) + formatCreditFooter(creditInfo));
     }));
-    server.tool("get_parcel_report", `The whole dossier for one land parcel in a single call: the parcel core (location, area, land use, plan designation), all nine enrichment layers (flood risk, heritage listing, landslide risk, nuisance surroundings, public-transport access, general-plan zoning, buildings on the parcel, recent building activity, agricultural-land eligibility), the parcel's transaction history (newest first, up to 20), a local price context (median zł/m² for the county and the locality over the last 12 months) and a municipal context (a headline demographic/economic subset plus upcoming-infrastructure signals for the gmina).
+    server.tool("get_parcel_report", `The whole dossier for one land parcel in a single call: the parcel core (location, area, land use, plan designation), all thirteen enrichment layers (flood risk, heritage listing, landslide risk, subsurface: mining terrains and major groundwater reservoirs, nuisance surroundings, public-transport access, general-plan zoning, buildings on the parcel, recent building activity, agricultural-land eligibility, official land-use & soil-quality classification with its re-designation consequences where the county publishes it, nature: nearby forest and protected areas, roads: geometric road-access evidence measured from carriageway centrelines, which is not a determination of legal access), the parcel's transaction history (newest first, up to 20), a local price context (median zł/m² for the county and the locality over the last 12 months) and a municipal context (a headline demographic/economic subset plus upcoming-infrastructure signals for the gmina).
 Address it by a full cadastral id in the natural '/' form ('142907_2.0014.342/5'), the URL-safe '-' form, or the internal UUID from a search or resolve result.
 Each section carries its own state, shown explicitly: covered = a definitive result; covered_no_data = the parcel was checked and nothing was found (still billed); not_covered = outside our data (refunded); not_computed = a live computation could not finish in time (refunded — the rest of the report still returns, so a report can be partial). The two context sections instead use full / low_sample / suppressed / no_data.
+The buildings section additionally reports how many of the buildings could be given a construction-age estimate from building-permit records. That is an ESTIMATE with an interval, never a registry construction date, and the records only start in 2016, so for most buildings the answer is that the year could not be established — which is stated rather than omitted.
 Prefer this over calling the per-layer parcel tools one by one — it is one call at a flat price and never costs more than the sum of its parts. Use resolve_parcel first when you only have an address, a coordinate, or a 'locality + number'.
-Costs 35 API tokens. Billing is by outcome (see the billing line on the response): a parcel that cannot be resolved is fully refunded; a resolved parcel where no layer had data is billed only the core floor (1 token) with the rest refunded; a resolved parcel with at least one covered layer is billed in full.`, {
+Costs 45 API tokens. Billing is by outcome (see the billing line on the response): a parcel that cannot be resolved is fully refunded; a resolved parcel where no layer had data is billed only the core floor (1 token) with the rest refunded; a resolved parcel with at least one covered layer is billed in full.`, {
         parcelId: z.string().min(3).max(200).describe("Full cadastral id ('142907_2.0014.342/5' or the '-' form) or the internal UUID from a search/resolve result."),
     }, { readOnlyHint: true, destructiveHint: false, title: "Get Parcel Report" }, async (params) => withErrorHandling("get_parcel_report", apiKey, async () => {
         requireApiKey(apiKey);
         const { data, creditInfo } = await getParcelReport(params.parcelId, apiKey);
         return textResponse(formatParcelReport(data) + formatCreditFooter(creditInfo));
     }));
+    server.tool("get_parcel_land_class", `The official land-use and soil-quality classification recorded for one land parcel, and what it implies for taking the land out of agricultural use. Returns the land-use categories and the soil-quality grades entered for the parcel, whether any of those grades is in the protected I-III range, whether the parcel lies inside a city's administrative boundary (which changes the rule that applies), and a note on the re-designation consequences with the date the legal state behind it was verified.
+Use it when the question is specifically about the classification or about re-designating farmland. For anything else about the parcel — price history, flood risk, zoning, buildings, permits, surroundings, transport — call get_parcel_report instead: it is one call at a flat price and includes this same classification as one of its sections.
+Address it by a full cadastral id in the natural '/' form ('142907_2.0014.342/5'), the URL-safe '-' form, or the internal UUID from a search or resolve result.
+The categories and grades come back as SETS. The source records no area for any of them, so the answer can never say which category prevails on the parcel or give a share — a parcel listing two categories has both, in unknown proportion.
+This layer answers only where the county publishes the classification; many counties, including several large cities, do not. Four states, told apart explicitly: covered = the county publishes it and the parcel has an entry; covered_no_data = the county publishes it and this parcel has none (a checked negative — still billed); not_covered = the county does not publish it, or we do not hold the parcel (refunded); not_computed = the lookup could not finish in time (refunded — retry).
+Costs 4 API tokens, refunded on not_covered and not_computed. Not legal advice, and never a statement that a parcel can or cannot be built on.`, {
+        parcelId: z.string().min(3).max(200).describe("Full cadastral id ('142907_2.0014.342/5' or the '-' form) or the internal UUID from a search/resolve result."),
+    }, { readOnlyHint: true, destructiveHint: false, title: "Get Parcel Land Classification" }, async (params) => withErrorHandling("get_parcel_land_class", apiKey, async () => {
+        requireApiKey(apiKey);
+        const { data, creditInfo } = await getParcelLandClass(params.parcelId, apiKey);
+        return textResponse(formatParcelLandClass(data) + formatCreditFooter(creditInfo));
+    }));
+    const PARCEL_AREA_MAX_KM2 = 500;
+    const PARCEL_RADIUS_MAX_KM = 12.6;
+    const ADDRESS_FILTER_MIN_TERYT_DIGITS = 4;
+    const STREET_MIN_WORD_CHARS = 3;
+    const TERYT_SEARCH_MIN_WORD_CHARS = 2;
+    const ADDRESS_FILTER_MAX_CHARS = 200;
+    function wordCharCount(s) {
+        return (s.match(/[\p{L}\p{N}]/gu) ?? []).length;
+    }
+    function terytReachesCounty(teryt) {
+        const parts = teryt.split(",").map((p) => p.trim()).filter((p) => p !== "");
+        if (parts.length === 0)
+            return false;
+        return parts.every((p) => p.replace(/\D/g, "").length >= ADDRESS_FILTER_MIN_TERYT_DIGITS);
+    }
+    server.tool("list_parcels_in_area", `List cadastral parcels in an area — the land plots themselves, NOT transactions.
+For deeds and prices in an area use search_by_area or search_by_polygon instead. To look up a parcel by an id prefix use search_parcels; to turn one address, coordinate or 'locality + number' into a parcel use resolve_parcel; for everything known about a single parcel use get_parcel_report.
+
+Name the area in one of five ways — at least one is required:
+- teryt: administrative code prefix at any level (2 digits = voivodeship, 4 = county, 6 = municipality, finer allowed); comma-separate several. Browse codes with list_locations.
+- location: a county or city NAME, resolved to its code. A name shared by two counties comes back as an error listing both, never as a guess.
+- bbox: "minLng,minLat,maxLng,maxLat" in WGS84.
+- lat + lng + radiusKm: a circle (all three together).
+- polygon: a GeoJSON Polygon, for a drawn shape. Pass it on its own.
+A bbox and a circle cannot be combined — together they would mean the overlap of a rectangle and a circle, which is rarely the question.
+
+Two shapes of answer, priced differently:
+- Default: the LIGHT list — parcel id, district and centre point per row, with no outline and no surface. 2 API tokens. Pages by cursor: when more parcels match, the answer hands you an opaque cursor to pass back as cursor=.
+- includeGeometry=true (needs a bbox), or a polygon: OUTLINES — the full GeoJSON polygon of each parcel. 5 API tokens, at most 100 parcels per call (50 by default), no paging.
+
+Truncation is the normal case on outlines, not an edge case. An area the size of a city holds far more parcels than one call returns, so an outline answer is usually marked TRUNCATED and the parcels in it are an arbitrary subset — not the first, nearest or largest. Never report a truncated answer as the parcel list of an area; ask for a smaller area instead.
+
+minArea / maxArea (m²) filter on the registered parcel surface without returning it. They need a narrow scope — a bbox, a circle, a location name, or a teryt of at least 4 digits (county level) — and are refused elsewhere with a message saying what to add. They are not available on the outline calls.
+
+Every row of the light list carries the street address held for that parcel, whether or not you asked about one, and says where it came from: a street on record, or one we worked out for a parcel the record left without a street (shown with a note saying so). A building number is only ever on record, so a worked-out street never carries one. Most rural parcels have no street at all — for those the way in is resolve_parcel with the precinct name and the parcel number, not a street.
+- street: matches the name case-insensitively anywhere inside it, ${STREET_MIN_WORD_CHARS} letters or digits minimum, ${ADDRESS_FILTER_MAX_CHARS} characters maximum. It is a NAME, not a pattern: % and _ match themselves. Both sources are searched at once and a parcel found in both appears once, attributed to the record. Matching is case- and accent-insensitive, so 'karmelicka' and 'Karmelicką' both find 'Karmelicka' — but it does NOT inflect: pass the name in the NOMINATIVE, because an inflected form like 'Karmelickiej' answers with an empty list. That empty page costs nothing (the tokens are refunded) and carries a suggestions block with close names to retry, so read the suggestions before you conclude anything about the data.
+- buildingNumber: matches EXACTLY ('12A' does not find '12a') and needs street alongside it. RCN often records a compound or split number ('84/92'), so an exact '84' will not find '84/92' — when a plain number comes back empty on a street that exists, that page costs nothing (the tokens are refunded) and lists the numbers held on the street as suggestions to retry. Because a number is only ever on record, a call carrying one answers only with parcels whose street is on record.
+Both need a narrow scope for the same reason minArea does — a bbox, a circle, a teryt of at least 4 digits, or a location name — and neither counts as naming the area: a common street name across the country is a national search, not a question. Neither is available on the outline calls.
+
+Parcel identity is gated: parcel_id comes back for API-token / OAuth callers and for paid or active-trial accounts, and is withheld for everyone else while the location and the outline still come back.
+
+Coverage, so you can allow for it — TWO SEPARATE GAPS:
+1. We hold near-complete coverage of the cadastral register, though not the whole of it and not live: what we hold was measured county by county on a fixed date, so a freshly split, merged or renumbered parcel may not be in yet. This applies to EVERY entrance here, teryt and location included. A short list, and the absence of a truncation marker, mean only that nothing further matched what we hold as of that measurement — never that you have every parcel in the area. Each answer carries a corpus_coverage block: for teryt and location it gives the measured parcels-held and parcels-in-register figures for the counties you asked about; for bbox, circle and polygon those figures are null, because sizing an arbitrary shape needs county boundaries we do not have — the measurement still applies, we just cannot put a number on it for that shape.
+2. Separately, the spatial entrances (bbox, circle, polygon) work off the stored outline, and a small share of the parcels we DO hold keep theirs in a coordinate system those queries cannot read — those are missing from spatial answers specifically. The teryt and location entrances never touch geometry and are unaffected BY THAT SECOND GAP; a parcel whose outline we do not hold shows up there with no location.
+Neither gap is a reason to distrust what comes back: a returned parcel is a real parcel. They are a reason never to read an empty or short answer as evidence that the land is not there.
+
+Limits: an area over ${PARCEL_AREA_MAX_KM2} km², a radius over ${PARCEL_RADIUS_MAX_KM} km (the same ground) or a polygon over 500 vertices is refused rather than scanned, and a query that outruns its time limit answers with an error asking you to narrow it.`, {
+        teryt: z.string().max(200).optional().describe("TERYT administrative code prefix (2/4/6 digits or finer), comma-separated for several. Wins over location when both are given."),
+        location: z.string().max(200).optional().describe("County, city, or district name, resolved to its TERYT code. A Warszawa district name (e.g. 'Mokotów') narrows to that district; another city's delegatura (e.g. 'Kraków-Podgórze') resolves to its parent county. An ambiguous name is an error listing the candidates."),
+        bbox: z.string().max(200).optional().describe(`Bounding box in WGS84 as "minLng,minLat,maxLng,maxLat", covering at most ${PARCEL_AREA_MAX_KM2} km². Required for includeGeometry=true.`),
+        lat: z.number().min(-90).max(90).optional().describe("Latitude of the circle centre (WGS84). Requires lng and radiusKm."),
+        lng: z.number().min(-180).max(180).optional().describe("Longitude of the circle centre (WGS84). Requires lat and radiusKm."),
+        radiusKm: z.number().positive().max(PARCEL_RADIUS_MAX_KM).optional().describe(`Circle radius in km (max ${PARCEL_RADIUS_MAX_KM} — the radius covering the ${PARCEL_AREA_MAX_KM2} km² ceiling). Requires lat and lng.`),
+        polygon: z.object({
+            type: z.literal("Polygon"),
+            coordinates: z.array(z.array(z.array(z.number()))).min(1),
+        }).refine((poly) => poly.coordinates.reduce((sum, ring) => sum + ring.length, 0) <= 500, { message: "polygon exceeds 500 total vertices (sum across all rings)" }).optional().describe("GeoJSON Polygon geometry. Coordinates: [longitude, latitude] pairs, first and last point identical, at most 500 vertices. Always returns outlines. Pass it instead of the other area parameters, not alongside them."),
+        minArea: z.number().positive().optional().describe("Minimum parcel surface in m². Needs a bbox, a circle, a location name, or a teryt of at least 4 digits. Not available with includeGeometry or a polygon."),
+        maxArea: z.number().positive().optional().describe("Maximum parcel surface in m². Same scope requirement as minArea."),
+        street: z.string().max(ADDRESS_FILTER_MAX_CHARS).optional().describe(`Street name, matched case-insensitively anywhere inside the name (min ${STREET_MIN_WORD_CHARS} letters or digits). A name, not a pattern — % and _ match themselves. NOMINATIVE and with Polish diacritics: 'Karmelickiej' and 'Marszalkowska' both answer empty. Needs a bbox, a circle, a location name, or a teryt of at least ${ADDRESS_FILTER_MIN_TERYT_DIGITS} digits. Not available with includeGeometry or a polygon.`),
+        buildingNumber: z.string().max(ADDRESS_FILTER_MAX_CHARS).optional().describe("Building number, matched exactly ('12A' does not find '12a'). RCN numbering is often compound ('84/92'), so an exact '84' misses '84/92' — if a plain number answers empty, drop it and read the numbers off the street's rows. Requires street, and answers only with parcels whose street is on record. Same scope requirement as street."),
+        includeGeometry: z.boolean().optional().describe("Return each parcel's full outline instead of the light row (5 tokens instead of 2, at most 100 parcels, no paging). Requires a bbox; with a polygon the outlines come back anyway."),
+        limit: z.number().min(1).max(1000).optional().describe("Max parcels returned. Light list: up to 1000, default 250. Outlines: up to 100, default 50 — a larger value is clamped there."),
+        cursor: z.string().max(500).optional().describe("Opaque cursor from the previous light-list answer, to get the next page. Pass it back unchanged; it is not available on outline calls."),
+    }, { readOnlyHint: true, destructiveHint: false, title: "List Parcels in an Area" }, async (params) => withErrorHandling("list_parcels_in_area", apiKey, async () => {
+        requireApiKey(apiKey);
+        const hasTeryt = params.teryt != null && params.teryt !== "";
+        const hasLocation = params.location != null && params.location !== "";
+        const hasBbox = params.bbox != null && params.bbox !== "";
+        const circleParts = [params.lat, params.lng, params.radiusKm].filter((v) => v != null).length;
+        const hasPolygon = params.polygon != null;
+        const hasAreaFilter = params.minArea != null || params.maxArea != null;
+        const hasCursor = params.cursor != null && params.cursor !== "";
+        const street = params.street != null && params.street !== "" ? params.street : undefined;
+        const buildingNumber = params.buildingNumber != null && params.buildingNumber !== "" ? params.buildingNumber : undefined;
+        const hasAddressFilter = street !== undefined || buildingNumber !== undefined;
+        if (!hasTeryt && !hasLocation && !hasBbox && circleParts === 0 && !hasPolygon) {
+            return textResponse("Name the area first: pass teryt, location, bbox, lat+lng+radiusKm, or polygon. Listing every parcel in the country is not something this tool does.");
+        }
+        if (hasPolygon && (hasTeryt || hasLocation || hasBbox || circleParts > 0)) {
+            return textResponse("A polygon already describes the area. Pass it on its own, or drop it and use teryt / location / bbox / lat+lng+radiusKm instead.");
+        }
+        if (hasBbox && circleParts > 0) {
+            return textResponse("Pick one shape for the area: a bbox or a lat+lng+radiusKm circle. Passing both asks for the overlap of a rectangle and a circle.");
+        }
+        if (circleParts > 0 && circleParts < 3) {
+            return textResponse("lat, lng and radiusKm must be given together — a circle needs a centre and a radius.");
+        }
+        if (params.includeGeometry === false && hasPolygon) {
+            return textResponse("A polygon search always returns outlines. Drop includeGeometry=false, or use a bbox if you want the light list instead.");
+        }
+        const wantsOutlines = hasPolygon || params.includeGeometry === true;
+        if (params.includeGeometry === true && !hasBbox && !hasPolygon) {
+            return textResponse("Outlines are returned for a bbox or a polygon. With teryt, location or a circle, drop includeGeometry to get the light list, then ask for outlines with a bbox around the part you care about.");
+        }
+        if (wantsOutlines && hasAreaFilter) {
+            return textResponse("minArea/maxArea are not available on an outline call. Use them on the light list (no includeGeometry, no polygon) to find the parcels, then ask for outlines by bbox.");
+        }
+        if (wantsOutlines && hasCursor) {
+            return textResponse("An outline call has no paging, so there is no cursor to pass. Narrow the area instead — the cursor belongs to the light list.");
+        }
+        if (wantsOutlines && hasAddressFilter) {
+            return textResponse("street/buildingNumber are not available on an outline call. Use them on the light list (no includeGeometry, no polygon) to find the parcels, then ask for outlines by bbox.");
+        }
+        if (buildingNumber !== undefined && street === undefined) {
+            return textResponse("buildingNumber needs street alongside it, e.g. street=\"Karmelicka\", buildingNumber=\"10\". A number on its own would have to be looked up parcel by parcel across the whole area.");
+        }
+        if (hasAddressFilter) {
+            const scopeIsNarrow = hasBbox
+                || circleParts === 3
+                || (hasTeryt ? terytReachesCounty(params.teryt) : hasLocation);
+            if (!scopeIsNarrow) {
+                return textResponse(`A street name needs a narrower area alongside it: a bbox, a lat+lng+radiusKm circle, a location name, or a teryt of at least ${ADDRESS_FILTER_MIN_TERYT_DIGITS} digits (county level). The same street name occurs in hundreds of towns, so on its own it asks for a search of the whole country.`);
+            }
+        }
+        if (street !== undefined && wordCharCount(street) < STREET_MIN_WORD_CHARS) {
+            return textResponse(`street needs at least ${STREET_MIN_WORD_CHARS} letters or digits — punctuation alone cannot be looked up, and a shorter fragment would have to read every street name we hold. Pass more of the name.`);
+        }
+        if (hasPolygon) {
+            const { data, creditInfo } = await searchParcelsByPolygon(params.polygon, params.limit, apiKey);
+            return textResponse(formatParcelFeatures(data, "the polygon") + formatCreditFooter(creditInfo));
+        }
+        if (wantsOutlines) {
+            const { data, creditInfo } = await getParcelsMap(params.bbox, params.limit, apiKey);
+            return textResponse(formatParcelFeatures(data, "the bounding box") + formatCreditFooter(creditInfo));
+        }
+        const { data, creditInfo } = await listParcels({
+            teryt: params.teryt,
+            location: params.location,
+            bbox: params.bbox,
+            lat: params.lat,
+            lng: params.lng,
+            radiusKm: params.radiusKm,
+            minArea: params.minArea,
+            maxArea: params.maxArea,
+            street,
+            buildingNumber,
+            limit: params.limit,
+            cursor: params.cursor,
+        }, apiKey);
+        const area = hasTeryt ? `teryt ${sanitizeInput(params.teryt)}`
+            : hasLocation ? `"${sanitizeInput(params.location)}"`
+                : hasBbox ? "the bounding box"
+                    : `a ${params.radiusKm} km circle`;
+        const address = street === undefined ? ""
+            : buildingNumber === undefined
+                ? `, street "${sanitizeInput(street, ADDRESS_FILTER_MAX_CHARS)}"`
+                : `, street "${sanitizeInput(street, ADDRESS_FILTER_MAX_CHARS)}" no. ${sanitizeInput(buildingNumber, ADDRESS_FILTER_MAX_CHARS)}`;
+        return textResponse(formatParcelList(data, area + address, (creditInfo?.refunded ?? 0) > 0) + formatCreditFooter(creditInfo));
+    }));
     server.tool("search_by_polygon", `Search real estate transactions within a geographic polygon.
+Returns TRANSACTIONS — deeds and prices — despite the name. For the land plots themselves inside a drawn shape, pass the same polygon to list_parcels_in_area.
 Provide a GeoJSON Polygon geometry to search within a custom area.
 Returns transactions found inside the polygon with coordinates.
 Use for precise neighborhood/osiedle boundaries. Can estimate coordinates from search_by_area results. For quick searches, start with search_by_area instead.
@@ -442,8 +666,12 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
         maxArea: z.number().optional().describe("Maximum area in m²"),
         district: z.string().optional().describe("District name filter"),
         street: z.string().optional().describe("Street name filter (partial match)"),
-        limit: z.number().min(1).max(5000).default(100).optional()
-            .describe("Max results (1-5000, default 100). MCP displays up to 50 transactions."),
+        landUse: landUseParam,
+        buildingStoreys: buildingStoreysParam,
+        minFootprintArea: minFootprintAreaParam,
+        maxFootprintArea: maxFootprintAreaParam,
+        limit: z.number().min(1).max(3000).default(100).optional()
+            .describe("Max results (1-3000, default 100). MCP displays up to 50 transactions."),
     }, { readOnlyHint: true, destructiveHint: false, title: "Search Transactions by Polygon" }, async (params) => withErrorHandling("search_by_polygon", apiKey, async () => {
         requireApiKey(apiKey);
         const { data, creditInfo } = await searchByPolygon({
@@ -463,6 +691,10 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
             dateTo: params.dateTo,
             minArea: params.minArea,
             maxArea: params.maxArea,
+            landUse: params.landUse?.join(","),
+            buildingStoreys: params.buildingStoreys?.join(","),
+            minFootprintArea: params.minFootprintArea,
+            maxFootprintArea: params.maxFootprintArea,
             district: params.district,
             street: params.street,
             limit: params.limit,
@@ -471,7 +703,7 @@ Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21
     }));
     server.tool("compare_locations", `Compare real estate statistics across multiple locations side-by-side.
 Provide 2-5 district names to compare median price/m², average area, and transaction counts.
-Use list_locations first to find valid location names.
+This tool matches on name only. Call list_locations(search=...) first: use names it flags as RCN districts (rcn_district) — other names (most TERYT unit names) silently return no data here.
 Requires at least one filter besides districts (e.g., propertyType).
 Example: compare Mokotów, Wola, Ursynów for apartments.
 ${MARKET_CAVEAT}`, {
@@ -559,8 +791,8 @@ ${MARKET_CAVEAT}`, {
     server.tool("get_demographics", `Demographic, economic, housing and other local statistics for a Polish location, from GUS BDL (Bank Danych Lokalnych) — Poland's public Central Statistical Office open-data bank. ~50 indicators across 11 categories (population, economy, housing, spatial planning, infrastructure, environment, safety, education, prices) plus a few derived metrics.
 Address by location (city/county name) OR teryt. A name resolves to county/powiat (4-digit) level; for richer gmina/district-level data (L6) pass a 6 or 7-digit teryt. teryt wins when both are given. Use list_locations to find TERYT codes — neighborhoods/osiedla are NOT addressable here.
 A query returns the requested level PLUS all parent levels (a gmina query also yields powiat, NUTS3 region and voivodeship indicators). Optional year, or yearFrom+yearTo for a time series, and category to filter. Cost: 1 token.`, {
-        location: z.string().optional().describe("City/county name, resolves to county/powiat level (e.g. 'Warszawa', 'Kraków'). Use this OR teryt. For gmina-level data pass a 6/7-digit teryt instead."),
-        teryt: z.string().optional().describe("TERYT code: 2-digit (voivodeship, e.g. 14), 4-digit (county, e.g. 1465), 6 or 7-digit (gmina, e.g. 1465011). Wins over location. Use list_locations to find codes."),
+        location: z.string().optional().describe("City, county, or district name (e.g. 'Warszawa', 'Kraków'). A city/county name resolves to county/powiat level; a Warszawa district name (e.g. 'Mokotów') resolves to that district, another city's delegatura (e.g. 'Kraków-Podgórze') to its parent county. Use this OR teryt. For gmina-level data on other units pass a 6/7-digit teryt instead."),
+        teryt: z.string().optional().describe("TERYT code: 2-digit (voivodeship, e.g. 14), 4-digit (county, e.g. 1465), 6 or 7-digit (gmina, e.g. 1465011). The 7th digit selects the unit type: 3 = urban-rural gmina overall, 4/5 = urban/rural part only, 8 = Warszawa district (1465011 = all of Warszawa, 1465108 = Śródmieście). Wins over location. Use list_locations to find codes."),
         year: z.number().int().optional().describe("Single year (2003-present). Mutually exclusive with yearFrom/yearTo. Omit for the latest available year per indicator."),
         yearFrom: z.number().int().optional().describe("Start year for a time series (min 2003)."),
         yearTo: z.number().int().optional().describe("End year for a time series (max current year + 1)."),
@@ -590,7 +822,7 @@ A query returns the requested level PLUS all parent levels (a gmina query also y
 Address by location (city/county name → aggregates every municipality in that county) OR teryt (6-7 digits = one municipality, 4 digits = a county aggregate). teryt wins when both are given. Use list_locations to find codes.
 Known limits, state them when you report results: the bulletin carries only contracts BELOW the EU procurement thresholds (from 2021), so the largest investments are not visible here. A tender is attributed to the SEAT of the contracting authority, not to the works location — county and national authorities tender works in other municipalities. The category counters therefore include municipal authorities only, while the recent-notice list shows every authority with a flag. Absence of tenders is NOT evidence that a municipality is not investing.
 Cost: 1 token.`, {
-        location: z.string().optional().describe("City or county name (e.g. 'Warszawa', 'Krotoszyn'). Aggregates every municipality in the county. Use this OR teryt."),
+        location: z.string().optional().describe("City, county, or district name (e.g. 'Warszawa', 'Krotoszyn'). A city/county name aggregates every municipality in the county; a Warszawa district name (e.g. 'Mokotów') narrows to that gmina, another city's delegatura (e.g. 'Kraków-Podgórze') resolves to its parent county. Use this OR teryt."),
         teryt: z.string().optional().describe("TERYT code: 6 or 7 digits = one municipality (e.g. 146501), 4 digits = a county aggregate (e.g. 1465). Wins over location."),
     }, { readOnlyHint: true, destructiveHint: false, title: "Infrastructure Signals" }, async (params) => withErrorHandling("get_infrastructure_signals", apiKey, async () => {
         requireApiKey(apiKey);
@@ -650,7 +882,7 @@ Not comparable across cities with different as_of dates (RCN publication lag var
 Coverage is county-level only (miasta na prawach powiatu) plus Warszawa's 18 districts, and further limited to cities with asking-rent data. A town inside a larger powiat (e.g. Sandomierz, Pruszków), a non-Warszawa city district, or an osiedle does NOT resolve and returns a 404 — do not pass such names. Unless the location is a major city you already know is covered, call list_rental_yield_locations FIRST to get valid names, or pass a 4-digit county TERYT.
 Optional areaBucket restricts both sides to an apartment area range in m2 (e.g. '40-50'). Area ranges are NOT additive — a bucket does not sum back to 'all'.
 The transaction-price denominator uses the market median. ${MARKET_CAVEAT}`, {
-            location: z.string().optional().describe("County-level city name — must be a miasto na prawach powiatu or a catalog entry from list_rental_yield_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A town within a larger powiat, a non-Warszawa district, or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."),
+            location: z.string().optional().describe("County-level city name — a miasto na prawach powiatu or a catalog entry from list_rental_yield_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A Warszawa district name (e.g. 'Mokotów') narrows to that district; another city's delegatura (e.g. 'Kraków-Podgórze') resolves to its parent county. A town within a larger powiat or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."),
             teryt: z.string().optional().describe("TERYT code. 4 digits = county (e.g. 1465 = Warszawa). 6 digits = dzielnica where available (today: Warszawa's 18 districts, e.g. 146510 = Śródmieście) → yield for that district. Other longer codes (gmina/precinct) are truncated to the county. Wins over location when both are provided."),
             areaBucket: z.enum(["all", "0-30", "30-40", "40-50", "50-60", "60-80", "80+"]).optional().describe("Apartment area range in m2: all (default, whole stock), 0-30, 30-40, 40-50, 50-60, 60-80, 80+. Bucket values are not additive."),
         }, { readOnlyHint: true, destructiveHint: false, title: "[Beta] Rental Yield Estimate" }, async (params) => withErrorHandling("get_rental_yield", apiKey, async () => {
@@ -680,7 +912,7 @@ Not comparable across cities with different as_of dates (RCN publication lag var
 Coverage is county-level only (miasta na prawach powiatu) plus Warszawa's 18 districts, and further limited to cities with asking-sale data. A town inside a larger powiat (e.g. Sandomierz, Pruszków), a non-Warszawa city district, or an osiedle does NOT resolve and returns a 404 — do not pass such names. Unless the location is a major city you already know is covered, call list_price_spread_locations FIRST to get valid names, or pass a 4-digit county TERYT.
 Optional areaBucket restricts both sides to an apartment area range in m2 (e.g. '40-50'). Area ranges are NOT additive — a bucket does not sum back to 'all'.
 The transaction-price denominator uses the market median. ${MARKET_CAVEAT}`, {
-            location: z.string().optional().describe("County-level city name — must be a miasto na prawach powiatu or a catalog entry from list_price_spread_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A town within a larger powiat, a non-Warszawa district, or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."),
+            location: z.string().optional().describe("County-level city name — a miasto na prawach powiatu or a catalog entry from list_price_spread_locations (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). A Warszawa district name (e.g. 'Mokotów') narrows to that district; another city's delegatura (e.g. 'Kraków-Podgórze') resolves to its parent county. A town within a larger powiat or an osiedle will 404 — check the catalog or use teryt first. Use this OR teryt."),
             teryt: z.string().optional().describe("TERYT code. 4 digits = county (e.g. 1465 = Warszawa). 6 digits = dzielnica where available (today: Warszawa's 18 districts, e.g. 146510 = Śródmieście) → spread for that district. Other longer codes (gmina/precinct) are truncated to the county. Wins over location when both are provided."),
             marketType: z.enum(["primary", "secondary", "all"]).optional().describe("Transaction denominator segment: 'all' (default, composition-matched to mixed sale offers), 'secondary', or 'primary'."),
             areaBucket: z.enum(["all", "0-30", "30-40", "40-50", "50-60", "60-80", "80+"]).optional().describe("Apartment area range in m2: all (default, whole stock), 0-30, 30-40, 40-50, 50-60, 60-80, 80+. Bucket values are not additive."),
@@ -702,9 +934,35 @@ Optional search filters by city name (diacritic-insensitive substring, min 2 cha
             const { data, creditInfo } = await getPriceSpreadLocations({ search: params.search }, apiKey);
             return textResponse(formatPriceSpreadLocations(data) + formatCreditFooter(creditInfo));
         }));
+        server.tool("get_flood_risk", `EXPERIMENTAL (beta): this tool may change or be withdrawn without notice; do not build critical workflows on it.
+Report what share of a Polish county's real-estate transactions sit on land in a mapped flood-hazard zone, broken down by severity, from the RCN registry.
+Severity bands are return periods: high = most frequent flooding (~1-in-10-year), medium (~1-in-100-year), low = rarest (~1-in-500-year). Counts land in a mapped hazard zone only; absence of a zone is never asserted as 'safe' (an area may be unmapped).
+Address by location (city/county name → resolves to a county) OR teryt (4-digit county code; longer codes truncate to the county; a district code resolves to its county — exposure is reported at county level; teryt wins when both are given).
+Aggregated over the whole transaction history (all-time, no date window). Suppressed below 5 assessed transactions. Coverage is county-level. Unless the location is a major city you already know is covered, call list_flood_risk_locations FIRST to get valid names, or pass a 4-digit county TERYT.`, {
+            location: z.string().optional().describe("County-level city/county name (e.g. 'Warszawa', 'Kraków', 'Gdańsk'). District names are accepted (a Warszawa district or another city's delegatura, e.g. 'Kraków-Podgórze'), but coverage is county-level, so the answer is the parent county with a note. A town within a larger powiat or an osiedle may 404 — check the catalog or use teryt first. Use this OR teryt."),
+            teryt: z.string().optional().describe("TERYT code. 4 digits = county (e.g. 1465 = Warszawa). Longer codes (gmina/precinct/district) are truncated/resolved to the county. Wins over location when both are provided."),
+        }, { readOnlyHint: true, destructiveHint: false, title: "[Beta] Flood-Hazard Exposure Share" }, async (params) => withErrorHandling("get_flood_risk", apiKey, async () => {
+            requireApiKey(apiKey);
+            if (!params.location?.trim() && !params.teryt?.trim()) {
+                return textResponse('Provide a location (city/county name) or teryt (county code). Example: get_flood_risk(location="Warszawa").');
+            }
+            const { data, creditInfo } = await getFloodRisk({ location: params.location, teryt: params.teryt }, apiKey);
+            return textResponse(formatFloodRisk(data) + formatCreditFooter(creditInfo));
+        }));
+        server.tool("list_flood_risk_locations", `EXPERIMENTAL (beta): this tool may change or be withdrawn without notice; do not build critical workflows on it.
+List the counties for which get_flood_risk can return data (i.e. where transactions have a completed flood assessment). Use this to discover valid location/teryt values for get_flood_risk instead of guessing names.
+Each entry is coverage signal only (assessed sample size + confidence) — it does not compute the share; call get_flood_risk(location|teryt) for the actual exposure.
+Optional search filters by county name (diacritic-insensitive substring, min 2 chars). Results are sorted by assessed_sample_n descending. Free (0 credits).`, {
+            search: z.string().min(2, "search must be at least 2 characters").optional().describe("Filter by county name (diacritic-insensitive substring, min 2 chars). E.g. 'gda' → Gdańsk. Omit to list the full catalog."),
+        }, { readOnlyHint: true, destructiveHint: false, title: "[Beta] List Flood-Risk Locations" }, async (params) => withErrorHandling("list_flood_risk_locations", apiKey, async () => {
+            requireApiKey(apiKey);
+            const { data, creditInfo } = await getFloodRiskLocations({ search: params.search }, apiKey);
+            return textResponse(formatFloodRiskLocations(data) + formatCreditFooter(creditInfo));
+        }));
     }
     server.tool("get_building_breakdown", `Get the building-by-building breakdown for one transaction: footprint area, number of storeys, and estimated total floor area (footprint × storeys) for each building on the property.
 search_transactions / search_by_area / search_by_polygon return per-transaction building SUMS inline; this tool splits them into individual buildings. Use it after a search when a result has building data and you need the detail (e.g. a developed-land deed covering several buildings).
+Each building also carries a construction-age estimate derived from building-permit records. It is an ESTIMATE with an interval, never a registry construction date, and the records only start in 2016 — so for most buildings the honest answer is "construction year not established", which is stated explicitly rather than left out.
 The transaction_id is the id shown on a search result that has building data. Cost: 4 tokens. Returns nothing for a transaction with no buildings.`, {
         transaction_id: z.string().regex(UUID_RE, "transaction_id must be a UUID — copy the id from a search_transactions result that has building data").describe("Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result that carries building data."),
     }, { readOnlyHint: true, destructiveHint: false, title: "Building-by-Building Breakdown" }, async (params) => withErrorHandling("get_building_breakdown", apiKey, async () => {
@@ -740,8 +998,29 @@ TWO-STATE: a transaction whose land is in no mapped zone returns nothing — abs
         const { data: res, creditInfo } = await getTransactionLandslide(params.transaction_id, apiKey);
         return textResponse(formatLandslideBreakdown(res) + formatCreditFooter(creditInfo));
     }));
-    server.tool("get_transaction_surroundings", `Get the plot-by-plot surroundings profile for one transaction: for each linked plot, the distance in meters to the nearest cemetery, landfill (waste disposal site), sewage treatment plant, industrial/storage area, large industrial plant, and intensive livestock farm, from reference land-use and environmental-registry data. Useful for due-diligence on nearby nuisances.
-Distances are approximate and measured from the plot boundary; 0 means the plot touches or overlaps such an area. Each category is searched within a fixed radius only: cemetery 1 km, landfill 3 km, sewage treatment 2 km, industrial/storage 1 km, large industrial plant 3 km, intensive livestock farm 3 km.
+    server.tool("get_transaction_subsurface", `Get the parcel-by-parcel subsurface breakdown for one transaction across two dimensions: mining terrains and major groundwater reservoirs. For each linked plot that overlaps either — the mining-terrain status ('active' | 'former') with its mineral class ('subsidence' = extraction with surface deformation, the actual mining-damage risk; 'surface' = open-pit working, mostly local impact; 'fluid' = borehole extraction; 'other'), the groundwater-reservoir status ('documented' | 'undocumented'), the share of the plot inside each, and the per-object lists (mining terrain: name, oversight authority, validity dates; reservoir: number, name, documentation).
+A mining terrain is a legally defined zone of anticipated mining influence; its mapped location is approximate — an intersection is an advisory signal to verify with the competent mining-supervision authority, not a legal determination. A groundwater reservoir's extent alone imposes NO restriction; a restriction would come only from an established protection zone, which is not published here.
+Use it for a specific transaction to see whether its land overlaps a mining terrain or a major groundwater reservoir, and the per-object detail. get_parcel_report includes a one-line subsurface summary per parcel.
+TWO-STATE: a transaction whose land overlaps neither layer returns nothing — absence of data is never an assertion of safety. Cost: 4 tokens (refunded when there is no subsurface data).`, {
+        transaction_id: z.string().regex(UUID_RE, "transaction_id must be a UUID — copy the id from a search_transactions result").describe("Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result."),
+    }, { readOnlyHint: true, destructiveHint: false, title: "Transaction Subsurface Breakdown" }, async (params) => withErrorHandling("get_transaction_subsurface", apiKey, async () => {
+        requireApiKey(apiKey);
+        const { data: res, creditInfo } = await getTransactionSubsurface(params.transaction_id, apiKey);
+        return textResponse(formatSubsurfaceBreakdown(res) + formatCreditFooter(creditInfo));
+    }));
+    server.tool("get_transaction_roads", `Get the plot-by-plot road-access evidence for one transaction: for each linked plot, the distance in meters to the nearest public road, to the nearest road of any kind, and to the nearest motorway/expressway/dual-carriageway — plus, for the nearest public road, the estimated distance to the EDGE of its carriageway, its management category ('national' | 'voivodeship' | 'county' | 'municipal'), its functional class ('motorway' | 'expressway' | 'main_accelerated' | 'main' | 'collector' | 'local' | 'access' | 'other') and whether it runs at ground level (false = it crosses on a viaduct or in a tunnel, so it passes the plot over or under it). Each plot also carries access_indicator ('likely' | 'uncertain' | 'unlikely') and the version of the rule that produced it.
+access_indicator is GEOMETRIC EVIDENCE measured from carriageway centrelines in reference road-network data. It does NOT determine legal access and says nothing about easements or rights of way, which are recorded in the land register and are not published here — treat it as a lead to verify, never as a conclusion. That is why it has three states and is never a yes/no.
+Each measurement has a fixed radius: public road 500 m, road of any kind 500 m, motorway/expressway/dual-carriageway 3 km (that last one is a traffic-nuisance proxy, not an access signal). public_road_edge_distance_m is null when the source carries no carriageway width — no median is substituted.
+Use it for a specific transaction to judge how its land sits relative to the road network. get_parcel_report includes a one-line road-access summary per parcel.
+TWO-STATE: a null/absent distance means no such road within the search radius in the reference data — it is NEVER a guarantee that none exists. assessed=false means the plot has not been evaluated yet (no statement either way). Cost: 4 tokens (refunded when there is no informative data — no linked plots, or none evaluated yet).`, {
+        transaction_id: z.string().regex(UUID_RE, "transaction_id must be a UUID — copy the id from a search_transactions result").describe("Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result."),
+    }, { readOnlyHint: true, destructiveHint: false, title: "Transaction Road Access" }, async (params) => withErrorHandling("get_transaction_roads", apiKey, async () => {
+        requireApiKey(apiKey);
+        const { data: res, creditInfo } = await getTransactionRoads(params.transaction_id, apiKey);
+        return textResponse(formatRoads(res) + formatCreditFooter(creditInfo));
+    }));
+    server.tool("get_transaction_surroundings", `Get the plot-by-plot surroundings profile for one transaction: for each linked plot, the distance in meters to the nearest cemetery, landfill (waste disposal site), sewage treatment plant, industrial/storage area, large industrial plant, intensive livestock farm, high-voltage overhead power line and extra-high-voltage overhead power line, from reference land-use and environmental-registry data. Useful for due-diligence on nearby nuisances.
+Distances are approximate and measured from the plot boundary; 0 means the plot touches or overlaps such an area. Each category is searched within a fixed radius only: cemetery 1 km, landfill 3 km, sewage treatment 2 km, industrial/storage 1 km, large industrial plant 3 km, intensive livestock farm 3 km, high-voltage overhead power line 1 km, extra-high-voltage overhead power line 1 km. Only overhead high- and extra-high-voltage lines are covered — medium- and low-voltage lines are ubiquitous and carry no signal, and no easement corridor width or substation is published here.
 TWO-STATE: a null/absent distance means no such object within the search radius in the reference data — it is NEVER a guarantee that none exists. assessed=false means the plot has not been evaluated yet (no statement either way). Cost: 4 tokens (refunded when there is no informative data — no linked plots, or none evaluated yet).`, {
         transaction_id: z.string().regex(UUID_RE, "transaction_id must be a UUID — copy the id from a search_transactions result").describe("Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result."),
     }, { readOnlyHint: true, destructiveHint: false, title: "Transaction Surroundings Breakdown" }, async (params) => withErrorHandling("get_transaction_surroundings", apiKey, async () => {
@@ -758,8 +1037,8 @@ TWO-STATE: a transaction whose land has no stop within cap in any mode returns n
         const { data: res, creditInfo } = await getTransactionTransit(params.transaction_id, apiKey);
         return textResponse(formatTransitBreakdown(res) + formatCreditFooter(creditInfo));
     }));
-    server.tool("get_transaction_permits", `Get the building-permit history for one transaction's parcels, from the official national registry of positively resolved building permits and works notifications (records since 2016): for each case — its kind (permit / notification), the building intent and works type, the statutory object category, the deciding authority, the decision or intake date, the investment address, and the volume.
-Use it after a search to screen what has been built or approved on the transaction's land — a leading indicator of development activity. Match is by the parcel's current identifier, so splits/merges break the link, and only positively resolved cases are held (no pending or refused applications).
+    server.tool("get_transaction_permits", `Get the building-permit history for one transaction's parcels, from the official national registry of building permits and works notifications (records since 2016): for each case — its kind (permit / notification), the building intent and works type, the statutory object category, the deciding authority, the decision or intake date, the investment address, and the volume.
+Use it after a search to screen what has been built or approved on the transaction's land — a leading indicator of development activity. Match is by the parcel's current identifier, so splits/merges break the link. Permits are held once a decision has been issued; the outcome of that decision, granted or refused, is not part of the data held here. Notifications are held only where they were accepted without objection. Cases still pending are not held at all.
 TWO-STATE: a transaction whose parcels have no registered case returns nothing — an empty result is never a confirmation that nothing was ever planned. Cost: 4 tokens (refunded when there is no record).`, {
         transaction_id: z.string().regex(UUID_RE, "transaction_id must be a UUID — copy the id from a search_transactions result").describe("Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result."),
     }, { readOnlyHint: true, destructiveHint: false, title: "Transaction Building-Permit History" }, async (params) => withErrorHandling("get_transaction_permits", apiKey, async () => {
@@ -784,4 +1063,14 @@ TWO-STATE: a parcel with no matched eligible area returns nothing — absence of
         const { data: res, creditInfo } = await getTransactionFarmland(params.transaction_id, apiKey);
         return textResponse(formatFarmland(res) + formatCreditFooter(creditInfo));
     }));
+    server.tool("get_transaction_nature", `Get the parcel-by-parcel nature breakdown for one transaction: for each linked plot with a nature signal — the nearest forest within 2 km (forest_distance_m in metres, 0 = the plot overlaps forest, with its overlap share) and any overlapping protected natural areas: the sharpest form (protection_rank 1 = national park, 2 = nature reserve, 3 = Natura 2000, 4 = landscape park, 5 = protected landscape, 6 = other), building_restriction ('statutory_ban' = a build ban that follows directly from the Nature Protection Act for national parks and reserves, 'conditional' = restrictions depend on the act that established the area), the share of the plot under protection, and the named areas.
+This describes the SOURCE of a restriction (statute vs the establishing act), never the outcome of a specific permitting case, and is not legal advice. Forest is an amenity signal (proximity), protected areas a due-diligence one (build limits).
+Search results do not carry a nature signal, so call this tool directly on a transaction id whenever forest proximity or protected-area build limits matter. Use it after a search on land plots.
+An empty result is NEVER a statement that building is allowed — this layer does not cover local zoning plans, planning-permission decisions or areas under designation. A buffer zone around a park or reserve IS reported, as form 'buffer_zone' at rank 6, and never as a statutory ban. An empty result also says which kind of empty it is: either the plots were checked and carry no signal, or no nature reference data is held for them yet and nothing was checked — the second is never a finding that there is no forest or protected area. Cost: 4 tokens (refunded on any empty result).`, {
+        transaction_id: z.string().regex(UUID_RE, "transaction_id must be a UUID — copy the id from a search_transactions result").describe("Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result."),
+    }, { readOnlyHint: true, destructiveHint: false, title: "Transaction Nature (Forest & Protected Areas) Breakdown" }, async (params) => withErrorHandling("get_transaction_nature", apiKey, async () => {
+        requireApiKey(apiKey);
+        const { data: res, creditInfo } = await getTransactionNature(params.transaction_id, apiKey);
+        return textResponse(formatNatureBreakdown(res) + formatCreditFooter(creditInfo));
+    }));
 }