Cenogram - Polish Real Estate Data

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

Annotations already declare this as a safe read (readOnlyHint=true, destructiveHint=false), and the description adds non-obvious behavior: name-only matching with silent empty results for non-RCN names, and the aggregation rule that fractional-ownership and non-market deeds (tenders, foreclosures, subsidized sales) are excluded from price medians while transaction counts remain complete. That is exactly the kind of semantic caveat structured fields cannot convey.

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

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

Purpose, prerequisite, constraint, example and aggregation caveat are each front-loaded and every sentence carries distinct operational information. It is somewhat dense at seven sentences for what is essentially a filtered-list tool, but no sentence is filler.

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

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

For an 18-parameter tool with no output schema, the description covers the load-bearing gaps: valid input domain (RCN district names), the silent-failure mode, the mandatory extra filter, and what the compared statistics represent (market-only price aggregates vs. complete transaction counts). An agent has enough to call it correctly without guessing.

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 already documents parameter formats, including the 2-5 unique district rule, so the baseline is 3. The description goes beyond it by explaining that only RCN-flagged names match (silent failure otherwise) and that at least one additional filter beyond districts is mandatory — real constraints that affect how the agent populates the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Compare real estate statistics across multiple locations side-by-side') and immediately names the concrete outputs (median price/m², average area, transaction counts). This distinguishes it from single-scope siblings like get_price_statistics or get_market_overview without the agent needing to open any schema.

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

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

Explicitly states the cardinality constraint (2-5 districts), the prerequisite workflow ('Call list_locations(search=...) first' and use values flagged as rcn_district), and a hard precondition ('Requires at least one filter besides districts, e.g. propertyType'). It even supplies a worked example, leaving nothing to inference.

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?

Goes well past the readOnlyHint/destructiveHint annotations: it discloses that this is a beta orientation estimate not a certified appraisal, the 5-token cost with refund on no-estimate, maintenance switch-off behavior, as_of county-level freshness, and that non-market deeds are excluded from price aggregates. Rich, non-obvious 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?

Front-loads the purpose and key constraints, and most sentences carry real information. It is dense and lengthy, with some hard-to-parse clauses (the comparables-selection sentence) and a tangential closing note on price aggregates that slightly dilute the structure.

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 exists, so the description carries the return-shape burden and does: estimate per m² and per hectare, likely and wide range, confidence band, comparable count, and as_of date. Given a complex 7-param tool, this is complete enough for an agent to call and interpret results 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 already 100%, so the baseline is 3. The description nonetheless adds semantic value: that landType is caller-chosen and not inferred, that mpzpDesignation narrows the comparable set, and that area falls back to the cadastre on the parcelId path — clarifying intent beyond the field docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Estimate the market value of an undeveloped plot of land from comparable registered transaction prices near a point') and scopes it tightly ('Undeveloped land only (v1)'). An agent can distinguish this land-specific estimator from the general estimate_value sibling without opening the schema.

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

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

Provides clear usage context: address by lat/lng OR parcelId (exactly one), area required on the coordinate path, and the 'undeveloped land only' constraint. It stops short of explicitly naming alternatives (e.g., estimate_value for built property), so routing guidance is contextual rather than prescriptive.

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 declare readOnlyHint/destructiveHint, so the description carries the real behavioral burden and does so: cost of 5 API tokens with refund on failure, the no-estimate case when comparables are too few, as_of freshness lagging by county and non-comparability across cities, and exclusion of fractional/non-market deeds from price aggregates.

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 the core purpose and the appraisal disclaimer, then inputs, then return shape, then costs. Dense and mostly waste-free, though the closing note on median/average price exclusions is somewhat tangential to invoking this tool.

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

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

With no output schema, the description enumerates the return contents (point estimate, likely/wide ranges, confidence band, comparable count, as_of). Inputs, cost, failure mode, and scope limits are all covered, so an agent has everything needed to call it 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%, so baseline is 3, but the description adds genuine meaning: why area is required (no per-address floor-area source in Poland), that rooms narrows comparables to ±1, that the parcel centroid is used for parcelId, and includeComps' default/echo behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (estimate) and resource (market value of an apartment) plus the method (comparable registered transaction prices near a point). It explicitly distinguishes itself from the sibling estimate_land_value and scopes itself to apartments only.

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

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

