Cenogram - Polish Real Estate Data

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

While annotations declare readOnlyHint=true, the description adds valuable behavioral context: it specifies the comparison yields three specific metrics (median price/m², average area, transaction counts) and discloses the API constraint requiring additional filters beyond districts. This goes beyond basic safety profiling.

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 efficiently structured across five sentences: purpose statement, input specification, workflow prerequisite, API constraint, and concrete example. Every sentence earns its place 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?

For a 10-parameter tool with no output schema, the description adequately covers input requirements, workflow dependencies, and previews the returned data dimensions. It could marginally improve by specifying the output structure format, but the metric enumeration provides sufficient context for invocation.

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?

Despite 100% schema description coverage (baseline 3), the description adds critical semantic constraints not in the schema: the '2-5' district count limit (schema only enforces minLength: 1) and a concrete formatting example ('Mokotów,Wola,Ursynów') that clarifies the comma-separated syntax.

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 ('Compare') and resource ('real estate statistics'), clarifies the comparison is 'side-by-side' across 'multiple locations', and specifies the exact metrics returned (median price/m², average area, transaction counts). This effectively distinguishes it from sibling tools like get_price_statistics or search_transactions.

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

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

Provides explicit prerequisites ('Use list_locations first to find valid location names'), input constraints ('Provide 2-5 district names'), and API requirements ('Requires at least one filter besides districts'). However, it does not explicitly contrast when to use this versus siblings like get_price_statistics for single-location analysis.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context by enumerating the specific return values (total count, date range, breakdowns) since no output schema exists, but omits other traits like pagination or caching 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 consists of exactly two efficient sentences with zero redundancy. The first sentence front-loads the core purpose, and the second efficiently lists return values using a colon-separated format.

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 has no parameters and no output schema, the description adequately compensates by detailing the return payload. It successfully communicates what data the agent will receive, though it could briefly clarify the geographic/temporal scope of the overview.

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 contains zero parameters. Per the rubric, 0-parameter tools receive a baseline score of 4, as there are no parameter semantics to describe.

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 action ('Get') and specific resource ('Polish real estate transaction database'), with 'comprehensive overview' distinguishing it from sibling search and comparison tools. The return value list further clarifies the scope.

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 no explicit guidance on when to use this tool versus siblings like 'get_price_statistics' or 'search_transactions'. It lists what it returns but doesn't advise users to use it for high-level market analysis before drilling down.

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, confirming safe read access. The description adds valuable behavioral context not found in structured fields: the geographic scope ('Poland') and the aggregation method (binning transactions into price ranges). It does not describe output format details or pagination, but 'histogram' implies the return structure adequately given the tool's simplicity.

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?

Two well-structured sentences with zero waste. The first sentence front-loads the core action and output format; the second provides usage context. Every word earns its place.

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 2-parameter schema (100% coverage), readOnly annotation, and lack of output schema, the description provides sufficient context by specifying the geographic market (Poland) and output type (histogram). It appropriately compensates for missing output schema by indicating the histogram nature of returned data.

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

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

With 100% schema description coverage, the baseline is 3. The description does not explicitly discuss the bins or maxPrice parameters, but the mention of 'histogram' and 'price range' implicitly contextualizes the binning concept without duplicating schema details.

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

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

The description clearly states the tool retrieves a 'price distribution histogram' with specific aggregation ('how many transactions fall into each price range'), which distinguishes it from sibling tools like get_price_statistics (likely summary stats) and search_transactions (individual records). However, it does not explicitly contrast with these siblings by name.

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

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

Provides positive usage context ('Useful for understanding the overall market price structure in Poland') indicating when to use the tool. However, it lacks negative guidance (when not to use) or explicit references to alternatives like get_price_statistics for non-distribution analysis.

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

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

