Cenogram - Polish Real Estate Data

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral nuance by specifying that median/average prices exclude non-market transactions (fractional ownership, public tenders, foreclosures, privileged/subsidized sales) while transaction counts remain complete. This goes beyond the annotations without 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-structured: first sentence states purpose, then usage guidelines, then a note on data exclusion. It is front-loaded and each sentence adds value, though slightly verbose in the second paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 18 parameters, no output schema, and annotations providing readOnly, the description covers key behavioral aspects (exclusion logic) and usage prerequisites (list_locations, required filter). It is sufficiently complete for a comparative 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?

Schema coverage is 100%, so the description does not need to explain parameters. It adds context about the districts parameter format and the requirement for an additional filter, but this is marginal value beyond the schema. 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?

Description clearly states the tool compares real estate statistics across multiple locations side-by-side, listing specific metrics (median price/m², average area, transaction counts). It distinguishes itself from sibling tools by focusing on multi-location comparison rather than single-location statistics or other operations.

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 clear context: use list_locations first to find valid names, requires at least one filter besides districts, gives an example. Does not explicitly state when not to use, but the context is sufficient to guide appropriate usage.

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

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

Annotations only state readOnlyHint=true and destructiveHint=false. Description discloses beta status, non-certified nature, data exclusions (fractional ownership, non-market deeds), token cost and refund policy, and return value composition (point estimate, ranges, confidence, as_of date). 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 core purpose first, then constraints, optional params, outputs, and caveats. Every sentence adds value, but length could be trimmed slightly 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 7 parameters, no output schema, and annotation minimalism, the description fully covers inputs, outputs, limitations, costs, and usage nuances. No gaps remain.

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 description adds crucial context: area is required due to lack of Polish floor-area source, lat/lng and parcelId are mutually exclusive, market enum clarified, includeComps default explained. This 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?

The description clearly states the tool estimates market value of an apartment using comparable transactions. It distinguishes from siblings like get_price_statistics and get_market_overview by focusing on individual unit valuation, and explicitly notes it is not a certified appraisal.

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 when-to-use/not-use conditions: requires area and exactly one of lat/lng or parcelId; optional rooms and market; warns about insufficient comparables leading to no estimate and credit refund. Also advises against direct cross-city comparisons due to as_of lag.

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

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.

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.

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

Beyond annotations (readOnlyHint=true), the description details known limitations: EU threshold exclusion, tender attribution to contracting authority seat, and the fact that absence of tenders is not evidence. This level of transparency is exemplary.

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 and front-loaded with the core purpose. Every sentence adds value, including the cost disclosure. No unnecessary words or 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?

The description covers input, sources, and limitations comprehensively given the tool's complexity and lack of output schema. It mentions category counters and recent-notice lists, but could more explicitly describe the output format or fields returned.

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 description adds substantial meaning beyond the input schema: explains aggregation behavior (location aggregates by county), teryt significance (6-7 vs 4 digits), and precedence (teryt wins). It also references list_locations for code lookup.

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 that the tool returns signals about upcoming infrastructure construction in Polish municipalities, listing three specific public sources. This distinguishes it from sibling tools that focus on transactions, demographics, or prices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to address municipalities (by location or teryt) and mentions using list_locations for codes. It does not explicitly compare with alternatives, but the tool's specialized purpose makes usage clear.

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

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.

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.

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

Beyond annotations (readOnlyHint, destructiveHint), discloses experimental (beta) status, potential for change, negative spread possibility, coverage limitations, data source differences, and as_of date issues.

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?

Long but well-organized into logical paragraphs. Every sentence provides necessary context for correct usage, though could trim some redundancy (e.g., repeated 'not additive').

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 4 parameters, enums, and no output schema, description covers all critical aspects: location resolution, data suppression, market segments, bucket behavior, and warnings. No gaps identified.

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?

All parameters are already well-described in schema (100% coverage). Description adds value by clarifying teryt vs location precedence, area bucket non-additivity, and marketType defaults, but 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 it measures the asking-vs-transaction price spread for a Polish city or county, with formula and scope. It distinguishes from siblings like get_price_statistics by focusing on spread rather than absolute prices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use (spread) and when-not-to-use (towns, non-Warszawa districts). Suggests calling list_price_spread_locations first for location validation, and explains parameter interactions (teryt wins).

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

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.

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

Beyond annotations (readOnlyHint, destructiveHint), describes experimental status, data sources, limitations (non-additive buckets, sample threshold, as_of date issues, 404 cases). Full behavioral context for a read-only query tool.

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?