Gives explicit when-to-use (apartments, 10–250 m²), when-not (undeveloped land → estimate_land_value), input exclusivity (lat+lng OR parcelId, exactly one), and caveats about what it does not do (no condition/floor, not a certified appraisal). Nothing about tool selection is left to inference.

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?

Goes well beyond the readOnlyHint annotation: it warns that construction-age values are estimates, not registry dates, that permit records only begin in 2016, and that 'not established' is stated explicitly rather than omitted. It also discloses the 4-token cost and the empty result for transactions with no buildings.

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 longer than average but every sentence adds necessary operational detail: what the tool returns, when to use it, data-quality caveats, and empty-result behavior. The key identifiers and usage are front-loaded, with caveats and cost after.

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

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

With no output schema present, the description covers return fields (footprint area, number of storeys, estimated total floor area, construction-age estimate), the no-buildings edge case, cost, input origin, and usage context. An agent has enough to invoke it correctly and interpret results.

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

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

Schema coverage is complete: the input schema already says transaction_id is a UUID from search_transactions/search_by_area/search_by_polygon that carries building data. The description mostly restates this, adding at most a pointer to 'the id shown on a search result'. It provides no substantial 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 opens with a specific verb and outcome ('Get the building-by-building breakdown for one transaction') and enumerates the exact fields returned (footprint area, storeys, estimated total floor area). It also explicitly distinguishes this tool from the search tools that return per-transaction building sums inline, so an agent can immediately tell what it does and what it is not.

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 gives clear when-to-use guidance: call it after a search when a result has building data and you need per-building detail, e.g. for a developed-land deed. It also contrasts it with search_transactions / search_by_area / search_by_polygon, which return sums, making the choice between sibling tools explicit.

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 cover the read-only/safe profile, but the description adds substantial extra context: an EXPERIMENTAL/beta stability warning, all-time aggregation with no date window, suppression below 5 assessed transactions, and the important caveat that absence of a mapped zone is not asserted as 'safe'. These are real behavioral traits not derivable from the structured fields.

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 beta notice is front-loaded appropriately, and severity-band calibration and suppression rules are each stated once and compactly. It is on the longer side, with the teryt-precedence rule appearing in both description and schema, but every sentence carries distinct information.

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

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

With no output schema, the description carries the burden of return semantics and does so well: it defines the severity bands via return periods, the assessed-transaction threshold, the county-level granularity, and the all-time window. The exact output shape (shares vs counts, field names) is only implied, which is the remaining gap.

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% and the parameter descriptions already state the truncation, district, gmina-candidate and 'teryt wins' rules, so the description largely restates them. It does tie the parameters to a routing decision (when to prefer the catalog lookup), but adds little syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource+scope: the share of a Polish county's real-estate transactions falling in a mapped flood-hazard zone, broken down by severity, sourced from the RCN registry. This is clearly distinguishable from sibling assets like get_transaction_flood (transaction-level) and list_flood_risk_locations (catalog). An agent can select it without opening another schema.

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

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

Gives an explicit prerequisite workflow: call list_flood_risk_locations FIRST unless the location is a known-covered major city, or pass a 4-digit county TERYT. It also spells out the alternatives (location vs teryt), the precedence rule, and the dry-run case for ambiguous gmina names, leaving nothing to inference.

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 indicate readOnlyHint=true and destructiveHint=false. The description adds important behavioral context, including data quality issues (marketType unknown for ~55%, transaction_date missing for ~1.7%) and exclusions in price aggregates (fractional shares, non-market deeds). This is valuable 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 well-structured with a lead sentence, a list of returns, and bullet-pointed notes. It is slightly verbose but each sentence adds value (data quality, price exclusions). Front-loading 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?

With zero parameters and no output schema, the description fully compensates by detailing return values and caveats. The tool is well-defined for its purpose as a broad overview, and the caveats about data quality and price calculation are critical for correct 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?

