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?

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

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

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

Well-structured with clear notes, though slightly verbose. Every sentence earns its place, providing essential context without redundancy.

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

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

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

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

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

Schema coverage is 100% for the single parameter, but description adds valuable behavioral details about auto-expansion and partial matching, going beyond the schema description.

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

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

Clearly states the tool retrieves price per m² statistics for residential apartments in Poland, distinguishing it from sibling tools like search_transactions which handle other property types.

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

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

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

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

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

Beyond annotations (readOnlyHint, destructiveHint), description discloses two-state behavior (no match ≠ non-agricultural), cost (4 tokens refunded when no eligible area), and data source freshness (updated weekly). Adds critical interpretative guidance.

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

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

Front-loaded with main purpose, followed by details and important notes. Slightly lengthy but each sentence adds value; well-organized.

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

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

Despite no output schema, description explains response structure (eligible area, share, source features, match count, snapshot date). Combined with behavioral notes, provides full understanding for a read-only tool.

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

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

Schema coverage 100% with parameter description. Description adds context that transaction_id comes from specific search tools (search_transactions, search_by_area, search_by_polygon), aiding correct sourcing.

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

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

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

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

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

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

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

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

Annotations already 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, 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?

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 already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial non-obvious behavior: field provenance from the notarial deed (RCN), inline flagging of computed/inferred values, and full permalink construction instructions. It goes well beyond the safety profile the 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?

Front-loaded with the core purpose and the name-misleading caveat, then progressively more detailed. It is long, and the permalink paragraph plus radius guide repeat material also present in the schema, but every block is doing distinct work. Slightly verbose rather than padded.

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 what is returned (transactions, deeds, prices), data provenance and flag semantics, and how to share a result. Combined with the fully documented schema, 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 genuine value on top: radius guidance and the note that minArea/maxArea apply across all propertyType values (unit usable area vs parcel area). It does not re-explain most filters, which is correct since the schema does that.

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

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

States a specific verb+resource ('Search real estate transactions within a geographic radius') and immediately disambiguates the misleading name by clarifying it returns TRANSACTIONS (deeds and prices), not parcels. It explicitly names the sibling to use for the other interpretation (list_parcels_in_area), so an agent can pick correctly without opening a schema.

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

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

Explicit when-to-use ('Best tool for neighborhood/osiedle searches'), a concrete radius heuristic (0.3-0.5 km street, 0.5-1 km neighborhood, 2-5 km city area), a worked example, and a named alternative for the opposite need. This is about as complete as routing guidance gets.

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

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

Annotations already declare readOnlyHint/destructiveHint, but the description adds substantial non-obvious behavior: field provenance (RCN notarial deed by default, computed/approximated values flagged inline with [...]), coordinate conventions and vertex limits, and a full permalink-construction recipe. This is well beyond the structured safety 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?

Front-loads the core purpose and the transaction-vs-parcel distinction before any detail. The permalink paragraph is bulky and the [longitude, latitude] / first-last-point rules duplicate the schema, but nearly every remaining sentence is actionable rather than 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 a 23-parameter tool with no output schema and full schema coverage, the description covers the gaps that matter: what comes back (transactions with coordinates), provenance caveats, and how to turn results into a shareable permalink. It doesn't enumerate the full result shape, but with annotations and schema complete that is a minor 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%, so the schema already documents all 23 parameters, including coordinate order and the first/last-point-identical rule, which the description merely restates. The inline example polygon and the 'estimate coordinates from search_by_area' hint add some practical value, but this is the baseline case where structured data 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?

States a specific verb+resource (search real estate transactions within a polygon) and immediately clarifies a naming trap: it returns TRANSACTIONS, not parcels, 'despite the name.' It explicitly routes the parcel use case to list_parcels_in_area, distinguishing it from the closest sibling 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?

Gives explicit conditions: use for precise neighborhood/osiedle boundaries, start with search_by_area for quick searches, and pass the same polygon to list_parcels_in_area if the plots themselves are wanted. Alternatives and when-not-to-use are both named.

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 covered. The description nevertheless adds substantial behavioral context beyond the schema: NULL rates (marketType ~55%, no transaction_date ~1.7%), inline provenance flags, and the fact that bad name matches 'silently return zero rows'. Strong additions, but the core safety signals come from annotations.

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

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

Front-loaded with purpose, then usage, then data caveats, permalink, and provenance. For a 31-parameter tool the length is defensible, but the multi-sentence permalink-construction block is dense and leans toward reference-document territory rather than selection guidance.

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 31 parameters, no output schema, and no nested objects, the definition supplies the routing rules, the returned fields, the data caveats, and the sibling alternatives an agent needs to call it correctly. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema itself carries most parameter detail. The description adds real value by explaining the teryt-vs-location tradeoff and the silent-zero-row failure mode of incorrect name/diacritic usage, which the schema only partially covers.

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

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

States a specific verb+resource with scope ('Search Polish real estate transactions from the national RCN registry (8M+ records)') and enumerates the returned fields. It explicitly distinguishes itself from siblings by naming search_by_area for neighborhoods/osiedla and list_locations for resolving places, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use routing: 'Call list_locations(search=...) first to resolve a place', 'prefer the returned TERYT code as teryt=', and restricts location= to results flagged rcn_district. It also names the alternative (search_by_area) and the condition that selects it, plus a worked example query.

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