Comprehensive but slightly verbose. Front-loaded with experimental warning and formula. Clear structure with caveats and parameter details. Minor redundancy (gross/top-line mentioned twice) but overall well organized.

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 3 parameters, description covers inputs, behavior (suppression, errors), limitations, and usage flow. Explains what outputs to expect (yield value or 404). Completely sufficient for an AI 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 covers 100% of parameters. Description adds crucial semantics: teryt wins over location, area buckets not additive, 5-sample minimum, and that non-covered locations return 404. Adds significant 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?

Clearly states it estimates gross rental yield for Polish cities/counties with specific formula. Distinguishes from sibling tools (e.g., list_rental_yield_locations serves as catalog). Unique purpose well articulated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when to use (estimate yield), when not (non-covered locations, warns about experimental nature). Provides alternatives: use list_rental_yield_locations first, or pass teryt. Cautions against critical workflows.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description goes beyond by detailing the two-state behavior (parcels with no match return nothing), the composition of the response (eligible area, share, source features, number of matches, snapshot date), and the cost policy. 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 well-structured and front-loaded with the core functionality. It includes necessary caveats and cost details, though slightly verbose. Every sentence serves a purpose, but some trimming could improve conciseness.

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 complexity (parcel-by-parcel breakdown, two-state behavior, multiple output fields) and lack of an output schema, the description is fairly complete. It describes all major aspects of the response and the two-state caveat, but does not mention how to interpret the share or the exact response structure.

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% (one parameter with UUID pattern and source description). The tool description adds no extra parameter meaning beyond what the schema already provides, so it is at the baseline for high coverage.

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 'Get the parcel-by-parcel agricultural land-eligibility breakdown for one transaction', specifying the verb (get), resource (breakdown), and scope (one transaction). It differentiates itself from sibling tools like get_building_breakdown and get_transaction_flood by focusing on agricultural eligibility, and includes a rationale for its use.

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 explains the tool's usefulness for due-diligence on agricultural land and cautions that absence of a match does not indicate non-agricultural status. While it doesn't explicitly list when not to use it or name alternatives, the context is clear enough for an agent to decide.

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

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.

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.

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.

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

Annotations indicate readOnlyHint=true, description adds details on data source, limitations, two-state behavior, and token cost—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?

Packs necessary information into a few sentences but is slightly verbose with elaborated context; front-loaded 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?

No output schema, but description enumerates fields returned (kind, building intent, works type, etc.) and explains limitations and cost—complete given complexity.

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?

Single parameter transaction_id has full schema description; description only adds 'after a search' context, which is minor. Baseline 3 for 100% schema coverage.

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 'Get the building-permit history for one transaction's parcels' with specific verb and resource, distinguishes from sibling tools like get_transaction_flood.

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 ('after a search to screen...'), includes exclusions (splits/merges break link, only positively resolved cases, empty result not a confirmation).

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds significant behavioral insight: the three-state coverage ('covered', 'covered_no_data', 'not_covered') and the cost/token refund policy. 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 moderately long but well-structured, front-loading the main purpose then covering coverage states and usage. Each sentence adds value, though it could be slightly more concise.

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 comprehensively details the return structure (zone data, building parameters, overlays) and the possible coverage states. Combined with existing annotations, it provides sufficient context for an agent to use the tool correctly.

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 a single parameter (transaction_id) well-described in the schema. The description adds context on usage but does not enhance parameter semantics beyond the schema, meeting the baseline score.

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 that the tool retrieves general-plan zoning for a transaction's land, detailing the specific information returned (zone symbol, name, share, building parameters, overlay areas). It distinguishes itself from sibling tools by focusing on zoning for feasibility and permitted-use questions.

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 recommends use for 'feasibility and permitted-use questions on a plot,' providing clear context. While it does not explicitly state when not to use it or compare to alternatives, the purpose is clear enough given the sibling tool set.

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

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

Annotations already set readOnlyHint=true and destructiveHint=false. The description goes further by explaining that distances are approximate, measured from boundaries, and that a null distance means no object found within the search radius (not a guarantee). It also details the two-state (null vs assessed=false) and the cost/refund behavior.

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: purpose, distance details with radii, two-state explanation, and cost. Every sentence provides essential information without 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 no output schema, the description explains all expected outputs: distances per category, the meaning of null vs assessed=false, and radius limits. The cost and refund condition are also included, making the description sufficient for an agent to use the tool correctly.

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 a clear description for transaction_id. The description adds value by specifying that the ID comes from search_transactions, search_by_area, or search_by_polygon results, which aids correct parameter selection.

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 gets a 'plot-by-plot surroundings profile for one transaction' listing distances to specific nuisance categories. The verb 'get' and resource 'surroundings profile' are specific and distinct from sibling tools like get_building_breakdown or get_demographics.

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 states it is 'useful for due-diligence on nearby nuisances' and explains the two-state system. While it does not list alternatives, the context is clear enough for an agent to select this tool for environmental-risks analysis.

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

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