There are zero parameters, so the input schema provides full coverage. The description adds no extra meaning for parameters, but no additional documentation is needed. The description is complete and clear.

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 returns a 'comprehensive overview of the Polish real estate transaction database' and lists specific data elements (total transaction count, date range, breakdowns, top locations, price statistics). This distinguishes it from siblings like get_price_statistics 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 implies usage for high-level summary but does not explicitly state when to use this over alternatives like search_transactions or get_price_statistics. No exclusion criteria or when-not-to-use guidance is provided.

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 substantially extends the read-only/destructive annotations. It explains that categories and grades return as sets with no area proportions, covers regional coverage limitations, enumerates the four distinct lookup states with their billing/refund behavior, and adds a clear non-legal-advice caveat. No contradiction exists with readOnlyHint=true or destructiveHint=false.

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 organized into clear thematic paragraphs, one for outputs, one for routing, one for input formatting, one for result semantics, one for coverage states, and one for costs and limits. Each sentence adds necessary operational or interpretive value; there is no fluff.

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 that there is no output schema, the description carries the burden of explaining the response. It covers what is returned, how values are represented, when the data is absent, how billing and refunds behave, and what limitations apply. This is complete enough for an agent to select and invoke 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?

The schema already documents parcelId with 100% coverage, naming the natural form, dash form, and UUID. The description adds concrete examples and the exact expected notation, including the '/'-separated cadastral format and the URL-safe alternative, which is useful beyond the schema 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 opens with a specific verb and resource: it returns the official land-use and soil-quality classification for one land parcel and what it means for taking land out of agricultural use. It lists the concrete pieces of information returned and explicitly separates this tool from get_parcel_report by naming the alternative for unrelated parcel 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 gives clear when-to-use guidance: 'Use it when the question is specifically about the classification or about re-designating farmland.' It also gives explicit when-not-to-use guidance, naming get_parcel_report and explaining how that sibling includes the same classification in a broader response.

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, yet the description adds far more: 5-token cost charged even on empty results, per-page billing, periodic (not live) data with a refresh date, maintenance outages returning 'temporarily unavailable', cursor/truncation semantics, aggregate spanning all pages, pending/refused cases absent, and parcel-geometry matching gaps. This is unusually rich disclosure for a read-only 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?

It is front-loaded with purpose but then becomes a very long block, and several points are restated: the smaller-radius advice appears twice, cursor/truncated paging is explained in the description and again in the schema, and cost/pagination are revisited under 'Cost'. Much of the length is justified by tool complexity, but redundancy costs it.

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?

There is no output schema, so the description carries the full return-value burden — and it does: deduplicated list, newest-first (not nearest-first) ordering, per-case fields, the year×category aggregate with permit/notification split and volumes, the truncated flag, and error-on-timeout behavior. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, and the description largely mirrors the schema (intent shorthand, worksType, category examples). It does add semantic value the schema does not carry cleanly: the rationale for the two-year default floor at 2016-01-01, the radius-vs-paging strategy, and the category examples tied to real question shapes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a precise verb+resource+scope: 'List the building permits and works notifications ... within a radius of a point — issued decisions only'. It is immediately distinguishable from generic transaction tools by its spatial framing, but it never explicitly addresses the potentially confusable sibling get_transaction_permits, so sibling differentiation is left implicit.

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

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

It gives explicit when-to-use-each-option guidance: aggregateOnly=true for 'how many/how much' questions, a smaller radiusKm rather than paging for 'what is closest', categories/excludeCategories examples for specific question shapes, and routing for coordinates via resolve_parcel / list_parcels_in_area / user, with 'never guess them'. Alternatives and trade-offs are spelled out rather than 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?

The note explains that median/average prices exclude fractional ownership and non-market deeds, while transaction counts remain complete. This adds behavioral context beyond the readOnlyHint and destructiveHint annotations, informing agents about data quality and exclusions.

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, front-loaded with the main purpose, and uses a concise note for important exclusions. Every sentence adds value without repetition or verbosity.

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

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

For a simple read-only tool with two parameters and no output schema, the description fully covers the output (histogram) and key behavioral notes. No gaps are apparent given the tool's 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?

