Cenogram - Polish Real Estate Data
Server Details
7M+ real estate transactions from Poland's RCN registry. Search, compare, and analyze prices.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 15 of 15 tools scored. Lowest: 3.7/5.
Each tool has a clearly distinct purpose. Overlapping search tools (search_by_area, search_by_polygon, search_transactions) are differentiated by their search modes (radius, polygon, structured query) and described clearly. Detail tools (get_transaction_*) are specific to different property attributes.
Tool names consistently use lowercase with underscores and follow verb_noun pattern. However, there is some variation: 'compare', 'get', 'list', 'search' are used as verbs. This is mostly consistent but not uniform across all tools (e.g., 'compare_locations' vs 'get_building_breakdown').
15 tools is well-scoped for a real estate data server. It covers search, statistics, location browsing, and detailed property analysis without feeling bloated or sparse.
The tool set covers the full lifecycle of data queries: browsing locations, searching transactions, obtaining market overviews, price statistics, demographics, and detailed property attributes (buildings, flood, heritage, landslide, surroundings). No obvious gaps for a read-only query service.
Available Tools
15 toolscompare_locationsARead-onlyInspect
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. Requires at least one filter besides districts (e.g., propertyType). Example: compare Mokotów, Wola, Ursynów for apartments. Note: median/average prices are market-based — fractional ownership shares and non-market deeds (public tenders, foreclosures, privileged/subsidized sales) are excluded from price aggregates. Transaction counts and coverage stay complete.
| Name | Required | Description | Default |
|---|---|---|---|
| rooms | No | Number of rooms (izby) filter, residential units only. Multi-select; '8plus' means 8 or more, 'unknown' = no room count recorded (NULL). E.g. ['2','3'] for 2-3 izby flats. Without 'unknown', rows with no room count are excluded. | |
| dateTo | No | End date (YYYY-MM-DD) | |
| street | No | Street name filter | |
| maxArea | No | Maximum area in m² | |
| minArea | No | Minimum area in m² | |
| dateFrom | No | Start date (YYYY-MM-DD) | |
| maxPrice | No | Maximum price in PLN | |
| minPrice | No | Minimum price in PLN | |
| districts | Yes | Comma-separated district names to compare (2-5, must be unique). E.g. 'Mokotów,Wola,Ursynów' | |
| marketType | No | Market type filter | |
| buildingType | No | Building type filter (PKOB classification). 'unknown' = no type recorded (NULL); without it such rows are excluded (~39% of buildings have no type). | |
| propertyType | No | Property type filter (recommended - API requires at least one filter) | |
| unitFunction | No | Unit/apartment function filter. 'unknown' = no function recorded (NULL); without it such rows are excluded. Garages appear only when 'garage' is selected, not via 'unknown'. | |
| mpzpDesignation | No | MPZP zoning designation prefix filter (e.g. 'terenRolniczy', 'budownictwoMieszkanioweJednorodzinne', 'budownictwoMieszkanioweWielorodzinne'). Use 'unknown' for rows with no designation recorded (NULL); distinct from the registry code 'brakMPZPLubWZ'. | |
| transactionType | No | Transaction type filter. For market analysis, ALWAYS specify to exclude non-market transactions. | |
| includeDemographics | No | Add a GUS BDL demographics block per district (county-level: population density, wages, unemployment, median age, plus a few cross-source ratios like price-to-income). Districts that don't resolve to a county are omitted from the demographics section. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds critical behavioral context: 'median/average prices are market-based — fractional ownership shares and non-market deeds... are excluded from price aggregates. Transaction counts and coverage stay complete.' This explains data limitations beyond what annotations provide, with no contradictions.
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 description is concise and well-structured: first sentence states purpose, second provides prerequisites, third gives an example, and fourth notes important behavioral details. Every sentence serves a clear purpose with no redundancy.
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 (16 parameters, no output schema), the description covers the main use case, prerequisites, and key behavioral notes. However, it lacks any mention of output format, pagination, or limitations (e.g., maximum number of locations). The sibling tools are listed but no explicit guidance on when to prefer alternatives is provided.
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% (16 parameters all have descriptions). The description adds value by explaining the districts parameter format (comma-separated, 2-5 unique names) and the requirement for an additional filter. It also provides high-level context for price exclusions, which is not tied to a specific schema field but enhances understanding.
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 clearly states the tool's purpose: 'Compare real estate statistics across multiple locations side-by-side.' It specifies the metrics (median price/m², average area, transaction counts) and prerequisites. This distinguishes it from sibling tools like get_price_statistics or get_market_overview, which focus on single-location statistics.
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 provides explicit guidance: use list_locations first to find valid names, requires at least one filter besides districts, and limits to 2-5 districts. An example is given. However, it does not explicitly mention when not to use this tool or suggest alternatives among siblings, leaving some ambiguity for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_building_breakdownARead-onlyInspect
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). The transaction_id is the id shown on a search result that has building data. Cost: 1 token. Returns nothing for a transaction with no buildings.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result that carries building data. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds beyond annotations: cost (1 token), returns nothing for transactions without buildings, and confirms read-only nature. No contradiction with annotations.
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 usage, then details. Every sentence adds value; no redundancy.
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 simple drill-down tool: explains what it does, when to use, input, cost, and edge case. No output schema but describes return fields.
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 has 100% coverage, but description adds context: transaction_id is from search results with building data. Explains pattern and source.
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?
Clearly states it retrieves building-by-building breakdown for a transaction, specifying fields (footprint, storeys, total floor area). Distinguishes from sibling tools that return sums inline.
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?
Explicitly advises to use after a search when building data is present, mentions sibling tools that return sums, and gives example context (developed-land deed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_demographicsARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Single year (2003-present). Mutually exclusive with yearFrom/yearTo. Omit for the latest available year per indicator. | |
| teryt | No | 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. | |
| yearTo | No | End year for a time series (max current year + 1). | |
| category | No | Filter to these categories. Omit to return all available. | |
| location | No | 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. | |
| yearFrom | No | Start year for a time series (min 2003). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich behavioral details beyond annotations: parent level returns, mutual exclusivity of year parameters, cost (1 token), data source (GUS BDL), and teryt-wins logic. Annotations already declare read-only, and description aligns with no contradiction.
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 description is well-organized and front-loaded, but slightly lengthy. Every sentence adds value, though minor trimming could improve conciseness without losing clarity.
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 no output schema, the description explains that the query returns the requested level plus all parent levels and mentions indicators. Could specify output format, but sufficient for an agent to understand return scope.
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?
With 100% schema coverage, the description adds substantial meaning: explains that teryt wins over location, location resolves to county level, year parameters are for time series, and category filter lists valid values. This enhances the agent's understanding beyond 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 clearly states it returns demographic, economic, housing, and other local statistics for a Polish location from GUS BDL, specifying ~50 indicators across 11 categories. It distinguishes from siblings by noting that neighborhoods/osiedla are not addressable here and references list_locations for TERYT codes.
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?
Provides explicit guidance on addressing by location name or teryt, resolution differences (county vs gmina), teryt precedence, parent level returns, optional year ranges, category filtering, cost, and use of list_locations. Does not explicitly state when to use alternatives, but contextually clear that this is for broad statistics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_market_overviewARead-onlyInspect
Get a comprehensive overview of the Polish real estate transaction database. Returns: total transaction count, date range, breakdown by property type and market type, top locations, price statistics. Note: data quality varies by field - marketType is unknown for ~55% of records, transaction_date missing for ~1.7%. Note: median/average prices are market-based — fractional ownership shares and non-market deeds (public tenders, foreclosures, privileged/subsidized sales) are excluded from price aggregates. Transaction counts and coverage stay complete.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds critical behavioral details: data quality issues (marketType unknown for ~55%, transaction_date missing ~1.7%) and exclusion of fractional ownership and non-market deeds from price aggregates. This provides essential context about what the returned statistics represent.
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 description is well-structured with a clear main purpose followed by two bullet-point notes on data quality. Each sentence adds value, though the notes could be slightly more concise. The key information is front-loaded.
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 no output schema and no parameters, the description adequately explains the return values and important caveats. It covers the tool's scope and limitations, though it could be more specific about the response structure (e.g., whether it's a JSON object with named fields).
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?
There are no parameters, so the schema coverage is 100% by default. The description adds value by explaining what the output returns and the data quality considerations, which compensates for the lack of parameter documentation.
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 clearly starts with 'Get a comprehensive overview', specifying the verb and resource (Polish real estate transaction database). It lists specific return categories like transaction count, date range, breakdowns, top locations, and price statistics, making it distinct from sibling tools that focus on subsets like price distribution or building breakdown.
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 implies this tool is for high-level summaries of the entire database, naturally separating it from more specific sibling tools. While it does not explicitly state when not to use or name alternatives, the context of sibling names (e.g., get_price_statistics, compare_locations) makes the usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_price_distributionARead-onlyInspect
Get price distribution histogram showing how many transactions fall into each price range. Useful for understanding the overall market price structure in Poland. Note: median/average prices are market-based — fractional ownership shares and non-market deeds (public tenders, foreclosures, privileged/subsidized sales) are excluded from price aggregates. Transaction counts and coverage stay complete.
| Name | Required | Description | Default |
|---|---|---|---|
| bins | No | Number of price bins (5-50, default 20) | |
| maxPrice | No | Maximum price to include (default 3,000,000 PLN) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true, destructiveHint=false) already indicate safety. The description adds value by disclosing that median/average prices exclude fractional shares and non-market deeds, while transaction counts remain complete. This provides important behavioral context beyond the annotations.
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 description is concise with three sentences, each serving a distinct purpose: stating the function, indicating usefulness, and providing a critical behavioral note. It is well-structured and front-loaded with the core purpose.
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 low complexity (2 parameters, no output schema), the description covers the purpose and key behavioral notes. However, without an output schema, the description could briefly mention the expected return format (e.g., bins and counts) to fully compensate. The absence of this information leaves some uncertainty for the agent.
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?
The input schema has 100% description coverage for both parameters ('bins' and 'maxPrice'), so the schema already explains their meaning. The description does not add any additional parameter semantics, so baseline score of 3 is appropriate.
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 clearly states the tool retrieves a price distribution histogram, specifying the verb 'Get' and resource 'price distribution histogram'. It sets the context of market price structure in Poland. However, it does not explicitly distinguish this tool from the sibling tool 'get_price_statistics', which might also provide price-related data, though the histogram aspect provides implicit differentiation.
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 mentions it is 'useful for understanding the overall market price structure', which gives a clear use case. However, it lacks explicit guidance on when to use this tool versus alternatives like 'get_price_statistics', and does not provide any when-not-to-use scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_price_statisticsARead-onlyInspect
Get price per m² statistics by location for residential apartments in Poland. Note: only covers residential units (lokale mieszkalne). For other property types, use search_transactions. 'Warszawa'/'Kraków'/'Łódź' auto-expand to all sub-districts (Warszawa=19, Kraków=5, Łódź=6). Other names use partial match. Data quality: based on transaction prices from notarial deeds, not asking/listing prices. Coverage varies by county (some have data gaps of 5+ years). Note: median/average prices are market-based — fractional ownership shares and non-market deeds (public tenders, foreclosures, privileged/subsidized sales) are excluded from price aggregates. Transaction counts and coverage stay complete.
| Name | Required | Description | Default |
|---|---|---|---|
| location | No | Filter by location name. 'Warszawa'/'Kraków'/'Łódź' auto-expand to all sub-districts. Other names use case-insensitive partial match (e.g. 'Wrocł' matches 'Wrocław'). Omit for all Poland. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: data source (notarial deeds, not asking prices), coverage variability, and exclusions (fractional shares, non-market deeds), enhancing transparency beyond annotations.
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 description is well-structured with a clear main sentence followed by notes. While slightly verbose, every sentence adds value and the front-loading of purpose is effective.
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 no output schema, the description effectively explains what is returned (statistics, median/average prices, transaction counts) and covers data quality and exclusions, making it fully informative for an agent.
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%, but the description enriches the 'location' parameter with auto-expansion rules, case-insensitive partial matching, and omission behavior for all Poland, adding significant 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 clearly states it gets price per m² statistics for residential apartments in Poland by location, distinguishing from sibling tool search_transactions for other property types. The verb 'Get' and resource 'price per m² statistics' are specific and unambiguous.
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?
Explicitly states when to use (residential units) and when not (other property types, directing to search_transactions). Also details auto-expansion for major cities and partial match behavior, aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_transaction_floodARead-onlyInspect
Get the parcel-by-parcel flood-hazard breakdown for one transaction: for each linked plot that sits in a mapped flood zone — the worst hazard category (high/medium/low, i.e. ~1-in-10-year to ~1-in-500-year), the hazard type (river/coastal/infrastructure), the share of the plot inside the zone, and the full per-scenario list (each with its return period). search_transactions (and search_by_area) surface a per-transaction worst-case flood_risk inline; this tool splits that into the individual parcels and scenarios behind it. Use it after a search when a result shows flood_risk. (search_by_polygon does not include flood inline.) TWO-STATE: a transaction whose land is in no mapped zone returns nothing — absence of a zone is never asserted as "safe". Cost: 1 token (refunded when there is no flood data).
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations (readOnlyHint=true, destructiveHint=false) by explaining the 'TWO-STATE' behavior: returns nothing if no mapped zone, and clarifies that absence of a zone is not asserted as safe. It also mentions token cost and refund, providing complete behavioral context.
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 description is well-structured: first sentence defines the main purpose, then explains relationship to siblings, and finally notes special behavior. It is slightly verbose but every sentence adds value. Could be trimmed slightly, but overall effective.
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?
Despite lacking an output schema, the description details the return format (per-parcel breakdown including worst hazard, type, share, and per-scenario list). It covers input, output, behavior, cost, and sibling context, making it fully self-contained for a single-parameter tool.
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?
The input schema has 100% description coverage for the single parameter (transaction_id, a UUID from search results). The description does not add additional semantics, but the schema already provides sufficient meaning. Baseline score of 3 is appropriate.
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 clearly states the tool retrieves a parcel-by-parcel flood-hazard breakdown for one transaction. It specifies the output fields (worst hazard category, type, share, per-scenario list) and distinguishes itself from sibling tools by explaining that search_transactions and search_by_area provide only inline flood_risk, while this tool splits it into individual parcels.
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 explicitly says to use this tool after a search when a result shows flood_risk. It also notes that search_by_polygon does not include flood inline, helping users decide when not to use this tool. However, it does not provide an explicit alternative or exclusion beyond what is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_transaction_heritageARead-onlyInspect
Get the parcel-by-parcel heritage-listing breakdown for one transaction: for each linked plot with a detected heritage listing — the status (listed = a protected monument on/at the plot; zone = the plot lies within a protected urban layout or the designated surroundings of a monument), the share of the plot inside the protected area (when measurable), and the individual entries (category, name, function, period, entry date). search_transactions (and search_by_area) surface a per-transaction heritage_status inline; this tool splits that into the individual parcels and entries behind it. Use it after a search when a result shows a heritage listing. (search_by_polygon does not include heritage inline.) TWO-STATE: a transaction with no detected listing returns nothing — absence of a detection is never asserted as "not listed". Indicative data — the regional heritage conservator makes the final, binding determination. Cost: 1 token (refunded when there is no heritage data).
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and destructiveHint. Description adds important behavior: two-state (no listing returns nothing, not a negative assertion), indicative data disclaimer, and cost refund. No contradiction with annotations.
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?
Description is well-structured: first sentence states purpose, then contrasts with siblings, then explains behavior and edge cases. Every sentence adds value, though slightly wordy.
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 one parameter and no output schema, the description fully explains what the tool returns (per parcel: status, share, entries). It covers edge cases (no listing), cost, and data limitations, making it complete for agent understanding.
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 description already explains the parameter sufficiently. The description reiterates the source of the transaction ID but does not add new semantic 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 clearly states the tool retrieves a parcel-by-parcel heritage-listing breakdown for a transaction. It distinguishes itself from sibling tools like search_transactions by explaining that it splits the inline heritage_status into individual parcels and entries.
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?
Explicitly says to use after a search when a result shows a heritage listing. Contrasts with search_by_polygon which lacks inline heritage. Also mentions cost refund when no heritage data, guiding when it is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_transaction_landslideARead-onlyInspect
Get the parcel-by-parcel landslide-hazard breakdown for one transaction, based on official landslide-hazard maps (1:10,000 scale): for each linked plot that intersects a mapped hazard area — the worst category ('landslide' = a mapped landslide area, 'threatened' = an area threatened by mass movements), the share of the plot inside the mapped zones, and the per-zone list (each with its source_version_date — the source-record version date, not a survey/observation date). An intersection at this scale means the parcel overlaps a mapped hazard area, not that the parcel itself is a landslide. search_transactions (and search_by_area) surface a per-transaction worst-case landslide_risk inline; this tool splits that into the individual parcels and zones behind it. Use it after a search when a result shows a landslide risk. (search_by_polygon does not include landslide inline.) TWO-STATE: a transaction whose land is in no mapped zone returns nothing — absence of data is never an assertion of safety. Cost: 1 token (refunded when there is no landslide data).
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds important behavioral context: the scale of maps, interpretation of intersection, absence-of-data disclaimer, and token cost/refund policy. No contradiction with annotations.
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 description is somewhat verbose, including multiple explanatory sentences that could be condensed. While front-loaded with purpose, the additional details on scale and intersection, though valuable, make it less concise than ideal.
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 no output schema, the description adequately outlines the returned fields (worst category, share, per-zone list with source_version_date) and the behavior when no hazard is found. It is complete for a single-parameter tool, though error handling for invalid IDs is not addressed.
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 description for transaction_id is already sufficiently clear. The tool description repeats this without adding new semantic details, so baseline 3 is appropriate.
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 clearly states the verb 'Get' and resource 'parcel-by-parcel landslide-hazard breakdown for one transaction'. It distinguishes from siblings by explaining that search_transactions provides a worst-case inline, and search_by_polygon does not include landslide inline.
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?
Explicitly says 'Use it after a search when a result shows a landslide risk.' It contrasts with related tools and explains the two-state behavior when no hazard exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_transaction_surroundingsARead-onlyInspect
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, and industrial/storage area, from reference land-use 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. 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: 1 token (refunded when there is no informative data — no linked plots, or none evaluated yet).
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, non-destructive behavior. The description significantly extends transparency by explaining distance approximations, boundary/source, search radii, the two-state outcome (null vs assessed=false), and cost/refund policy. No contradiction with annotations.
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 description is brief and well-structured, with two focused paragraphs. The first paragraph covers purpose and output; the second covers nuance and cost. Every sentence adds value, no fluff, and the key information is front-loaded.
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?
Despite lacking an output schema, the description sufficiently explains the response: for each linked plot, distances to four categories, with special states (null, assessed=false). It also documents search radius limits and cost conditions, making the tool's behavior fully comprehensible.
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?
The single parameter (transaction_id) has a description in the schema that already specifies its source and format. The tool description adds minimal additional semantic meaning beyond the schema; it merely reaffirms the tool's scope. With 100% schema coverage, baseline 3 is appropriate.
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 clearly states the tool retrieves a plot-by-plot surroundings profile for a transaction, specifying the four distance categories (cemetery, landfill, sewage treatment, industrial/storage). It also indicates the use case (due diligence on nuisances), which differentiates it from sibling tools that fetch other data types.
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 explicitly notes the tool works for one transaction and that the transaction_id comes from related search tools. It does not, however, provide explicit when-to-use or when-not-to-use guidance or compare with specific alternatives among siblings, though the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_locationsARead-onlyInspect
Browse locations in two modes:
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
Name search (search param): Find districts by name (flat list, legacy). If both provided, parent takes precedence. 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).
| Name | Required | Description | Default |
|---|---|---|---|
| parent | No | TERYT parent code to browse children. 2-digit (voivodeship → counties), 4-digit (county → municipalities), 6-digit (municipality → precincts). Omit for all voivodeships. | |
| search | No | Filter locations by name (case-insensitive partial match, e.g. 'Krak' for Kraków districts). Ignored when parent is set. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral details: hierarchical navigation, code-length rules, and precedence. No contradictions.
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?
Well-structured with bullet points and clear sections. Front-loaded with the two modes. Every sentence is informative and necessary, no redundancy.
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?
Despite no output schema, the description compensates by explaining what is returned (TERYT codes and names). Complete for a browse tool, covering all modes and edge cases.
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%, but the description adds substantial context: explains code lengths for each level, precedence of parent, and the case-insensitive partial match for search. Adds value beyond 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 clearly states the tool's purpose: browsing locations in two distinct modes (TERYT hierarchy and name search). It distinguishes itself from siblings by noting it returns TERYT codes for use in search_transactions.
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?
Provides explicit guidance on when to use each mode (parent for navigation, search for name lookup) and precedence rules. Also advises using 'teryt' over 'location' to avoid name ambiguity, with a concrete example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_by_areaARead-onlyInspect
Search real estate transactions within a geographic radius. 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). Area filters (minArea/maxArea) work for all propertyType values. Permalink: every result is shareable on the map. From a result's "id:" line and its "Location: °N, °E" line, build https://cenogram.pl/ceny-transakcyjne#v=1&lat=&lng=&z=16&tx= (drop the °N/°E; lat = the °N number, lng = the °E number) — opens that exact transaction on the map. Omit &tx= 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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results (1-50, default 20) | |
| rooms | No | Number of rooms (izby) filter, residential units only. Multi-select; '8plus' means 8 or more, 'unknown' = no room count recorded (NULL). E.g. ['2','3'] for 2-3 izby flats. Without 'unknown', rows with no room count are excluded. | |
| dateTo | No | End date (YYYY-MM-DD) | |
| maxArea | No | Maximum area in m² | |
| minArea | No | Minimum area in m² (usable_area_m2 for units, parcel_area for land) | |
| dateFrom | No | Start date (YYYY-MM-DD) | |
| latitude | Yes | Latitude (Poland range: 49-55) | |
| maxPrice | No | Maximum price in PLN | |
| minPrice | No | Minimum price in PLN | |
| radiusKm | No | Search radius in km (0.1-50, default 2). Use 0.5-1 for neighborhoods, 0.3-0.5 for streets. | |
| floodRisk | No | Flood-hazard filter. high = most frequent flooding (~1-in-10-year), medium (~1-in-100-year), low = rarest (~1-in-500-year). Selects ONLY transactions whose land sits in a mapped flood zone; absence of a zone is never asserted as 'safe'. Multi-select; e.g. ['medium','high'] = at least medium risk. | |
| longitude | Yes | Longitude (Poland range: 14-25) | |
| marketType | No | Market type: primary (developer) or secondary (resale). ~55% of records have unknown market type and will be excluded when this filter is used. | |
| buildingType | No | Building type filter (PKOB classification). 'unknown' = no type recorded (NULL); without it such rows are excluded (~39% of buildings have no type). | |
| propertyType | No | Property type filter | |
| unitFunction | No | Unit/apartment function filter. 'unknown' = no function recorded (NULL); without it such rows are excluded. Garages appear only when 'garage' is selected, not via 'unknown'. | |
| landslideRisk | No | 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. | |
| heritageStatus | No | 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. | |
| transactionType | No | Transaction type filter. For market analysis, ALWAYS specify to exclude non-market transactions. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already specify readOnlyHint and destructiveHint. The description adds extensive behavioral detail: radius constraints, area filter applicability, permalink construction, field provenance (RCN vs computed values), and special filter semantics (e.g., flood risk selects only mapped zones, absence not safe). No contradictions.
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 description is long but well-structured and information-dense. Each section (purpose, radius guide, example, filter notes, permalink, provenance) serves a distinct purpose. Minor redundancy in radius guidance appears in both paragraph and schema description, but overall efficient for the complexity.
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?
The description covers search behavior, radius, filters, permalink, and data provenance. It does not describe the return format or pagination, but no output schema exists. The tool has 19 parameters, and the description handles most aspects. It assumes domain knowledge (TERYT, PKOB, RCN) which may be slightly incomplete for new users.
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%, but the description adds significant value beyond schema descriptions: radius guide per search scope, room filter behavior with 'unknown', market type exclusion rate, building type unknown exclusion, unit function garage nuance, and transaction type recommendation. This elevates semantics beyond 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?
The description clearly states it searches real estate transactions within a geographic radius. It specifies the tool is best for neighborhood/osiedle searches, distinguishing it from other search tools like search_by_polygon. The verb 'search' and resource 'transactions within a radius' are explicit.
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 provides radius guidance (e.g., 0.5-1 km for neighborhoods), an example, and details on area filters. However, it does not explicitly list when to avoid this tool or name alternative tools, though the context signals include sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_by_polygonARead-onlyInspect
Search real estate transactions within a geographic polygon. 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. Coordinates are [longitude, latitude]. First and last point must be identical. Permalink: every result is shareable on the map. From a result's "id:" line and its "Location: °N, °E" line, build https://cenogram.pl/ceny-transakcyjne#v=1&lat=&lng=&z=16&tx= (drop the °N/°E; lat = the °N number, lng = the °E number) — opens that exact transaction on the map. Omit &tx= 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. Example: {"type":"Polygon","coordinates":[[[21.0,52.2],[21.01,52.2],[21.01,52.21],[21.0,52.21],[21.0,52.2]]]}
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (1-5000, default 100). MCP displays up to 50 transactions. | |
| rooms | No | Number of rooms (izby) filter, residential units only. Multi-select; '8plus' means 8 or more, 'unknown' = no room count recorded (NULL). E.g. ['2','3'] for 2-3 izby flats. Without 'unknown', rows with no room count are excluded. | |
| dateTo | No | End date (YYYY-MM-DD) | |
| street | No | Street name filter (partial match) | |
| maxArea | No | Maximum area in m² | |
| minArea | No | Minimum area in m² | |
| polygon | Yes | GeoJSON Polygon geometry. Coordinates: [longitude, latitude] pairs. First and last point must be identical. Max 500 vertices total. | |
| dateFrom | No | Start date (YYYY-MM-DD) | |
| district | No | District name filter | |
| maxPrice | No | Maximum price in PLN | |
| minPrice | No | Minimum price in PLN | |
| marketType | No | Market type filter | |
| buildingType | No | Building type filter (PKOB classification). 'unknown' = no type recorded (NULL); without it such rows are excluded (~39% of buildings have no type). | |
| propertyType | No | Property type filter | |
| unitFunction | No | Unit/apartment function filter. 'unknown' = no function recorded (NULL); without it such rows are excluded. Garages appear only when 'garage' is selected, not via 'unknown'. | |
| mpzpDesignation | No | MPZP zoning designation filter (exact match). Use 'unknown' for rows with no designation recorded (NULL); distinct from the registry code 'brakMPZPLubWZ'. | |
| transactionType | No | Transaction type filter. For market analysis, ALWAYS specify to exclude non-market transactions. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true/destructiveHint=false. Description adds: coordinate order ([longitude, latitude]), first/last point identical, max 500 vertices, permalink construction, and data provenance (notarial deed vs computed). No contradictions.
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?
Slightly verbose but all content is relevant. Front-loaded purpose and usage, then parameter details, example, and field provenance. Each sentence adds value.
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?
Handles 17 parameters well with no output schema. Covers polygon specification, filter behaviors, and data provenance. Could be strengthened by briefly noting that results include coordinates and transaction IDs.
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 100%, but description adds valuable context: coordinate order, polygon closure requirement, vertex limit, example JSON, and explains filter behaviors (e.g., 'unknown' in buildingType, unitFunction, transactionType). Adds meaning beyond 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?
Clear statement: 'Search real estate transactions within a geographic polygon.' Distinguishes from sibling search_by_area (for quick searches) and search_transactions by specifying polygon-based spatial search.
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 guidance: 'Use for precise neighborhood/osiedle boundaries.' and 'For quick searches, start with search_by_area instead.' Also explains coordinate order and polygon closure, aiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_parcelsARead-onlyInspect
Search for land parcels by parcel ID prefix (autocomplete). 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'.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Parcel ID prefix to search for (min 3 chars). E.g. '146518_8.01' | |
| limit | No | Max results (1-10, default 10) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the read-only nature (matching annotations) and adds details about autocomplete behavior and returned fields (district, area, GPS coordinates). No contradictions with annotations.
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 description is concise and well-structured, with three sentences plus an example. It is front-loaded with the main purpose.
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 simplicity of the tool and no output schema, the description sufficiently explains return fields and behavior. It is complete enough for an agent to understand what to expect.
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% with clear descriptions for both parameters. The description adds a concrete example but does not provide additional semantic value 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 clearly states the tool searches for land parcels by parcel ID prefix with autocomplete. It distinguishes from sibling tools like search_by_area and search_transactions by focusing on parcel ID prefix matching.
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 provides a use case: finding exact parcel IDs then searching transactions nearby. However, it does not explicitly exclude cases when other search tools should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_transactionsARead-onlyInspect
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. 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: °N, °E" line, build https://cenogram.pl/ceny-transakcyjne#v=1&lat=&lng=&z=16&tx= (drop the °N/°E; lat = the °N number, lng = the °E number) — opens that exact transaction on the map. Omit &tx= 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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (default: 1) | |
| sort | No | Sort by field (default: date) | date |
| limit | No | Number of results (1-50, default 10) | |
| order | No | Sort order (default: desc) | desc |
| rooms | No | Number of rooms (izby) filter, residential units only. Multi-select; '8plus' means 8 or more, 'unknown' = no room count recorded (NULL). E.g. ['2','3'] for 2-3 izby flats. Without 'unknown', rows with no room count are excluded. | |
| teryt | No | 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. | |
| dateTo | No | End date (YYYY-MM-DD) | |
| street | No | Street name filter (partial match, e.g. 'Puławska', 'Trakt Lubelski') | |
| maxArea | No | Maximum area in m² | |
| minArea | No | Minimum area in m² | |
| dateFrom | No | Start date (YYYY-MM-DD) | |
| location | No | 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. | |
| maxPrice | No | Maximum price in PLN | |
| minPrice | No | Minimum price in PLN | |
| parcelId | No | 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. | |
| floodRisk | No | Flood-hazard filter. high = most frequent flooding (~1-in-10-year), medium (~1-in-100-year), low = rarest (~1-in-500-year). Selects ONLY transactions whose land sits in a mapped flood zone; absence of a zone is never asserted as 'safe'. Multi-select; e.g. ['medium','high'] = at least medium risk. | |
| marketType | No | Market type: primary (developer) or secondary (resale). ~55% of records have unknown market type and will be excluded when this filter is used. | |
| buildingType | No | Building type filter (PKOB classification). 'unknown' = no type recorded (NULL); without it such rows are excluded (~39% of buildings have no type). | |
| propertyType | No | Property type filter | |
| unitFunction | No | Unit/apartment function filter. 'unknown' = no function recorded (NULL); without it such rows are excluded. Garages appear only when 'garage' is selected, not via 'unknown'. | |
| landslideRisk | No | 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. | |
| buildingNumber | No | Building/house number (e.g. '251C', '12A'). Requires location or street to be set. | |
| heritageStatus | No | 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. | |
| mpzpDesignation | No | MPZP zoning designation filter (exact match, e.g. 'budownictwoMieszkanioweWielorodzinne', 'terenObiektowProdukcyjnychSkladowIMagazynow'). Use 'unknown' for rows with no designation recorded (NULL); distinct from the registry code 'brakMPZPLubWZ' (= 'no plan/WZ' recorded as data). | |
| transactionType | No | Transaction type filter. For market analysis, ALWAYS specify transactionType to exclude non-market transactions (subsidized, foreclosure, public purpose). ~2% of transactions have unknown type (NULL) and are excluded when this filter is used unless 'unknown' is included. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, which are consistent with a search tool. The description adds numerous behavioral details: marketType NULL ~55%, transaction_date NULL ~1.7%, permalink construction, field provenance with inline [...], location matches TERYT only. No contradictions.
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 description is thorough but lengthy due to necessary data caveats and usage instructions. It is well-structured: purpose, prerequisites, example, data notes, permalink, provenance, and location limitations. While slightly verbose, the complexity justifies the length.
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 25 parameters, no output schema, and complex data quirks (NULL handling, filtering exclusions, permalink, location matching), the description covers all essential aspects comprehensively. It provides enough context for an AI agent to use the tool effectively.
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% with parameter descriptions. The description adds operational context beyond schema, such as the recommendation to always specify transactionType for market analysis, how to handle NULLs, and the permalink construction. This adds value but the schema already covers basics.
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 clearly states the tool searches Polish real estate transactions from the RCN registry, lists the returned fields (address, date, price, area, price/m², property type), and distinguishes from sibling tools like search_by_area (for neighborhoods) and list_locations (prerequisite).
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?
Explicitly instructs to use list_locations first to find valid location names, provides an example search scenario, and explains when to use search_by_area instead (for neighborhoods). Also provides data notes on NULL handling and filtering implications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!