Beyond the annotations (readOnlyHint, destructiveHint), the description adds significant behavioral context: cap distances per mode, two-state behavior (empty result when no stops within caps), and the cost/token refund policy. It also cautions about open feed coverage limitations.

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 moderately lengthy but every sentence adds value—purpose, output details, cap distances, two-state behavior, cost. It is front-loaded with the main purpose and structured logically, though could be slightly more concise.

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 the output logic (per parcel, per mode, distances, stop names) and empty result condition. It covers the key behavioral aspects, though it could specify the return format (array vs. object) for complete clarity.

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 a single parameter described as 'Transaction id (UUID) from a search_transactions / search_by_area / search_by_polygon result.' The tool description does not add any additional semantics beyond this.

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: 'Get the parcel-by-parcel public transport access breakdown for one transaction.' It specifies the output (nearest stop distances per mode, stop names) and distinguishes itself from sibling tools by focusing on transit access.

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 explains the two-state behavior and cost refund but does not provide explicit guidance on when to use this tool versus alternatives (e.g., get_transaction_surroundings). It implies usage for single-transaction transit queries but lacks when-not or comparison to siblings.

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

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.

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

The description supplements the annotations (readOnlyHint) with key behavioral details: experimental beta status, free usage, coverage signal nature, sorting by asking_sample_n, and diacritic-insensitive search. 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 but front-loads the beta warning and purpose. Every sentence adds value, though some phrasing could be tightened. It remains clear without unnecessary verbiage.

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 the return type (coverage signal with sample size and confidence), sorting, and cost. It covers enough for an agent to understand what the tool provides and how to use its output with get_price_spread.

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 schema covers the parameter fully (100% coverage), so baseline is 3. The description adds value by restating the min length and search behavior, and providing a concrete example ('gda' → Gdańsk). This slightly exceeds the 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 identifies the tool's function: listing cities/counties for which get_price_spread can return data. It explicitly distinguishes itself from get_price_spread ('does not compute the spread') and helps the agent understand its role as a discovery tool for valid location parameters.

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 states when to use this tool ('use this to discover valid location/teryt values for get_price_spread') and when not to ('it does not compute the spread'). It directly names the alternative (get_price_spread) and explains the optional search filter, providing clear guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds behavioral context: results are coverage signals only (sample size, confidence), sorted by rent_sample_n descending, free to use, and experimental status. 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?

Description is well-structured and concise: starts with experimental warning, then purpose, usage guidance, parameter details, and output behavior. Every sentence provides distinct value without 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 simple listing tool with one optional parameter, the description covers purpose, usage, parameter behavior, and output nature (sample size, confidence, sorted). Though no output schema exists, the description adequately informs an agent about what to expect and how to use the 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?

Schema coverage is 100% with description of 'search' parameter. Description adds value by explaining behavior: diacritic-insensitive substring search with min 2 chars, example mapping 'gda' to Gdańsk, and omitting returns full catalog.

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 lists cities/counties with rental yield coverage data, distinguishing it from get_rental_yield which computes yield. It uses specific verbs (list) and resource (cities/counties for rental yield).

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 use case: discover valid location/teryt values for get_rental_yield instead of guessing. Also clarifies it does not compute yield, directing to call get_rental_yield for actual values. Provides warning about experimental nature.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool costs 1 API token (refunded on no match), returns a list with coverage status, and details matching behavior (exact locality matching, case-insensitive, unusual spelling may miss). This is good 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 moderately long but well-structured with bullet points and examples. It front-loads the main purpose and every sentence adds value. It could be slightly more concise, but overall it is efficient.

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 complexity (4 params, no output schema, many siblings), the description is fairly complete. It explains what the tool returns (list of matching parcels with district, area, coordinates), the cost, and the usage flow. It could mention the response shape more explicitly, but it is adequate.

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 adds value by explaining the input formats and mutual exclusivity. It elaborates on the purpose of each parameter, such as the different forms for parcelId and the free-text format for q.

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 that the tool resolves a land parcel to its cadastral identity using exactly one of three input methods: parcelId, q, or lat/lng. It provides specific examples of input formats and distinguishes itself from siblings by noting that the result can be fed to 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?