The input schema already provides descriptions and defaults for both parameters (bins and maxPrice). The description does not add further parameter semantics beyond what the schema covers, so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a price distribution histogram showing transaction counts per price range, distinguishing it from siblings like get_price_statistics and get_market_overview. The title 'Price Distribution Histogram' further reinforces the specific resource.

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 in Poland,' providing context but no explicit comparison to alternatives like get_price_statistics or get_market_overview. No when-not-to-use or alternative tool references are given.

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 and destructiveHint, but description adds critical context: data source (notarial deeds), coverage gaps, exclusion of fractional ownership and non-market deeds from price aggregates, and retention of transaction counts.

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 clear notes, though slightly verbose. Every sentence earns its place, providing essential context 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?

Despite no output schema, description thoroughly covers what statistics are provided, data quality, and exclusions, making it complete for usage.

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% for the single parameter, but description adds valuable behavioral details about auto-expansion and partial matching, going beyond the schema description.

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 the tool retrieves price per m² statistics for residential apartments in Poland, distinguishing it from sibling tools like search_transactions which handle other property 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?

Explicitly specifies it only covers residential units and directs to search_transactions for other property types. Also details auto-expansion for major cities and partial match behavior.

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), description discloses two-state behavior (no match ≠ non-agricultural), cost (4 tokens refunded when no eligible area), and data source freshness (updated weekly). Adds critical interpretative guidance.

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 main purpose, followed by details and important notes. Slightly lengthy but each sentence adds value; 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?

Despite no output schema, description explains response structure (eligible area, share, source features, match count, snapshot date). Combined with behavioral notes, provides full understanding for a read-only 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 100% with parameter description. Description adds context that transaction_id comes from specific search tools (search_transactions, search_by_area, search_by_polygon), aiding correct sourcing.

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?

Describes a specific action ('get parcel-by-parcel agricultural land-eligibility breakdown for one transaction') with a clear resource and scope. Distinct from sibling tools which cover other transaction aspects (flood, heritage, etc.).

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

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

States the tool is 'useful for due-diligence on land that is actually eligible/maintained as agricultural'. Provides context on when to use, but does not explicitly mention when not to use or alternative tools.

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/destructiveHint, so safety is covered, yet the description adds substantial independent context: enum meanings for protection_rank and building_restriction, that a buffer zone is reported as rank 6 and never as a statutory ban, that results describe the source of a restriction not a permitting outcome, the two distinct kinds of empty result, and a cost of 4 tokens refunded on empty results. This is unusually rich behavioral disclosure.

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

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

Purpose and scope are front-loaded, and the caveats (empty-result semantics, buffer zones, disclaimers, cost) each carry decision-relevant information. The first sentence is a long run-on packed with parentheticals, which slightly hurts readability, but almost every sentence earns its place for a tool with no output schema.

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

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

With no output schema, the description carries the full burden of describing returns, and it does so field by field (forest_distance_m, protection_rank scale, building_restriction values, protection share, named areas). Combined with empty-result semantics, disclaimers, and cost, an agent has everything needed to invoke and interpret 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?

With a single parameter and 100% schema coverage, the schema already documents transaction_id (UUID pattern, provenance from search results). The description only reinforces that it is called directly on a transaction id, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource (parcel-by-parcel nature breakdown for one transaction) and enumerates exactly what is returned: nearest forest distance and overlapping protected areas. It also distinguishes itself from get_parcel_report ('For a parcel with no transaction, get_parcel_report names the protected areas'). An agent can separate this tool from its siblings without opening a schema.

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

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

It states when to use it ('call this tool directly on a transaction id whenever forest proximity or protected-area build limits matter'), positions it in a workflow ('Use it after a search on land plots'), and routes the no-transaction case to get_parcel_report. Alternatives and conditions are explicit.

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 valuable behavioral details: the three-state coverage with honest semantics, explanation of what each state means, and cost/refund behavior. This goes 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, starting with the main purpose, then detailing output, state system, usage, and cost. Each sentence is valuable, though slightly verbose; could be tightened.

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

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

