Cenogram - Polish Real Estate Data

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

Annotations already cover read-only/non-destructive behavior, and the description adds meaningful behavioral context beyond that: name-only matching, silent no-data outcomes, exclusion of non-market transactions from price aggregates, and clarity that counts/coverage remain complete. This is exactly the kind of extra context an agent needs.

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 compact and front-loaded: purpose, constraints, example, then data-quality note. Every sentence contributes either to correct usage or behavioral understanding, with no redundancy or 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 most critical operational pitfalls: name matching, required filter, and which data is excluded. It does not describe the response shape or failure handling, but the given context is strong and likely sufficient for an agent to 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how the districts parameter must be populated (RCN names from list_locations), that an additional filter is required, and by giving a concrete example. This is enough to justify a 4, though not a 5 since most parameter details are already in 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 uses a specific verb ('Compare') and resource ('real estate statistics across multiple locations side-by-side') and names the exact metrics (median price/m², average area, transaction counts). It clearly differentiates from the many sibling get_* tools by emphasizing the multi-location comparison aspect.

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 guidance: call list_locations first, use names flagged as rcn_district, and warns that other names silently return no data. It also states the hard requirement of at least one filter besides districts and provides a concrete example, leaving little 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 already indicate readOnlyHint=true and destructiveHint=false. The description adds transparency about beta status, token cost, refund on no estimate, data freshness lag, and exclusion of fractional shares, providing a complete picture of 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 with sections for purpose, constraints, parameters, returns, and disclaimers. It is slightly verbose but front-loads the main purpose effectively.

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 (7 parameters, no output schema), the description covers all aspects: what it returns, how it works, limitations, token cost, and edge cases like insufficient comparables. It is comprehensive.

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 value by explaining why area is required (no floor-area source in Poland), the mutual exclusivity of location parameters, and the effect of optional parameters on narrowing comparables.

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 from comparable transactions. It distinguishes itself from a certified appraisal and from sibling tools like search_transactions or get_price_statistics by focusing on estimation.

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 when to use (orientation estimate) and when not (not a certified appraisal). It also specifies required parameter (area) and mutually exclusive location parameters (lat/lng or parcelId), 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?

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 already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: query results include all parent levels, a name resolves to county level while teryt wins when both are given, and cost is 1 token. This goes well beyond the annotation signal.

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

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

The description is long but each sentence earns its place: source, indicator scope, addressing rules, hierarchy behavior, and filtering options. Critical constraints are front-loaded, and no filler or repeated schema text is present.

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 flexible read-only lookup with six optional parameters and no output schema, the description covers everything an agent needs: what data comes back, how to specify a location, how to get finer geographic levels, how to filter by category, and how to request a time series. The absence of an output schema is compensated by the explicit parent-level return behavior.

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 genuine value: it explains teryt digit-level resolution, the 7th digit unit-type meaning, the precedence of teryt over location, parent-level expansion, and the year vs yearFrom/yearTo semantics. This materially helps an agent choose and combine parameters correctly.

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+resource: it returns demographic, economic, housing, and other local statistics for a Polish location from GUS BDL, with ~50 indicators across 11 categories. This distinguishes it clearly from the many transaction, parcel, and pricing siblings.

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 practical routing guidance: use list_locations to find TERYT codes, pass a 6/7-digit teryt for gmina-level data, and note that neighborhoods/osiedla are NOT addressable here. It doesn't explicitly contrast with sibling tools like compare_locations or get_market_overview, but the domain is clear enough that an agent can infer when this tool is appropriate.

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 and destructiveHint, but the description adds substantial behavioral detail: experimental beta status, suppression below 5 transactions, county-level coverage, and the critical caveat that absence of a mapped zone is not asserted as 'safe'. These go well beyond the annotations and are essential for correct use.

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

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