Annotations indicate readOnlyHint=true; description adds transparency: spread can be negative, minimum 5 samples required, mixed sale offers, different data sources, area buckets not additive, exclusion of fractional shares. 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 relatively long but well-structured and front-loaded. Every sentence adds important detail. Could be slightly more concise, but 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 4 parameters, no output schema, and only readOnly annotation, the description is remarkably complete. Covers edge cases, constraints, and references sibling tool. Provides sufficient context for proper 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 covers 100% of parameters with descriptions. The tool description enriches with context (teryt wins over location, areaBucket not additive, marketType defaults to 'all') but schema already provides baseline. Still adds significant value.

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

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

Clearly defines the tool as measuring asking-vs-transaction price spread for Polish cities/counties. Provides formula and explains negative spread. Distinguishes from siblings by referencing list_price_spread_locations for coverage.

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 this tool (measure spread) and when not to (not comparable across different as_of dates). Points to sibling tool for location catalog. Provides clear parameter guidance (teryt vs location, marketType, areaBucket).

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. Description adds crucial behavioral context: geographic limitation (Poland only), property type restriction (residential only), and the Warsaw-specific naming quirk where city-level queries fail. 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?

Three sentences, zero waste. Purpose front-loaded in sentence 1. Sentence 2 scopes usage and names alternative. Sentence 3 provides specific parameter guidance for Warsaw. Every sentence earns its place.

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?

Adequate for a single-parameter tool. Despite lacking output schema, description sufficiently indicates return value type (price per m² statistics). Missing minor details like specific statistical measures returned (mean, median, etc.), but complete enough for agent selection.

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

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

Schema has 100% coverage with good parameter description. Description adds valuable domain-specific usage guidance: the Warsaw district naming convention (Mokotów/Wola vs Warszawa) and reinforces the partial matching behavior with concrete examples, preventing common query errors.

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?

Specific verb 'Get' + resource 'price per m² statistics' + scope 'residential apartments in Poland'. Explicitly distinguishes from sibling 'search_transactions' by stating it only covers residential units vs. 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 names alternative tool 'search_transactions' for other property types. Provides critical usage constraint for Warsaw requiring district names (Mokotów, Wola) rather than 'Warszawa'. Could explicitly state when to prefer this over 'get_price_distribution' or 'compare_locations'.

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. Description adds value by detailing data sources, approximation nature, sample size requirement, and that it excludes costs. 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?

Description is thorough but not overly verbose; well-organized with purpose first, then constraints, then parameter notes. Each sentence adds value, though slightly long.

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; description compensates by explaining the formula and suppression condition. Covers return format, limitations, and sample requirement. Adequate for a read-only estimator.

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 good descriptions. Description adds nuance: teryt wins over location, longer codes truncated, area buckets are not additive. Enhances understanding beyond schema.

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

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

The description explicitly states the tool estimates gross rental yield for Polish cities/counties, defines the formula, and distinguishes from sibling tools like list_rental_yield_locations by referencing it for location catalog.

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

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

Provides clear context on when to use (for yield estimates), how to specify location via city or teryt, warns about non-comparability across dates and coverage limitations, and mentions alternative tool for listing locations. Lacks explicit 'when not to use' but implies via exclusions.

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

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

While annotations declare readOnlyHint=true, the description adds crucial behavioral context about return granularity—specifically that Warsaw returns districts (Mokotów, Wola) rather than 'Warszawa', and Kraków returns sub-districts—helping the agent predict return structure without an output schema.

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?

Five sentences, all earning their place: core purpose, general behavior rule, two specific city examples that prevent confusion, and usage guidance. Front-loaded with the essential verb-resource pair.

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 single-parameter tool without output schema, the description compensates well with concrete return value examples (district names). Could be improved by explicitly stating the return type (array of location objects), but the behavioral examples provide sufficient predictability.

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

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

With 100% schema description coverage for the 'search' parameter, the baseline is met. The description mentions using the parameter 'to filter by name' but adds minimal semantic value beyond what the schema already documents.

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 the specific verb 'List' and clear resource 'available locations (cities and districts)', distinguishing it from sibling search tools (search_transactions, search_parcels) that return properties rather than administrative locations.

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 provides clear context about what the tool returns (administrative districts vs. city names) with specific city examples, helping the agent understand when to use it for location discovery. However, it lacks explicit guidance on when NOT to use it or direct comparison to sibling tools like compare_locations.

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 discloses behavior beyond annotations: each entry is a coverage signal only, not the spread; search is diacritic-insensitive substring with min 2 chars; results sorted by asking_sample_n descending; free credits. No contradiction with readOnlyHint annotation.

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

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