For a tool with one parameter and no output schema, the description comprehensively covers the return values (zone data, building parameters, overlays), the three-state coverage, usage guidance, and cost. It leaves no critical gaps for an agent to understand 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?

The input schema has 100% description coverage for the single parameter (transaction_id), so the schema already provides meaning. The description does not add further parameter-specific information, meeting the baseline of 3.

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 general-plan zoning for a transaction's land, specifying the output details (zone symbol, name, share, building parameters, overlay areas) and the three-state coverage system, making it distinct from any sibling tools.

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

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

The description explicitly recommends use for feasibility and permitted-use questions on a plot, and mentions cost/refund conditions. While it does not list alternatives or when-not-to-use, the context is clear given no sibling overlaps.

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, so the tool is read-only enrolled. The description adds significant transparency: it clarifies that access_indicator is geometric evidence, not legal access, explains the TWO-STATE semantics for null distances and assessed=false, and warns about the 3km radius being a traffic-nuisance proxy instead of access signal. This is far beyond the annotation hints.

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 detailed and comprehensive, covering semantics, use cases, and caveats. It is somewhat long but each sentence adds value, and key points are front-loaded (what it does, then access_indicator semantics, then measurement radius). No fluff; it is appropriately structured for such a multi-faceted tool.

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 (multiple distances and attributes per plot, a nuanced indicator, and radius rules), the description is exceptionally complete. It explains all output fields, the meaning of null/absent values, the assessed flag, cost and refund conditions, and how to obtain the transaction_id. With no output schema, this description carries the full burden and succeeds.

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% for the single parameter, with the schema already explaining that it is a transaction ID from search results. The description reinforces this by referencing the same search tools. It adds no new syntax but the parameter is self-explanatory; the baseline for high coverage is 3, and the description's reinforcement justifies a 4.

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: retrieving plot-by-plot road-access evidence for a specific transaction. It specifies the exact data returned (distances to nearest roads, management category, functional class) and references sibling tools (get_parcel_report) to delineate its unique scope. It is specific with verb and resource, making it easy to distinguish from other transaction-related tools.

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

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

The description explicitly explains when to use this tool: 'Use it for a specific transaction to judge how its land sits relative to the road network.' It also differentiates from get_parcel_report, noting that the latter includes a one-line summary, implying this tool is for detailed evidence. No explicit exclusions but strong contextual 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, so safety is covered; the description goes well beyond that by disclosing the token cost (4, refunded when no data), the two-state semantics ('absence of data is never an assertion of safety'), and the interpretive caveats that mining-terrain location is approximate/advisory and that a groundwater reservoir's extent alone imposes no restriction. These are exactly the behavioral traits annotations cannot express.

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

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

The purpose and dimensions are front-loaded, then caveats, alternative routing, and the two-state/cost note follow in a logical order. It is dense and the enum parentheticals are long, but nearly every clause carries information an agent would otherwise have to guess; only mild trimming would be possible.

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

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

For a single-parameter read tool with no output schema, the description covers everything an agent needs: the return shape (per-plot shares plus per-object lists), the meaning of each enum value, the advisory status of the data, the empty-result semantics, cost, and the sibling fallback. Nothing material is missing.

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

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

Schema description coverage is 100% and the single transaction_id parameter is fully documented in the schema (UUID pattern plus its source, a search_transactions/search_by_area/search_by_polygon result). The description adds no additional meaning about the parameter itself, so the 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 names a specific verb+resource (get parcel-by-parcel subsurface breakdown for one transaction), enumerates the two dimensions (mining terrains, groundwater reservoirs) and the exact fields returned, including status and mineral-class enums. It also explicitly routes the no-transaction case to the sibling get_parcel_report, so an agent can distinguish it from the 30+ siblings without opening a schema.

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

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