The description is long but well-structured, starting with the beta warning, then the core purpose, severity bands, addressing, aggregation, suppression, coverage, and final usage guidance. It is front-loaded with the most critical info and each sentence carries purpose, though it could be slightly more compact without losing essential details.

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 (severity bands, addressing nuances, suppression), the description covers the essential information. It explains severity bands with return periods, aggregation over all history, suppression threshold, and coverage. It does not explicitly describe the output format, but the purpose statement implies a report with severity breakdown, and there is no output schema to require it. Overall, it is sufficiently 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% with detailed parameter descriptions, so baseline is 3. The description adds extra nuance: district codes resolve to the county, teryt wins when both are provided, and location inputs like a town within a powiat may 404, suggesting to check the catalog or use teryt first. This adds meaningful guidance 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 explicitly states the tool reports the share of a Polish county's real-estate transactions in flood-hazard zones, broken down by severity, from the RCN registry. It uses a specific verb ('report') and resource ('share of transactions in flood-hazard zone'), and clearly differentiates from siblings by mentioning the RCN registry and severity 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 gives explicit guidance on when to use the tool and when to use alternatives: it instructs to call list_flood_risk_locations first unless the location is a known major city, or to pass a 4-digit TERYT. It also explains the addressing rules (location vs teryt, teryt wins) and notes experimental beta status, advising not to build 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?

The description goes far beyond the readOnlyHint/destructiveHint annotations by disclosing the rolling 12-month window, EU-threshold limitation, seat-of-authority attribution caveat, the difference between category counters and the recent-notice list, and the warning that absence of tenders is not evidence of no investment. These are material behavioral limitations an agent must know before reporting results.

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 the length is justified by the data-source caveats and usage rules that cannot be safely omitted. It is front-loaded with the core purpose, then moves through addressing, limitations, and cost in a logical order, though some parameter details are redundant with 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 the tool's complexity and the absence of an output schema, the description does a good job covering data sources, aggregation semantics, and known caveats. It references output elements like 'category counters' and 'recent-notice list' without fully specifying the return shape, but the essential interpretive context is present.

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 input schema already explains teryt formats, aggregation behavior, and the precedence rule. The description largely repeats these points rather than adding new parameter-level meaning; its only additional value is pointing to list_locations for finding codes.

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 detects signals that a Polish municipality is about to build infrastructure, listing exact infrastructure types. It names the three data sources, making the tool's scope concrete and clearly distinct from the many transaction-focused 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?

It gives explicit usage context: address by location or teryt, with teryt taking precedence, and directs the agent to list_locations for finding codes. It also tells the agent to state known limits when reporting results. It does not explicitly name alternative tools or exclusions, but no sibling directly overlaps this tool's purpose.

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?

Beyond the readOnlyHint/destructiveHint annotations, the description explains per-section state semantics (covered, covered_no_data, not_covered, not_computed), billing and refund behavior, partial-report behavior, and the buildings construction-age estimate caveat with its 2016 data limitation. There is 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?

Though long, every paragraph earns its place: contents, ID formats, section states, the buildings estimate caveat, usage preference, and billing. The most important one-line definition is front-loaded, with supporting detail organized clearly afterward.

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 is remarkably complete. It tells the agent what sections to expect, how each section's state should be interpreted, what gets refunded, what a partial report means, and what the token cost is. An agent can confidently select and invoke this tool without additional information.

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 describes parcelId at 100% coverage, so the baseline is 3. The description adds value by giving concrete accepted forms ('142907_2.0014.342/5', the '-' form, or the internal UUID from a search/resolve result) and by connecting ID resolution to resolve_parcel. This goes slightly beyond the schema without being redundant.

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: 'The whole dossier for one land parcel in a single call.' It then enumerates exactly what the report contains, including core parcel data, enrichment layers, transaction history, price context, and municipal context. This clearly distinguishes it from sibling per-layer tools such as get_flood_risk or get_transaction_roads.

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 explicit routing guidance: 'Prefer this over calling the per-layer parcel tools one by one' and 'Use resolve_parcel first when you only have an address, a coordinate, or a locality + number.' This tells the agent exactly when to use this tool versus alternatives.

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 only provide readOnlyHint and destructiveHint, so the description carries the burden of behavioral disclosure. It goes well beyond annotations by disclosing beta instability, negative spreads as valid results, minimum sample suppression, 404 behavior for unresolvable locations, approximation due to different sources, and non-additive area buckets. 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 dense and long, but the complexity of the tool justifies much of it. The most critical information (formula, negative-spread validity, address resolution) is front-loaded, though the single prose block could be tightened with headings or bullets without losing content.

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

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