The description is concise with no wasted words, using three sentences to cover purpose, usage, and behavioral details. It is well-structured and front-loaded with the core function.

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 nature of entries (coverage signal, sample size, confidence) and what the tool does not compute. It is sufficiently complete for a low-complexity tool with one optional parameter, though it could explicitly mention the return structure.

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

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

The schema covers 100% of parameters with a description. The tool description adds value by repeating and elaborating on the search filter behavior (diacritic insensitivity, min length) and clarifying the effect of omitting the parameter (list 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 for which get_price_spread can return data, distinguishing it from siblings like get_price_spread itself. It specifies the resource (cities/counties) and the verb (list), and ties it to a specific sibling use case.

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 this tool: to discover valid location/teryt values for get_price_spread instead of guessing. It also explains what the entries represent (coverage signals) and what they do not (actual spread), and mentions optional search filters and free usage.

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

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

The description adds behavioral details beyond the readOnlyHint annotation, such as the tool being free (0 credits), results sorted by rent_sample_n descending, and the search being diacritic-insensitive substring with minimum 2 characters. It does not contradict annotations and provides useful context.

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

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

The description is concise (three short paragraphs) and well-structured, with each sentence serving a distinct purpose: listing the tool's function, explaining what entries represent, and describing the optional search filter. No unnecessary words.

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

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

Despite lacking an output schema, the description explains what each entry contains (coverage signal, sample size, confidence) and what it does not do (compute yield). It covers all necessary aspects for an agent to understand and use the tool effectively.

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

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

The input schema covers the single parameter 'search' with a description, and the tool description adds an example ('gda' → Gdańsk) and clarifies the min length and diacritic-insensitive behavior. Since schema coverage is 100%, the description adds meaningful context 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 'List the cities/counties for which get_rental_yield can return data', providing a specific verb ('list') and resource ('rental yield locations'). It distinguishes from siblings by clarifying this tool is for discovering valid location values for get_rental_yield, not for computing yields.

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 advises using this tool to discover valid location/teryt values instead of guessing names, and clarifies that each entry is a coverage signal, not the yield itself. It also mentions the optional search filter and its behavior. While it does not explicitly state when not to use it, the guidance is clear and practical.

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

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

The annotations declare readOnlyHint=true, indicating a safe read operation. The description adds valuable context about the geographic scope (radius) and provides a concrete coordinate example. However, it fails to mention the Poland-specific geographic constraints visible in the schema (lat 49-55, lng 14-25) or describe what data structure is returned, which would be helpful given the lack of an output schema.

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 consists of three highly efficient sentences: purpose declaration, input requirements, and concrete example. Every sentence earns its place without redundancy. The information is front-loaded with the core action, making it easy for an agent to quickly assess relevance.

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 schema's richness (10 parameters including date ranges, price filters, property types, and market types), the description is minimally adequate but has clear gaps. It focuses exclusively on the geographic search mechanism while omitting any mention of the sophisticated filtering capabilities available, which limits an agent's understanding of the tool's full utility without examining the schema directly.

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

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

With 100% schema description coverage, the schema fully documents all 10 parameters including their types, ranges, and purposes. The description mentions the three core geographic parameters (latitude, longitude, radius) and provides an example, but does not add significant semantic depth beyond what the schema already provides, which warrants the baseline score for high-coverage schemas.

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 specific action ('Search real estate transactions') and the unique scope ('within a geographic radius'). It effectively distinguishes itself from sibling tools like 'search_by_polygon' (which implies polygon geometry) and 'search_parcels' (different data type) through the explicit mention of radius-based searching.

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 an example usage scenario (Warsaw's Palace of Culture) that implicitly demonstrates when to use the tool—when you have a center point and distance. However, it lacks explicit guidance on when to choose this over 'search_by_polygon' (e.g., 'use this for circular areas, use search_by_polygon for irregular boundaries') or other search siblings.

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

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

Beyond readOnlyHint=true annotation, description adds crucial behavioral details: return value description ('Returns transactions found inside...'), coordinate ordering constraint ('[longitude, latitude]'), polygon closure requirement ('First and last point must be identical'), and a concrete JSON example.

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?

Seven sentences covering purpose, input mechanism, output, usage context, technical constraints, and example. No redundancy; every sentence provides distinct value. Well front-loaded with the core purpose.

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

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

For a complex 12-parameter spatial tool with nested objects and no output schema, description adequately covers the critical complexity (GeoJSON format requirements, coordinate system) and describes return values. Minor gap: doesn't mention result limits or error behavior for invalid geometries.

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?

Despite 100% schema coverage (baseline 3), description adds essential semantic context for the complex nested polygon parameter: coordinate order, closure constraint, and a complete working example that clarifies the expected data structure beyond the raw 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?

Description opens with specific verb 'Search' and clear resource 'real estate transactions within a geographic polygon.' The GeoJSON specificity distinguishes it from sibling tools like search_by_area or search_transactions.

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

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

Provides clear positive guidance: 'Use for precise area searches (neighborhoods, streets, custom regions).' However, lacks explicit contrast with siblings (e.g., when to use search_by_area vs this polygon search).

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?

Discloses return payload structure ('district, area, and GPS coordinates') which compensates for missing output schema. Clarifies autocomplete behavior pattern. Annotations declare readOnlyHint=true, and description confirms safety through 'Search' semantics without contradicting the read-only nature.

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?

Four sentences with logical progression: purpose → return values → usage context → concrete example. Zero redundancy. Front-loaded with action and resource, with every sentence delivering distinct value (mechanism, payload, workflow, syntax).

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 simple 2-parameter schema and lack of output schema, description achieves completeness by detailing return fields (district, area, GPS) and explaining the autocomplete interaction pattern. Sufficient for agent to invoke confidently without surprises.

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 complete descriptions for both 'q' (prefix) and 'limit'. Description reinforces parameter usage through concrete example ('146518_8.01') matching schema pattern, but does not add substantial semantic layer beyond well-documented schema fields.

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

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

Description opens with specific verb 'Search', identifies resource 'land parcels', and specifies unique mechanism 'parcel ID prefix (autocomplete)'. Clearly distinguishes from siblings like search_by_area and search_transactions through the prefix/autocomplete focus and explicit mention of workflow transitioning to transaction searches.

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

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

Provides explicit workflow guidance ('Useful for finding exact parcel IDs, then searching transactions nearby') that clarifies the two-step process with sibling search_transactions. Lacks explicit 'when not to use' guidance comparing geographic search alternatives (search_by_area, search_by_polygon), though the prefix focus provides implicit differentiation.

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. Description adds valuable context: data source (RCN registry), dataset scale (7M+ records), and specific return fields (address, date, price, area, price/m², property type). Could improve by mentioning pagination behavior or result format details.

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?

Four sentences, zero waste: (1) purpose and source, (2) return values, (3) prerequisite instruction, (4) example. Information is front-loaded and efficiently 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?

For a 16-parameter search tool with no output schema, the description adequately compensates by listing returned fields. Missing explicit details on pagination behavior or response structure, but the example and field list provide sufficient context for invocation.

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

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

Schema has 100% description coverage, establishing baseline 3. Description adds minimal parameter semantics beyond schema, though it reinforces the location parameter workflow ('Use list_locations first') and illustrates filter combinations through the example.

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

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

Description explicitly states the tool searches 'Polish real estate transactions from the national RCN registry' with specific scope (7M+ records). It clearly distinguishes from siblings by focusing on transaction search vs. comparison (compare_locations), statistics (get_price_statistics), or geographic searches (search_by_polygon, search_by_area).

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

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

Provides explicit prerequisite workflow: 'Use list_locations first to find valid location names.' Includes concrete usage example. Does not explicitly contrast with alternative search methods (search_by_area vs. this) or state when NOT to use it.

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