It states when to use it ('for a specific transaction to see whether its land overlaps a mining terrain or a major groundwater reservoir') and names the alternative for the other case ('For a parcel with no transaction, get_parcel_report lists the same terrains and reservoirs'). It even warns the agent about the two-state behavior and cost, which is decision-relevant 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 only provide readOnlyHint and destructiveHint. The description adds significant behavioral details: use of open GTFS data, distance caps per mode, two-state absence handling, token cost and refund. These go well beyond annotation information.

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 a single paragraph with no wasted words. It front-loads the core purpose, then provides necessary details in a logical order: process, caps, edge cases, cost.

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 input (one parameter) and no output schema, the description fully covers use case, distance caps, absence behavior, token cost, and refund. It leaves no ambiguity about what the tool returns or how it works.

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?

Only one parameter (transaction_id) with schema description covering its source. The tool description does not add further meaning beyond the schema. Schema coverage is 100%, 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 it gets 'parcel-by-parcel public transport access breakdown for one transaction,' specifying the resource (transaction), action (get), and scope (parcels, modes, stops). It distinguishes itself from sibling transaction tools by focusing on transit details.

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 when to use (getting transit access for a transaction) and details behavior like two-state returns and cost. It lacks explicit when-not-to-use or alternative tools, but the specificity among many siblings provides implicit 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, but the description adds substantial behavioral context: the beta/experimental status, free credit cost, that results are coverage signals with assessed sample size and confidence (not a computed share), and that they are sorted by assessed_sample_n descending. This goes well beyond annotations and tells the agent exactly what to expect from the response.

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 front-loaded with the beta warning and primary purpose, then flows logically into usage guidance, parameter details, return semantics, and cost. Every sentence carries meaningful information with no redundancy. For a tool with one optional parameter, the length is justified and well-structured.

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 a single optional parameter, no required fields, no output schema, and annotations already covering safety, the description fills all remaining gaps: it explains the return format (coverage signal with sample size and confidence), the sorting order, the credit cost, and the proper use case. An agent would have everything needed to call this tool correctly without further inquiry.

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 already provides a complete description for the single 'search' parameter, including diacritic-insensitivity, min length, and an example. The description repeats this information almost verbatim, adding no new semantic detail. With 100% schema coverage, the baseline of 3 is appropriate; the description doesn't enhance parameter 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 opens with a precise verb+resource: 'List the counties for which get_flood_risk can return data', and immediately distinguishes itself from get_flood_risk by noting it is coverage signal only, not actual exposure. This makes it clearly distinct from sibling tools like list_locations or get_flood_risk.

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: 'Use this to discover valid location/teryt values for get_flood_risk instead of guessing names.' It also clarifies that each entry is coverage signal only and directs to call get_flood_risk for actual exposure, effectively signaling when not to use it. The optional search filter and sorting behavior are also described, giving an agent complete routing 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 only cover readOnlyHint/destructiveHint, and the description goes far beyond: token pricing (2 vs 5 tokens), truncation as the normal case on outlines, cursor paging vs no paging, identity gating of parcel_id by account tier, two distinct coverage gaps, refunds on empty street/number pages, and hard limits (500 km², 12.6 km, 500 vertices). This is unusually rich behavioral disclosure.

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

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

Purpose and scope are front-loaded well, but the body is extremely long and repeatedly restates schema text (street whole-word matching, buildingNumber exact-match rules, minArea scope requirements). For a 14-parameter tool the length is partly justified, yet a meaningful share of sentences do not add information beyond the schema.

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 14 parameters, no output schema, and real complexity around coverage and truncation, the description is complete: it explains both answer shapes, the coverage block, truncation semantics, error behavior, and warnings against misreading short results. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond it: the framing that an area must be named in one of five ways, that teryt wins over location, that bbox and circle are mutually exclusive, and that geometry cannot combine with street/minArea. Some content duplicates the schema (street matching rules appear in both), limiting it to a 4 rather than a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource ('List cadastral parcels in an area — the land plots themselves') and immediately disambiguates from the transaction tools. It also names five distinct sibling tools and the exact case each one covers, so an agent can route without opening any schema.

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

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

Explicitly routes between siblings (search_by_area, search_by_polygon for deeds/prices; search_parcels by id prefix; resolve_parcel for address→parcel; get_parcel_report for a single parcel). It also states when parameter combinations are refused (bbox+circle, minArea/street on outlines, non-narrow scopes) rather than leaving the agent to discover it.

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?