For a complex endpoint with no output schema, the description covers essentially all invocation-critical behavior: resolution rules, error cases, sample thresholds, comparability limits, and market segments. The only notable gap is that it never describes the response shape or fields, which matters more because there is no output schema to fill that 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 coverage is 100%, so the baseline is 3, but the description adds substantial meaning: TERYT precedence over location, 4-digit vs 6-digit resolution and truncation behavior, non-additivity of areaBucket, and how marketType narrows both asking and transaction sides. These semantics are not inferable from 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 ('Measure') and resource ('asking-vs-transaction price spread') plus the exact formula. It clearly defines the scope (Polish city or county) and distinguishes this from sibling price tools like get_price_statistics or get_price_distribution.

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 explicitly tells the agent to call list_price_spread_locations first or pass a 4-digit TERYT, and warns against passing towns inside larger powiaty, non-Warszawa districts, or osiedla because they 404. It also explains marketType selection and warns that cities with different as_of dates are not comparable.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral context: experimental beta status, may change/withdraw, methodology, suppression when samples <5, non-additive area buckets, market-based median exclusions, and approximation across data sources. It also discloses the 404 behavior for invalid locations. This goes far beyond what annotations provide.

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

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

The description is long but every sentence earns its place. It is front-loaded with the beta warning and definition, then flows logically into methodology, limitations, parameter specifics, and edge cases. No filler or redundancy; the density is justified by the tool's complexity.

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

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

The description covers most aspects an agent needs: scope, methodology, limitations, error conditions, and parameter semantics. However, it does not explicitly describe the output format (e.g., JSON fields, as_of date, yield value), which is a gap given there is no output schema. It mentions 'result is suppressed' and 'as_of dates' but does not state the return structure. This is a minor but notable omission.

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 meaning: it explains teryt resolution (4-digit county, 6-digit dzielnica for Warszawa, truncation for longer codes), location name resolution (county-level cities, Warszawa districts, delegatura to parent county), and the non-additivity of areaBucket. It also gives concrete examples. This is far more than 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 states the specific action ('Estimate the gross rental yield') and the exact resource (Polish city or county) with a clear formula. It distinguishes itself from siblings by computing a derived metric, and explicitly notes it is gross and top-line only. The purpose is unmistakable and unique among the 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 provides explicit when-to-use guidance: call list_rental_yield_locations first or pass a 4-digit county TERYT unless the location is known. It also gives clear exclusions: towns inside larger powiats, non-Warszawa districts, and osiedla will 404. It explains the teryt-vs-location precedence and warns about comparability across as_of dates. This is comprehensive usage routing.

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 provide readOnlyHint and destructiveHint, but the description adds substantial behavioral details: the two-state behavior (no return when no flood zone, with warning that absence is not safety), the cost structure (4 tokens, refunded if no flood data), and the exact data returned (worst hazard category, type, share, full per-scenario list).

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 three paragraphs: main purpose, usage guidance, and edge case with cost. It is moderately long but front-loaded with core functionality. Could be slightly more concise but earns a 4.

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 tool has no output schema, but the description comprehensively explains returned data (category, type, share, per-scenario list) and the two-state behavior. For a single-parameter tool, this is fully 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% with the single parameter having a clear description. The tool description repeats but does not add new information beyond what the schema provides. Baseline 3 is appropriate as schema does the heavy lifting.

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 flood-hazard breakdown for one transaction' with a specific verb and resource. It distinguishes from siblings by noting that search_transactions surfaces inline flood_risk, while this tool splits it into parcels, and search_by_polygon lacks inline flood data.

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 on when to use: 'Use it after a search when a result shows flood_risk.' It also clarifies that search_transactions and search_by_area provide inline flood_risk, while search_by_polygon does not, providing clear context for alternatives.

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 important behavioral details: TWO-STATE (returns nothing if no listing), indicative data caveat, and cost/token refund policy, 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?

Well-structured with purpose first, then usage guidance, then caveats. Slightly verbose with the TWO-STATE explanation and disclaimer, but each sentence adds value.

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

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

Despite no output schema, description completely explains output structure (per parcel: status, share, individual entries with fields), intended use case, limitations, and cost. No gaps for a getter 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?