The description explicitly tells the user when to use each input mode ("Exactly ONE of: ..."), mentions the cost (1 API token) and refund policy, and guides to feed the result to search_transactions. It does not explicitly state when not to use the tool, but the context is clear.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which are consistent with the description. The description adds significant behavioral context beyond annotations: it explains field provenance (notarial deed vs. computed values), how to build a permalink for sharing results, and the meaning of flood risk and landslide risk filters. It also notes that absence of a risk zone is not asserted as 'safe,' which is important for interpretation.

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 moderately long but well-structured. It starts with a clear purpose statement, then provides usage guidance, an example, permalink instructions, and field provenance. Every sentence adds value, though the permalink section could be more concise. The structure is logical and easy to scan.

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 21 parameters, 100% schema coverage, and no output schema, the description is remarkably complete. It explains what results contain (id, location coordinates) and how to use them via a shareable link. It also covers data provenance, which is critical for trust. The description answers likely questions about usage and output interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining the radius guide, the behavior of area filters, the permalink construction, and the meaning of flood/landslide risk filters. It also clarifies that 'marketType' excludes ~55% of records when used, and that 'unknown' values in filters exclude rows. These details surpass the schema descriptions alone.

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 function: 'Search real estate transactions within a geographic radius.' It specifies the domain (real estate transactions) and the mechanism (radius). It also distinguishes itself from siblings by explicitly positioning it as 'Best tool for neighborhood/osiedle searches (neighborhoods are not TERYT districts).' This sets it apart from other search tools like search_by_polygon or 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?

The description provides explicit usage guidance: it recommends the tool for neighborhood searches, provides a radius guide (0.3-0.5 km for street, 0.5-1 km for neighborhood, 2-5 km for city area), and includes a concrete example (Wrocław's Nowy Dwór). It also clarifies that area filters work for all property types and notes the exclusion of unknown market types. This gives clear context for when and how to use the tool.

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

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

Annotations provide readOnlyHint=true and destructiveHint=false. Description adds valuable behavioral context: field provenance (values from notarial deeds, computed values flagged), permalink construction, and that results are shareable. 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?

Description is front-loaded with purpose and well-structured into paragraphs. However, it is somewhat verbose, especially the permalink and provenance sections which could be more compact for a tool description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 19 parameters and no output schema, description covers usage guidance, coordinate details, data provenance, and an example. It lacks explicit return format details but states 'Returns transactions found inside the polygon with coordinates.' Sufficient for agent use.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats some schema info (coordinate order, closure) but adds little new parameter-level meaning. Additional context (provenance, permalink) is not parameter-specific.

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?

Description clearly states 'Search real estate transactions within a geographic polygon.' and distinguishes from sibling search_by_area by noting 'For quick searches, start with search_by_area instead.' It also specifies use case: 'Use for precise neighborhood/osiedle boundaries.'

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 when to use alternatives: 'For quick searches, start with search_by_area instead.' Also provides guidance on deriving coordinates from search_by_area results and specifies coordinate order and polygon closure rules.

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

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.

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

Annotations indicate readOnlyHint=true. The description adds substantial context: data notes about marketType being NULL for ~55% of records, missing transaction_date for ~1.7%, permalink construction, field provenance, and location matching only to TERYT districts. This goes well 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 comprehensive but somewhat lengthy. It is well-structured with purpose, usage notes, data quality notes, permalink, and field provenance. Front-loaded with the main purpose. A minor cut could improve conciseness, but it remains clear and organized.

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 27 parameters, 100% schema coverage, and no output schema, the description is remarkably complete. It includes data quality notes, example usage, permalink construction, field provenance, and comparisons with sibling tools. It fully prepares the agent to use the tool correctly.

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

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

Schema description coverage is 100%, so parameters are fully documented. The description adds extra context for key parameters like marketType (exclusion when used), transactionType (always specify for market analysis), and floor/rooms filters (explaining 'unknown' handling). This adds 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 Polish real estate transactions from the RCN registry, listing specific fields. It distinguishes from sibling tools like list_locations and search_by_area, specifying when to use each.

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 is provided: 'Use list_locations first to find valid location names' and 'For neighborhoods (osiedla), use search_by_area instead.' Also warns about data quality issues (marketType null, missing transaction_date) and advises to always specify transactionType for market analysis.

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