Beyond the readOnly/non-destructive annotations, it discloses genuinely non-obvious behavior: the tool returns transactions despite its name, every result carries a shareable permalink constructible from the id/Location lines, and computed/approximated values are flagged inline. This is exactly the extra context annotations cannot supply.

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

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

Purpose and the name caveat are front-loaded, and each block (sibling routing, radius guide, example, permalink, provenance) earns its place for a 27-param tool. The permalink paragraph is dense, but its detail is functional rather than padding.

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?

There is no output schema, yet the description covers what is returned (transactions, deeds, prices), how to interpret computed vs deed-sourced fields, and how to build a permalink from results. For this level of parameter complexity the coverage is complete.

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

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

Schema coverage is 100%, so the schema already documents all 27 parameters (baseline 3). The description still adds cross-cutting meaning: that minArea/maxArea apply across all propertyType values and an extra radius band (2-5 km for a city area) beyond the schema text. Marginal but real added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Search real estate transactions within a geographic radius') and immediately clarifies the misleading name by asserting it returns TRANSACTIONS/deeds, not parcels. It explicitly names the sibling it is not (list_parcels_in_area), so an agent can disambiguate without opening a schema.

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

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

Gives explicit when-to-use context ('best tool for neighborhood/osiedle searches'), names the alternative for the parcel case, and provides concrete radius guidance for streets/neighborhoods/city areas plus a worked example. Nothing is left to inference.

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 annotations, it discloses rich behavior: return contents (transactions with coordinates), field provenance (RCN notarial deed by default, with computed/approximated values flagged inline), and the exact permalink construction rule. These are substantive behavioral traits the schema does not carry.

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 the critical scope/reverses-name warning in the first sentence, then routing guidance, then geometry rules and the permalink recipe. Efficient overall, though the permalink paragraph and field-provenance note make it long enough that some sentences are dense.

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

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

For a 24-parameter tool with no output schema, it covers the essentials: return contents, geometry requirements, source/approximation caveats, and routing. It leans on the fully-covered schema for filter semantics, so it is largely complete, though result-format/pagination details remain unstated (the 50-row display cap lives only in the schema).

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

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

Schema coverage is 100%, so all 24 parameters are already documented. The description restates the polygon coordinate convention ([longitude, latitude], closed ring) that the schema already specifies and adds a worked example, but contributes little new semantics beyond the structured fields. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Search real estate transactions within a geographic polygon') and immediately disambiguates against the misleading name by noting it returns TRANSACTIONS/notarial deeds, not land plots. It explicitly names the sibling (list_parcels_in_area) that returns the plots themselves, so an agent can tell the two apart without opening schemas.

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 ('Use for precise neighborhood/osiedle boundaries') and when-not ('For quick searches, start with search_by_area instead'), plus a bridging hint that coordinates can be estimated from search_by_area results. Alternatives are named with the condition that selects them.

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, and the description goes well beyond them: it discloses corpus coverage limits (national but not complete, not live), how to read an empty result, that a corpus_coverage block is returned, and that the call is free of token cost.

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 the core behaviour and the sibling routing in the first two sentences. The coverage paragraph is long but each sentence carries non-obvious operational guidance; only the trailing 'Free' note is slightly expendable.

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 exists, so the description correctly takes on the burden of describing what comes back (district, area, GPS coordinates, corpus_coverage block). Combined with the coverage caveat and the fallback to resolve_parcel, an agent has everything needed to call and interpret it 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%, so the baseline is 3, but the description adds real meaning the schema does not: the match is on the ID PREFIX only, never on an area, plus a concrete example prefix. The limit parameter is left entirely to 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?

States a specific verb (search) and resource (land parcels) and immediately constrains the match semantics to ID prefix. It names the two sibling tools it is not (list_parcels_in_area, resolve_parcel), letting an agent distinguish it without opening any schema.

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

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

Explicit when-to-use ('finding exact parcel IDs', 'searching transactions nearby') and when-not, with a named alternative for each wrong case: list_parcels_in_area for places/shapes and resolve_parcel for address/coordinate/locality lookups. Also covers how to interpret an empty result.

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