Only parameter transaction_id is fully covered by schema (100%), but description provides crucial context: it must come from a search result (search_transactions/search_by_area/search_by_polygon), adding meaning beyond the schema's format constraint.

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 the resource 'parcel-by-parcel heritage-listing breakdown for one transaction', differentiating it from sibling tools like search_transactions which only surface inline heritage status.

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 when a result shows a heritage listing'), provides exclusions (search_by_polygon does not include heritage inline), and clarifies that absence of detection is not 'not listed'. Also includes cost and refund 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?

Annotations indicate read-only and non-destructive. Description adds that intersection means overlap, not that the parcel is a landslide; two-state behavior (empty return when no data); cost of 4 tokens refunded when no data. 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 thorough but well-structured. Front-loaded with purpose, then details, usage guidance, and cost. Each sentence adds value, though slightly lengthy. Could be trimmed slightly but still 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 one parameter and no output schema, the description covers all needed context: what the tool does, return data details, when to use, behavioral nuances, and cost. Complete for 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?

Only one parameter with 100% schema coverage. Description adds context that the ID comes from search results, but schema already specifies pattern and description. Baseline 3 is appropriate as no extra semantics beyond what schema provides.

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

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

Clearly states it gets a parcel-by-parcel landslide-hazard breakdown for one transaction. Distinguishes from siblings by noting that search_transactions and search_by_area surface worst-case inline, while this tool splits into parcels. Also notes that 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 say to use it after a search when a result shows a landslide risk. Describes when not to expect results (no mapped zone returns nothing, not a safety assertion). Also mentions cost and refund conditions.

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 gives extensive behavioral disclosure beyond annotations: it clarifies that an empty result is never a guarantee of no restrictions, distinguishes between 'no parcels checked' vs 'no reference data,' and explains that the output describes the source of restrictions, not permitting outcomes. It also states the cost (4 tokens) and refund behavior. No contradiction with readOnlyHint=true.

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 core purposeтные and then provides rich semantics. However, it is quite long and includes details like exact protection ranks and the cost that could be presented more concisely or moved to an output schema. Still, each sentence adds meaningful decision-relevant 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 only one parameter and no output schema, the description is remarkably complete: it explains input provenance, output meaning, rank semantics, empty-result interpretation, and the source-vs-outcome limitation. It lacks only a brief note about the exact response format, but the semantic coverage is strong.

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 is only one parameter and schema coverage is 100%; the schema already names it as a UUID from search results. The description adds the context that the id comes from search_transactions or similar tools, but this is minimal 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 opens with a specific verb and resource: 'Get the parcel-by-parcel nature breakdown for a single transaction.' It clearly enumerates what the tool returns (forest distance, protection rank, overlap share, named areas) and distinguishes itself from search tools by noting that 'search results do not carry a nature signal.'

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 explicit when-to-use guidance: 'call this tool directly on a transaction id' when forest proximity or protected-area due diligence matters, and it excludes what the tool is not (not legal advice, not about permitting outcomes). It does not name a specific sibling alternative, but it clearly differentiates from the search workflow.

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 the safety profile is covered. The description adds critical behavioral details: that permits are only held after a decision, outcomes are not included, notifications only if accepted, pending cases are not held, and the TWO-STATE behavior (empty result ≠ no record). This is far beyond baseline and very helpful. 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 lengthy but each sentence adds value: data source, data items, usage context, matching limitation, data completeness, TWO-STATE. It is structured in paragraphs and front-loaded with the essential purpose. Slightly verbose but not wasteful.

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 the tool has only one parameter, is a read-only query, and has no output schema, the description covers all necessary aspects: what is returned, what is not, when to use, and common pitfalls. It is fully complete for an agent to invoke 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 schema already explains transaction_id well. The description reinforces that it's from a search result but doesn't add much beyond that. 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 states a specific verb ('Get') and resource ('building-permit history for one transaction's parcels'), and clearly distinguishes it from the sibling tools like get_transaction_planning (which likely deals with planning permissions) and get_transaction_farmland (which is about farmland). It also names the registry and data coverage since 2016. This is clear 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?

The description explicitly tells when to use it: 'Use it after a search to screen what has been built or approved on the transaction's land.' It also notes that it should be used alongside a search result, implying that a transaction_id must come from prior search. The description also warns about the matching limitation (current identifier, so splits/merges break the link). This is strong 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 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?

The description goes well beyond the readOnly/destructive annotations by disclosing the two-state behavior (returns nothing when there is no overlap), the advisory nature of mining-terrain intersections rather than legal determinations, and the fact that groundwater extent alone imposes no restriction. It also discloses the 4-token cost and refund condition, which is not visible anywhere else.

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

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

The description is long, but the length is earned: there is no output schema, so the return structure and critical legal/cost caveats must be spelled out. It is front-loaded with the main function, then layers detail and caveats in a logical order, though some phrases 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?

Without an output schema, the description fully compensates by enumerating the per-plot fields, statuses, mineral classes, per-object lists, and the empty-result behavior. It also covers the advisory nature, the non-restriction of groundwater extents, and the alternative tool, leaving an agent with everything needed to call 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?

Schema coverage is 100%, with transaction_id already documented as a UUID from search results. The description confirms the parameter is a specific transaction ID but does not add new parameter-level meaning 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?

The description opens with a specific verb and resource: 'Get the parcel-by-parcel subsurface breakdown for one transaction across two dimensions: mining terrains and major groundwater reservoirs.' It clearly differentiates itself from siblings by naming get_parcel_report as a shallower alternative and by scoping to a single transaction.

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 explicitly says 'Use it for a specific transaction to see whether its land overlaps a mining terrain or a major groundwater reservoir, and the per-object detail,' and it contrasts with get_parcel_report's one-line summary. This gives the agent a concrete selection rule among many transaction-sibling 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 declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: distances are approximate, measured from plot boundary, 0 means touching/overlapping, fixed search radii per category, only overhead high/extra-high voltage lines covered, and the two-state null/assessed=false semantics. It also discloses cost and refund conditions. This is exemplary transparency.

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 dense but every sentence earns its place: scope, categories, radii, boundary semantics, two-state interpretation, and cost. It is front-loaded with the core purpose. Slightly long, but the complexity of the two-state semantics and per-category radii justifies the length.

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

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

For a read-only tool with one parameter, no output schema, and rich annotations, the description covers everything an agent needs: what is returned, how to interpret edge cases, what is not covered, and cost. The absence of an output schema is compensated by the detailed description of the distance semantics and two-state values.

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 single parameter (transaction_id) is fully described in the schema with a UUID pattern and provenance. The description adds context by implying the transaction must come from a search result, but the schema already says that. Baseline 3 is exceeded slightly because the description reinforces the source of the ID and the cost implications.

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

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

The description states a specific verb ('Get'), a precise resource ('plot-by-plot surroundings profile for one transaction'), and enumerates the exact categories of nuisances covered. It clearly distinguishes itself from sibling tools like get_infrastructure_signals or get_transaction_roads by focusing on environmental nuisances and distances.

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 when to use it ('useful for due-diligence on nearby nuisances'), and provides detailed search-radius semantics. It also explains the two-state interpretation (null vs assessed=false), which is critical for correct usage. While it doesn't name a specific alternative tool, the scope is so clearly defined that an agent can route correctly.

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 already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral details beyond annotations: two modes, precedence rules, that it returns administrative units only, RCN district handling, and the output (TERYT codes, parent unit, follow-up calls). It doesn't mention errors or rate limits, but for a read-only tool the added context is substantial.

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 well-structured with numbered modes and clear separation. Every sentence adds value, such as the street clarification and the note on RCN districts. It front-loads the two modes and prioritizes key behavior. A slight trim could be made, but it remains efficient for the complexity.

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

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

Given the tool's complexity (hierarchy, two modes, output usage), the description is complete. It explains what the tool returns (TERYT codes, parent, follow-up calls), what it does not (streets), and how results feed into other tools. With no output schema, the description covers return semantics adequately, leaving no critical gaps for an agent 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% with detailed parameter descriptions (parent code lengths, search case-insensitivity). The description reinforces and extends this: explains precedence when both are provided, provides concrete examples (e.g., 'Wałcz'), and links parameters to usage outcomes. This adds value beyond the schema's literal definitions.

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 via TERYT hierarchy or name search, returning TERYT codes for use in other tools. It distinguishes itself from sibling location tools by focusing on administrative units and explicitly stating it never returns streets. The verb 'browse' and resource 'locations' are specific, and it differentiates from list_*_locations siblings by covering the general hierarchy.

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

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

The description provides explicit guidance on when to use each mode: 'Use location for quick city searches, teryt for precise administrative filtering' and explains parent precedence. It also names alternative tools and conditions, e.g., 'to search for parcels on a street, pass the name straight to list_parcels_in_area as street='. This leaves no ambiguity about selection.

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: truncation is the norm for outlines, coverage gaps (two separate ones) are explained, token costs differ between light and outline calls, paging via cursor, and the fact that empty answers may still be valid. It also explains the gating of parcel_id by account type. All of this goes far beyond the annotations and materially helps the agent reason about results.

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 very long, but it is well-structured with clear sections (naming the area, shapes of answer, truncation, coverage, limits) and front-loaded with the core purpose. Every sentence earns its place given the tool's complexity (14 parameters, multiple modes, edge cases). It is not concise, but it is appropriately sized and organized, so it earns a 4 rather than a 5.

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 14 parameters, no output schema, and multiple pricing/paging modes, the description is remarkably complete. It covers return shapes, truncation semantics, coverage limitations, token costs, paging, and parameter interactions. An agent has everything needed to call this tool correctly and interpret results, including edge cases like refunded tokens and suggestions on empty pages.

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 massively enriches parameter semantics. It explains the five ways to name an area and their interactions (e.g., teryt wins over location), the exact matching rules for street (whole-word, accent-insensitive, nominative only), the compound-number behavior for buildingNumber, and the scope requirements that apply to several parameters. This is far beyond what the schema provides.

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

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

The description opens with a crisp, specific statement: 'List cadastral parcels in an area — the land plots themselves, NOT transactions.' It immediately distinguishes itself from siblings by naming alternatives for deeds/prices, id lookup, address resolution, and full reports. An agent can tell exactly what this tool does and how it differs from every related tool.

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 routes to alternatives: 'For deeds and prices in an area use search_by_area or search_by_polygon instead. To look up a parcel by an id prefix use search_parcels...' It also gives detailed when-to-use guidance for each area-naming method, including constraints like 'a bbox and a circle cannot be combined' and scope requirements for minArea/street. No ambiguity remains about when to pick this tool or a sibling.

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 already mark the tool read-only and non-destructive, and the description adds rich behavioral context beyond that: exact case-insensitive matching, ambiguous-name behavior, the not_covered vs not_computed distinction, truncation, corpus coverage, and the fact that it costs no tokens. This is exactly the kind of operational nuance an agent needs.

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

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

The description is long, but the material is dense and genuinely relevant: matching semantics, coverage caveats, and mode differences. It is front-loaded with the core purpose and input modes. A little redundancy remains around the not_covered explanation and the street-address exclusion, so it is not maximally 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?

Despite having no output schema, the description covers what a successful result looks like, truncated responses, coverage blocks, failure semantics, and how the tool fits into a larger workflow. For a tool with four optional parameters and no required ones, all essential selection and interpretation information is present.

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 goes well beyond the schema: it explains the slash vs dash parcelId forms, that q accepts gmina or obręb names with exact case-insensitive matching, that lat/lng must be a point inside the parcel, and what each match mode returns. These are semantically important details not in 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 first sentence states a specific verb and resource: 'Resolve a land parcel to its cadastral identity', and the three input modes make the tool's job unambiguous. It also differentiates from siblings by explicitly routing street addresses to list_parcels_in_area and sale-history lookups 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 gives explicit when-to-use guidance ('Use this to turn an address point, a coordinate, or a locality+number into a concrete parcel id') and names the follow-up tool (search_transactions). It also states a clear exclusion: a city street address should go to list_parcels_in_area, not resolve_parcel.

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=true and destructiveHint=false; the description adds substantial behavioral context: the tool returns transactions despite its name, results are permalinkable via a documented URL pattern, field values come from notarial deeds by default, and computed/approximated values are flagged inline. It also warns that certain filters select only rows with detected values and never assert absence, which is exactly the kind of behavioral nuance an agent needs.

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 core purpose and disambiguation, then flows logically into usage guidance, radius recommendations, an example, permalink construction, and field provenance. Every sentence earns its place; the length is justified by the tool's complexity and the absence of an 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?

For a 25-parameter tool with no output schema, the description covers the critical contextual gaps: what the tool returns (transactions, deeds and prices), how to build a permalink from result fields, how radius maps to real-world search scopes, and how data provenance affects interpretation. An agent has enough guidance to select and invoke this 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%, but the description still adds meaning beyond the schema: the radius guidance (0.3-0.5 km street, 0.5-1 km neighborhood, 2-5 km city area), the note that minArea/maxArea work for all propertyType values, and the provenance explanation for deed-derived versus computed fields. The example with Wrocław's Nowy Dwór also illustrates how the required parameters work together in practice.

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: 'Search real estate transactions within a geographic radius.' It immediately clarifies that it returns transactions (deeds and prices), not land plots, and explicitly distinguishes itself from list_parcels_in_area. This makes the tool's purpose unambiguous and separates it from nearby siblings.

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 the tool is best ('Best tool for neighborhood/osiedle searches'), provides a concrete radius guide for street/neighborhood/city-area searches, and explicitly points to list_parcels_in_area as the alternative when land plots are needed instead of transactions. It does not compare against search_by_polygon or search_transactions, so the when-not-to-use guidance is good but not exhaustive.

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?

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: the tool actually returns deed and price records despite the polygon name, coordinates are [longitude, latitude] and rings must close, field provenance distinguishes notarial-deed values from computed or approximated ones, and permalink construction shows the shape of results. Nothing contradicts 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 long, but the purpose and sibling disambiguation comes first. The permalink and data-provenance paragraphs are verbose, yet they earn their place given the lack of an output schema. It slightly over-delivers detail, so 4 rather than 5.

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 23-parameter tool with no output schema, this description covers the critical non-obvious aspects: the transaction vs parcels distinction, the exact polygon encoding, how to read result coordinates, and the meaning of computed/approximated values. Nothing needed to invoke the tool safely and 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 description coverage is 100%, so the baseline is 3. The description adds real incremental value for the only required parameter: a full GeoJSON example, the explicit [lon, lat] order, and the closure rule. The other parameters are already well documented in the schema, so the description's contribution is modest but meaningful.

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

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

The description states a specific verb and resource: 'Search real estate transactions within a geographic polygon.' It also separates itself from siblings explicitly: it returns transactions, not parcels, and says 'despite the name', then points to list_parcels_in_area for the parcel case. This fully disambiguates the tool's purpose.

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

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

It gives explicit usage guidance: 'Use for precise neighborhood/osiedle boundaries' and 'For quick searches, start with search_by_area instead.' It also names the alternative for parcel-level results: 'pass the same polygon to list_parcels_in_area.' Selection between alternatives is fully 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 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond this: NULL percentages for marketType and transaction_date, the permalink construction from result fields, and field provenance (notarial deed vs computed/approximated values flagged with [...]). This enriches the agent's understanding of data quality and output format without contradicting 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 long but well-structured, front-loading purpose and core usage. It is divided into clear sections (usage, data notes, permalink, provenance, location note) with no filler. Every sentence adds operational value, and the length is appropriate for a tool with 31 parameters and 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?

Given the tool's complexity (31 params, no output schema), the description is remarkably complete. It covers prerequisites (list_locations), data quirks (NULL handling), output interpretation (permalink construction, provenance flags), and alternatives (search_by_area). An agent can correctly invoke this tool and interpret results without additional documentation.

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 for key parameters: it clarifies the teryt vs location distinction and warns about street diacritics and literal matching. It also reinforces the marketType NULL caveat. While not exhaustive for all 31 parameters, it meaningfully supplements the schema where ambiguity is likely. This 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 searches Polish real estate transactions from the RCN registry and returns specific fields (address, date, price, area, price/m², property type). It also differentiates from siblings by noting that location matches TERYT districts only and directs users to search_by_area for neighborhoods. The verb 'search' and resource 'transactions' 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?

The description provides explicit when-to-use guidance: it instructs to call list_locations first, prefer teryt= over location=, and explains when location= is valid (rcn_district flag). It also names the alternative tool (search_by_area) for neighborhoods. Data notes about marketType and transaction_date NULLs further guide filtering decisions. This is thorough and actionable.

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