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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: silent empty results for non-RCN district names and the hidden filter requirement. It does not describe result ordering or how districts with no transactions appear, which would push it to a 5.

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, front-loaded with purpose, then the naming trap, then the filter prerequisite. No filler; every clause carries an operational constraint the agent would otherwise get wrong.

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 read tool with no output schema, the description covers the highest-risk gaps (name matching, mandatory second filter) and names the returned metrics. Minor gaps remain: it doesn't say how districts without sufficient data are represented or whether includeDemographics affects the shape of the response.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value beyond the schema for the key parameter: districts matches by name only, requires RCN-flagged names, and silently fails otherwise — semantics the schema does not convey. It also hints at propertyType as the typical second filter.

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

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

States a specific verb and resource (compare 2-5 districts side-by-side) plus the exact output metrics (median price/m², average area, transaction counts). This is clearly distinguishable from sibling aggregators like get_price_statistics or get_market_overview, which are not district-comparison 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?

Explicitly routes the agent through a prerequisite (call list_locations(search=...)) and names the condition that gates success (only names flagged as rcn_district). It also states an exclusion: TERYT unit names silently return no data, and notes the requirement of at least one filter besides districts, e.g. propertyType.

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?

Despite readOnlyHint=true covering the safety profile, the description adds substantial non-obvious behavior: 5-token cost with refund when no estimate is produced, ability to be disabled for maintenance, county-varying as_of that makes estimates non-comparable, and exclusions of fractional shares and non-market deeds.

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 a clean beta/appraisal disclaimer, then organized into addressing, returns, and caveats. Dense but nearly every sentence carries a constraint an agent needs; a couple of clauses duplicate the schema descriptions verbatim.

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, yet the description enumerates the return payload (per m² and per hectare, likely and wide range, confidence band, comparable count, as_of date) and explains the no-estimate outcome. An agent knows what it will get and when it won't.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema can't express: the exactly-one rule between lat/lng and parcelId, area's conditional requirement/defaulting, and 'unknown' = no designation recorded. Some sentences do restate schema text, preventing a 5.

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

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

Specific verb + resource + scope: 'Estimate an undeveloped plot's market value from comparable registered transaction prices near a point,' plus the explicit 'Undeveloped land only' boundary and the disclaimer that this is not a certified appraisal. It doesn't name the closest ambiguous sibling (estimate_value) to route between them, so it stops short of 5.

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 addressing rules precisely: 'lat + lng OR parcelId ... exactly one', area REQUIRED with lat/lng and defaulted from the cadastre with parcelId, and that landType is a caller choice. It also names the failure conditions (too few comparables, undeterminable area) and the maintenance mode.

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 substantial context beyond that: beta status, that this is not a certified appraisal and ignores condition/finish/floor, the as_of county lag making cross-city comparison invalid, the 5-token cost with refund policy, and the exclusion of fractional shares and non-market deeds. It could go slightly further on latency or payload size, but the behavioral disclosure is unusually thorough.

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, then address rules, then return shape and caveats. Dense but every sentence carries information (ranges, as_of caveat, cost/refund, exclusions). Slightly long, but no filler sentences.

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, and the description fully covers the return shape: point estimate, likely and wide range, confidence band, comparable count, and as_of. With usage rules, caveats, and cost behavior all stated, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so parameters are already documented; the description reinforces the critical invariants (exactly one of lat/lng vs parcelId, area required at 10–250 m²) and explains what rooms/market and includeComps actually do to the result. This adds decision-relevant meaning rather than merely repeating 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 and resource ('Estimate an apartment's market value') and immediately clarifies the scope: comparable registered transactions near a point, apartments only. It explicitly distinguishes itself from the sibling estimate_land_value for plots/farmland, so the agent can choose without inspecting 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 routing: apartments only, use estimate_land_value for building plots or farmland, and too few comparables yields no estimate. It also specifies the address rule (lat+lng OR parcelId, exactly one) and that area is required, covering both when to use and how to invoke.

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

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

Annotations only declare readOnlyHint/destructiveHint, so the description carries the burden and does so richly: it discloses provenance of the construction-age ESTIMATE (permit records, never a registry date), the 2016 record horizon, the expected 'not established' outcome, and a concrete cost of 4 tokens. That is exactly the behavioral context structured fields cannot 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 what is returned, then the usage trigger, then the caveat about estimate quality and cost. Three tight paragraphs with no filler; every sentence conveys a fact an agent needs (fields, provenance, empty-result behavior, price).

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 and only safety annotations, the description still explains the returned fields, the semantic meaning of the estimate's interval, the empty-result case, and the token cost. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 50%: transaction_id is documented in the schema but transactionId is not, and the description never clarifies that the two are aliases for the same UUID. The description's 'for one transaction' adds orientation but no format or disambiguation guidance beyond what the schema already supplies.

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

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

States a specific verb and resource (building-by-building breakdown for one transaction) and enumerates the returned fields: footprint area, storeys, estimated total floor area with the footprint × storeys formula. It also explicitly contrasts itself with search tools that return per-transaction building SUMS, so an agent can distinguish it from siblings without opening the schema.

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

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

Gives a clear trigger: use it after a search whose result carries building data, e.g. a developed-land deed covering several buildings. It also notes the degenerate case (returns nothing for a transaction with no buildings). It doesn't name a specific sibling tool by name, but the alternative (inline search sums) is described well enough to 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 cover safety (readOnly, non-destructive), but the description adds real behavioral context: the return includes the requested level PLUS all parent levels, time-series vs. single-year semantics, the data source (GUS BDL), and an explicit cost of 1 token. This is precisely the kind of non-schema information an agent needs before calling.

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 what it returns and the coverage, then addressing rules, then return shape, then cost. No filler sentences; each adds a distinct, actionable fact.

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

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

With no output schema, the description still explains the return shape (requested level plus parents), and all six optional parameters are covered by a fully documented schema. Nothing material is missing for correct invocation, including the budget cost.

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 goes further by explaining the location→level resolution rule and the neighborhood exclusion, which the schema only partially implies. However, precedence (teryt wins over location) and year vs. yearFrom/yearTo exclusivity are largely restated from the schema rather than adding new meaning.

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 concrete verb+resource (local GUS BDL statistics for a Polish location) with scope quantified (~50 indicators, 11 named categories). The domain, source, and granularity make it unmistakable against siblings such as get_market_overview or the get_transaction_* tools, which cover market/transaction data rather than official local statistics.

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 clear addressing rules: location by name OR teryt sourced from list_locations, with an explicit exclusion ('Neighborhoods/osiedla are NOT addressable') and resolution behavior (city/county → county level). It does not name an alternative sibling for cases where the agent wants market prices instead, so it stops short of the 5-level bar.

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 this as read-only and non-destructive, and the description adds substantial context beyond them: the below-EU-threshold coverage gap since 2021, tender attribution to the authority's seat rather than works location, counters vs notice-list divergence, and the explicit warning that absence of tenders is not evidence of non-investment. The 1-token cost disclosure is also useful operational 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 purpose is front-loaded in the first sentence, with addressing rules and caveats following in a logical order. The caveat block is dense but each clause prevents a specific misinterpretation, so it earns its space; the cost note is a small appendage rather than noise.

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 no output schema, the description covers sources, addressing, and major interpretive pitfalls well. It only lightly characterizes the return shape (counters and a notice list with a flag), which is sufficient given the absence of an output schema but not exhaustive.

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 both parameters are fully documented in the schema, including the 4/6/7-digit semantics and location resolution rules. The description restates the teryt-wins precedence and the county-expansion behavior, adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — signals that a Polish municipality is about to build infrastructure — and enumerates the three data sources (procurement bulletin, agglomeration membership, planned capital expenditure). This is clearly distinct from siblings like get_permits_in_area or get_transaction_permits, which concern existing permits/transactions rather than forward-looking municipal investment signals.

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?

Explains the two addressing modes (location vs teryt) and states teryt wins when both are given, plus how location names resolve to municipalities. It gives clear context for invocation but does not explicitly route the agent away from related siblings such as get_permits_in_area or get_transaction_permits.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely non-obvious behavioral context: coverage gaps in the underlying data (marketType unknown for ~55% of records, transaction_date missing for ~1.7%), which materially affect how an agent should interpret the breakdowns. It does not discuss response size, aggregation lag, or freshness, leaving a small gap.

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 sentences, front-loaded with the entry-point instruction and the disambiguation before the enumeration of outputs. Every clause carries information — the negated use case, the sibling redirects, the returned fields, and the data-quality caveats — with no 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?

With no input parameters and no output schema, the description carries the burden of describing the return payload, and it does so by enumerating counts, date range, breakdowns, top locations, and price statistics. Combined with the data-quality caveats, an agent has enough to decide to call it and to interpret the result.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline for a parameterless tool applies. The mention of marketType refers to a returned field rather than an argument, so it neither helps nor confuses parameter semantics.

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 clear verb/resource ('shape of the whole Polish transaction database') and explicitly negates the likely misreading ('not one place'), then enumerates exactly what comes back: total count, date range, breakdowns, top locations, price statistics. Sibling tools get_price_statistics and search_transactions are named as the per-place alternatives, so the agent can distinguish this from neighbors 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?

The opening imperative 'Start here' gives an explicit entry-point rule, and the parenthetical names the alternatives (get_price_statistics, search_transactions) plus the condition that selects them (per-place queries). Both when-to-use and when-not-to-use are stated.

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 say readOnly/non-destructive; the description adds substantial context beyond them: the four coverage states and their billing/refund treatment, the 4-token cost with refund conditions, the fact that results are sets with no areas so no share or dominant category can be stated, and a legal-advice disclaimer. Nothing about calling it correctly is left to inference.

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 and the exclusion, then progressively deeper detail on returns, coverage states and cost — a sensible ordering. It is on the long side and the SETS/area explanation takes two clauses to land, but each sentence carries distinct information.

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

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

With no output schema, the description fully supplies the return contract: land-use categories, soil grades, the I-III protected-range flag, the city-boundary rule, and the verification date, plus the set-valued caveat and the enumerated status values. An agent can set expectations and handle every outcome.

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

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

Single parameter with 100% schema description coverage, including format examples and accepted ID forms, so the schema carries the load. The description adds no further detail on the parcelId itself (e.g. what happens with an unresolvable or non-held ID beyond the not_covered state), so the baseline 3 applies.

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

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

States a specific verb and resource — the official land-use and soil-quality classification of one parcel — and immediately scopes it to the agricultural de-designation question. It explicitly distinguishes itself from get_parcel_report, which the agent can recognize without opening a schema.

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

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

Gives an explicit when-to-use ('only for that question') and enumerates the adjacent topics that belong elsewhere (prices, flood, zoning, buildings, permits, surroundings, transport), routing them to get_parcel_report, which is noted to include this classification anyway. This is a model routing statement.

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?

Though annotations already declare readOnly/destructive=false, the description adds substantial behavior beyond them: billing (45 API tokens, refund rules per outcome), per-key per-minute rate limits with a sequential retry instruction for 'Too many requests', and the possibility of a partial report. It also flags interpretive caveats (RCN-derived neighbourhood signal, construction age as an estimate).

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?

Content is front-loaded: what it is, what's inside, then sibling routing, then state semantics, caveats, and billing. Nearly every sentence carries distinct information. It is dense and long, but the length is justified by the tool's complexity rather than padding.

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

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

For a complex aggregate tool with no output schema, the description covers the section inventory, the per-section state vocabulary (covered / covered_no_data / not_covered / not_computed plus context variants), list capping, partial results, and interpretation limits. An agent could call and correctly interpret it from this alone.

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 documents the single parcelId format fully, so the baseline would be 3. The description adds real value by explaining how to obtain a valid id (resolve_parcel for coordinates, list_parcels_in_area for addresses) and by tying id validity to the refund policy for unresolvable parcels.

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 ('whole dossier for one land parcel') and enumerates the exact contents (parcel core, thirteen layers, transactions, price context, municipal context, shape). It also explicitly contrasts itself with 'the per-layer parcel tools', so an agent can distinguish it from siblings 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 routing: 'prefer it over the per-layer parcel tools', 'for a coordinate or locality + number use resolve_parcel first', and 'for a street address use list_parcels_in_area'. It names alternatives and the precise condition that selects each, leaving nothing to inference.

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

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

Annotations only declare a safe read; the description adds far more: 5-token cost per call including empty results, per-page charging, periodic (not live) refresh, maintenance outages, an error when the query exceeds the time limit, and the aggregate covering all matched cases rather than the page. It also discloses real data gaps — no decision outcomes, only accepted notifications, no pending cases, parcels without geometry unsearched — which materially shapes interpretation.

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

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

The core purpose and the 'newest first, not nearest first' caveat are front-loaded, and almost every clause carries operational value. It is nonetheless a dense wall of text without sectioning, and the cost/paging points are restated in more than one 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?

With 12 parameters, no output schema and a complex data source, the description covers return ordering, the year×category aggregate with permit/notification split and volumes, the truncated/cursor protocol, refresh staleness and failure modes. Little an agent needs in order to call and interpret this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3; the description still adds cross-parameter meaning the schema only states tersely, e.g. that the cursor must be replayed with identical filters, that pages must not be summed, and that aggregateOnly costs the same. It does not add much beyond the schema for lat/lng/date bounds, which the schema already documents well.

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 concrete verb and resource ('List the building permits and works notifications'), plus scope (since 2016, within a radius of a point, issued decisions only) and the matching mechanism (parcel geometry held by the service). An agent knows exactly what it gets back compared with a transaction-lookup sibling.

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 routing guidance: use categories=[XIII] for apartment blocks, excludeCategories=[XXVI] to drop utility noise, aggregateOnly=true for 'how many', and a smaller radiusKm instead of paging to find what is nearest. It also says where coordinates must come from (resolve_parcel / list_parcels_in_area) and forbids guessing.

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 readOnly/destructive hints, and the description adds a key behavioral quirk: location/teryt are silently ignored because the histogram is national. It does not describe the return shape or units explicitly, but for a read-only aggregation tool this is solid added 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?

Two efficient sentences with the core purpose front-loaded and the exclusion/alternative guidance following immediately. Every clause 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 a read-only, no-output-schema tool with 100% param coverage, the description covers purpose, scope, and the ignored-parameter pitfall. Only the exact histogram/return representation is left implicit, which is a minor gap.

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

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

Schema coverage is 100% and already documents bins, maxPrice, and the ignored location/teryt fields. The description's note about ignored params largely repeats what the schema states, 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?

States a specific output form (national histogram of transactions per price range) and scope (all Poland), clearly differentiating it from location-scoped siblings. An agent can tell exactly what this returns without opening the schema.

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

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

Explicitly states when to use it ('overall price structure of the market') and names the alternatives for the location-specific case ('for one place use get_price_statistics or search_transactions'), including the condition that selects them.

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

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

Annotations already declare it as a safe read-only operation, but the description adds material context: data are based on notarial-deed prices rather than asking prices, county coverage varies with possible 5+ year gaps, and the response states the period used. These are meaningful behavioral caveats 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 compact and front-loaded: purpose and sibling exclusion come first, followed by window defaults, location matching, and data caveats. Every sentence contributes useful information without repetition.

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?

Input behavior and data caveats are well covered, but there is no output schema and the description does not explain what statistics are returned (e.g., median, average, count, breakdown). For an agent invoking a statistics tool, that return-shape gap leaves meaningful uncertainty.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema. The description reinforces the default window and location expansion behavior but adds little parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb+resource: price per m² statistics for residential apartments by location. It also distinguishes the tool from search_transactions by naming the alternative for 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?

It clearly scopes usage to residential apartments and directs other property types to search_transactions. It also explains the default 24-month window and when to use period="all". However, it does not explicitly compare against related siblings like 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?

Beyond the readOnlyHint it discloses the crucial interpretive caveat: a no-match result is never proof of non-agricultural status, with three concrete reasons (small unfarmed plots absent, layer update cadence, renumbered parcels on older transactions). It also gives the data refresh cadence and an explicit cost/refund rule, which annotations do not carry.

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

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

Purpose and return shape come first, then the caveat and cost. Every sentence carries unique information – no restatement of the name, no filler – despite the density required by the negative-result semantics.

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

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

There is no output schema, so the description carries return semantics itself: per-parcel area in m², share of parcel when measured area is known, source feature count, count of matched parcels, and snapshot date. Combined with the absence caveat and cost note, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 50% – only transaction_id is documented as the UUID from a search result – and the description adds nothing about the parameters. In particular it does not clarify that transactionId and transaction_id are duplicate aliases of the same UUID, an ambiguity an agent could stumble on.

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

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

The opening states a specific verb+resource+scope: a parcel-by-parcel agricultural land-eligibility breakdown for a single transaction, drawn from nationwide official data. It is clearly separable from neighboring tools such as get_parcel_land_class (paper classification) and the other get_transaction_* environment lookups.

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 a clear usage context ('useful for due diligence on land actually eligible/maintained as agricultural, beyond the paper classification') and a cost note, which implies the alternative source. It never names a sibling tool explicitly or states when not to call it, so it stops short of a full routing rule.

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 still adds genuinely useful context the annotations cannot: empty results when no mapped zone exists, an explicit warning that absence is not an assertion of safety, and a stated cost of 4 tokens refunded when no flood data. It doesn't describe ordering or the exact shape of the per-plot payload, but the behavioral cues it does give are strong.

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 high-value usage rule and cost/empty-result caveats are front-loaded and every sentence carries information. The opening sentence is dense with clause-heavy enumeration, but that density is payload description rather than padding.

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

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

With no output schema, the description carries the full burden of describing return values and does so field by field. Combined with the empty-result semantics, the cost note, and the sibling fallbacks, an agent has everything needed to call this correctly and interpret a null response.

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?

At 50% schema coverage and zero parametrization in the description ('for one transaction'), the baseline of 3 applies. Neither the schema nor the description resolves the real ambiguity: transactionId and transaction_id are duplicate optional aliases with required=[] and no stated either/or rule in the schema for transactionId.

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?

Names a specific verb and resource ('flood-hazard breakdown for one transaction') and enumerates exactly what comes back: hazard category, hazard type, share of plot in zone, and per-scenario return periods. That precision also distinguishes it from the sibling get_flood_risk, which is not transaction-scoped.

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

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

Gives an explicit trigger ('after a search whose result shows flood_risk') and names which searches surface it inline (search_transactions, search_by_area) versus which do not (search_by_polygon). It also routes the no-transaction case to get_parcel_report, so the agent has a complete decision tree.

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 readOnlyHint/non-destructive annotations: it discloses the cost (4 tokens, refunded when there is no heritage data), the authoritative caveat (indicative data; the regional conservator makes the binding determination), and the critical semantic that no detected listing is not the same as 'not listed'. Those are exactly the traits an agent cannot infer from structured fields.

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

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

Front-loaded with the purpose, then output shape, then usage routing, then caveats and cost — a sensible ordering with no filler. The first sentence is dense and clause-heavy, but every element carries 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?

There is no output schema, so the description must describe return values, and it does: status meanings for 'listed' vs 'zone', the measurable protected-area share, and the entry fields. Combined with usage routing, cost, and authority caveats, an agent has everything needed to call it and interpret the result.

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 two schema parameters are an alias pair (transactionId / transaction_id) at 50% description coverage, and the one documented property already says 'This or transactionId is required.' The description only implies 'one transaction' without naming the parameter or noting the alias, so it adds no real meaning over the schema — adequate but not compensating for the coverage gap.

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: a parcel-by-parcel heritage-listing breakdown for one transaction, enumerated down to fields (status, protected share, entries with category/name/function/period/entry date). It clearly separates itself from get_parcel_report (no-transaction case) and the search tools, so an agent can identify it without opening the schema.

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

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

Explicitly says when to use it ('after a search whose result shows a heritage listing') and names the alternatives: search_transactions and search_by_area surface heritage_status inline, search_by_polygon does not, and get_parcel_report covers a parcel with no transaction. This is a complete routing statement with both positive and negative 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?

Annotations already declare this is a non-destructive read; the description goes well beyond by disclosing pricing (4 tokens, refunded when no landslide data), the scale caveat (intersection means overlap with a mapped area, not that the parcel is a landslide), the meaning of source_version_date, and the crucial empty-result semantics ('absence of data is never an assertion of safety'). That last point is the kind of behavioral nuance structured fields cannot convey.

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

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

Front-loads the core capability, then usage, then caveats and cost — a sensible ordering with no filler sentences. It is dense and the deeply nested parenthetical defining source_version_date forces re-reading, but every sentence carries information an agent needs.

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

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

The description effectively documents the return shape (worst category, share of plot in zones, per-zone list) despite there being no output schema, and covers cost, negative results, and scale limits. The only remaining gap is guidance on the two mutually-exclusive transaction id parameters, which matters somewhat given both are optional in the schema.

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

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

Schema coverage is 50%: transaction_id carries a description naming it as the UUID from a search result, while transactionId is undocumented in the schema. The description establishes what the input represents ('for one transaction') but never explains the duplicated alias or that either field satisfies the requirement, leaving the agent to reconcile two near-identical parameters itself. Adequate baseline, but it does not fully compensate for the coverage gap.

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

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

The description names a specific resource and scope: parcel-by-parcel landslide-hazard breakdown for a single transaction, sourced from 1:10,000 official hazard maps. It also defines the domain vocabulary ('landslide' vs 'threatened') so the agent understands the output categories, and it is clearly separable from siblings like get_transaction_flood or get_parcel_report.

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 trigger: call it after a search whose result shows landslide_risk, and it even names which search tools surface that field (search_transactions, search_by_area) and which do not (search_by_polygon). It also names the alternative for transactions-less parcels (get_parcel_report), which is exactly the when-to-use-another-tool guidance the dimension asks for.

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

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

With only readOnlyHint and destructiveHint annotations, the description adds substantial behavioral context: cost and refund policy, empty-result semantics, buffer-zone treatment, rank meanings, building-restriction meanings, and a legal disclaimer. It also clarifies that the tool describes the source of a restriction rather than a permitting outcome.

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 layers in caveats and semantics. It is dense and somewhat long, but most sentences earn their place by preventing misinterpretation of empty results and protected-area rankings.

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

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

There is no output schema and annotations are minimal, so the description carries most of the explanatory burden. It covers the return concepts, empty-result distinctions, buffer-zone behavior, cost, and legal scope well enough for an agent to invoke and interpret the tool correctly.

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

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

Schema description coverage is 50%, so the description should compensate for gaps. It mentions calling on a transaction id from a search result, but it does not clarify the duplicated transactionId / transaction_id fields or their requiredness, leaving some ambiguity for the agent.

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 gives a specific verb-and-resource purpose: a parcel-by-parcel nature breakdown for one transaction, covering forest proximity and overlapping protected areas. It distinguishes itself from search tools (which carry no nature signal) and from get_parcel_report for parcels without 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?

It explicitly says to call this directly on a transaction id when forest proximity or protected-area build limits matter, and it names get_parcel_report as the alternative for parcel-only lookups. It also warns that an empty result is never a statement that building is allowed.

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 establish a safe read operation, but the description adds substantial behavioral context: linkage is by current parcel identifier so splits/merges break it, permit outcome and pending cases are not held, notifications are included only if accepted without objection, and empty results never confirm absence. It also discloses cost and refund conditions.

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

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

The purpose is front-loaded, and the remaining sentences add essential caveats, coverage-state meanings, alternatives, and cost information without filler. The length is justified by the domain complexity and absence of an output schema.

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

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

Given no output schema, the description supplies the key return-shape information by listing per-case fields. It also explains coverage states, match limitations, inclusion rules, empty-result interpretation, and cost, making it complete enough for correct 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?

The schema covers the UUID pattern and partially describes transaction_id as the transaction id from a search result. The description reinforces that the tool operates on one transaction id, but it does not clarify the transactionId vs transaction_id alias or add further parameter-level guidance beyond the schema.

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

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

States a specific resource and scope: building-permit history for one transaction's parcels from the national registry, with per-case fields and coverage since 2016. It also distinguishes itself from siblings by naming get_parcel_report and get_permits_in_area for adjacent use cases.

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

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

Explicitly says to use it after a search to screen what was built or approved on the land. It also routes the agent to alternatives: get_parcel_report when there is no transaction, and get_permits_in_area for nearby point-based permit activity.

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 context beyond them: the three-state coverage model ('covered'/'covered_no_data'/'not_covered'), the explicit warning that 'not_covered' is never a claim that no plan exists, and the cost of 4 tokens with refund conditions for the two non-data states. That is exactly the kind of operational and interpretive context an agent cannot get from structured fields.

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

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

The returned fields and the usage rule come first, followed by the coverage semantics and cost. The parenthetical Polish terms are domain-necessary, and no sentence is filler.

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

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

There is no output schema, so the description must describe return values – it does, enumerating zone attributes and overlay areas. Combined with the coverage-state explanation, an agent knows what it will get and how to read an empty result.

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 only 50% – transaction_id is documented but transactionId is bare – and the description never mentions either parameter, how to obtain a transaction id, or why two aliases for the same UUID exist. With half the parameters undocumented and no compensating text, the agent is left to infer the input contract.

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

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

States a specific verb and resource: general-plan (POG) zoning for one transaction's land, enumerating the returned fields (zone symbol, name, share, max height, development intensity, built-up coverage, biologically active area) and overlay areas. This clearly separates it from the many sibling get_transaction_* hazard tools, which cover flood, heritage, nature, transit, 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?

"Use it for feasibility and permitted-use questions on a plot" gives explicit when-to-use guidance, and the coverage discussion implies when results will be empty. It never names an alternative tool or states exclusions, so it stops short of the top tier.

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

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

Annotations only declare readOnlyHint/destructiveHint, yet the description adds substantive behavior: explicit cost (4 tokens, refunded when there is no informative data), the meaning of null distances, assessed=false semantics, and the carriageway-edge null case when the source lacks width. It also bounds interpretation, stating categorically that the indicator is geometric evidence and never a legal-access conclusion.

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 before the field list, and every clause carries information (radii, null meaning, legality caveat, cost). It runs long at roughly 150 words, but the dashes and parentheses keep it scannable and no sentence is filler.

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

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

No output schema exists, yet the description fully describes the return shape per plot, including access_indicator values and rule version, plus edge cases (null, assessed=false). Cost and interpretation limits are covered. An agent has everything needed to call and read the result correctly.

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

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

Schema description coverage is 50% — only transaction_id documents itself as 'Transaction id (UUID) from a search result. This or transactionId is required.' The description adds nothing about the two-parameter alias (transactionId vs transaction_id) or which form to prefer. With trivial UUID parameters the schema does most of the work, so baseline 3 fits.

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

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

States a specific verb and resource: plot-by-plot road-access evidence for a single transaction, and enumerates exactly what it returns (nearest public road, any road, motorway distances, carriageway-edge distance, management category, functional class, ground-level flag, access_indicator). This is clearly distinguishable from siblings like get_transaction_transit or get_transaction_surroundings without opening the schema.

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

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

Gives a clear purpose statement ('to judge how its land sits relative to the road network') and names a concrete alternative for the no-transaction case: get_parcel_report's one-line road-access summary. It also warns that the motorway distance is a nuisance proxy, not an access measure. No explicit 'do not use this when' exclusion versus other transaction_* siblings, but the routing guidance is strong.

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 readOnly/destructive annotations: warns that a mining-terrain intersection is advisory only and must be verified with the mining authority, that a reservoir extent alone imposes no restriction, that absence of results is not an assertion of safety, and that the call costs 4 tokens with a refund on empty data. This is exactly the context an agent needs before presenting the result.

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 usage and cost statement is front-loaded, and each subsequent sentence carries interpretive value (status enums, legal caveats). It is dense and runs long, but almost nothing could be cut without losing a meaningful caveat.

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

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

There is no output schema, yet the description enumerates the return shape (per-plot overlap, mining status, mineral class semantics, reservoir status, share inside each, per-object details) and covers the all-important negative-result semantics. An agent can call and interpret this correctly without further documentation.

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

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

Schema description coverage is 50% — only transaction_id carries a schema description, and its purpose is obvious from the UUID pattern and the 'one transaction's land' phrasing. The description adds no format, sourcing, or fallback guidance for the two aliased ID parameters, so it neither compensates nor harms.

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

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

States a specific verb and resource: checks whether one transaction's land overlaps a mining terrain or groundwater reservoir, and enumerates the returned fields. It is clearly distinguishable from siblings like get_transaction_flood or get_transaction_landslide by naming the exact layers covered.

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 the alternative for parcels without a transaction (get_parcel_report), which is the key routing decision. It does not, however, differentiate against the other transaction_* siblings (flood, heritage, nature, etc.), leaving the agent to infer that those cover different layers.

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 establish that this is a read-only, non-destructive operation, and the description adds substantial behavioral context: measurement from the plot boundary, per-nuisance radius limits, null-distance meaning, assessed=false meaning, and token cost/refund behavior. The null caveat is especially valuable and not contradicted by 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 purpose is front-loaded, followed by the nuisance list, measurement caveats, null semantics, and cost. The description is dense but every sentence carries useful information and there is no 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 read-only tool with no output schema, the description covers what is measured, the radii, how distances are interpreted, what null and assessed=false mean, cost behavior, and the no-transaction alternative. An agent has enough context to call it correctly, with the only notable gap being parameter alias semantics.

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 only 50%: transaction_id has a description, but transactionId is undocumented, and the alias relationship is not explained in the tool description. The description says only 'for one transaction' and does not compensate by clarifying which parameter to use, whether both are accepted, or where the UUID comes from.

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

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

The description states a specific verb and resource: a plot-by-plot surroundings profile for one transaction, focused on nearby nuisances. It distinguishes itself from the sibling get_parcel_report by explaining that tool covers parcels with no 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 frames the use case as due diligence on nearby nuisances and names the key alternative for parcels without a transaction. That gives an agent a clear routing rule between this tool and get_parcel_report.

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 readOnly/non-destructive, but the description adds substantial context beyond them: the exact per-mode distance caps, the GTFS data source, the cost of 4 tokens with a refund on empty results, and the critical negative-result semantics. That last point prevents the agent from misreading an empty response as 'no transit access'.

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 thresholds, then the negative-result caveat and cost — every sentence carries information. It is dense but not padded; the parenthetical threshold list is the only spot that feels compressed rather than tight.

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

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

With no output schema, the description still explains the return shape (distance per mode, nearest stop name per mode present), the row-per-linked-plot granularity, and what an empty result means. Combined with the cost note, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 50%: transaction_id is documented in the schema, but the alias transactionId has no description and the two-parameter/zero-required arrangement is ambiguous. The description implies a transaction identifier is needed but never explains the duplicate alias or which to supply, leaving the schema to carry that burden 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?

States a specific verb and resource: check public-transport access for one transaction's linked plots, returning nearest stop distance per mode plus stop names. This is clearly distinguishable from neighboring tools like get_transaction_roads or get_transaction_surroundings.

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?

Opens with an explicit use case ('Use it to check public-transport access to one transaction's land'), which tells the agent when to reach for it. It does not name an alternative tool or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint/non-destructive, yet the description adds substantial behavioral detail: ordering ('Best matches' with exact/prefix first), RCN district flagging and separate listing of code-less districts, transaction count and date range on RCN matches, a partial-gmina warning, and the precedence rule. These are non-obvious traits not derivable from the schema or 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?

Purpose and the search_transactions follow-up are front-loaded, and every remaining clause carries operational content rather than filler. It is dense and somewhat sprawling in the dash-clause structure, but nothing is purely redundant — a minor trim would make it 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?

With no output schema, the description must explain return shape, and it does: matches carry TERYT code, parent unit, and exact follow-up calls; RCN district matches add counts and date ranges. Combined with the two fully-documented params and read-only annotations, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and already documents both params, but the description still adds meaning beyond it: the code-depth-to-hierarchy-level mapping is restated with the practical consequence, the 'parent wins when both are given' override resolves a real ambiguity the schema only hints at ('Ignored when parent is set'), and it clarifies that results are administrative units, never streets.

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

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

The opening sentence states a specific verb and resource ('Resolve a place name to TERYT codes, or browse the TERYT hierarchy') and immediately positions the tool relative to siblings by naming search_transactions and the teryt= follow-up. The two modes (search vs parent) are explicitly enumerated so the agent can tell this apart from search_parcels/resolve_parcel.

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

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

It states when to use this tool ('the first step before search_transactions'), how each mode selects behavior, precedence ('parent wins when both are given'), a disambiguation rule ('Prefer teryt where a name is ambiguous', with the Wałcz example), and an explicit exclusion routing to list_parcels_in_area for streets/parcels. Alternatives and exclusions are both covered.

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

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

Annotations only declare a safe read; the description goes far beyond them with token pricing (2 vs 5 API tokens), cursor paging only on light lists, the 500 km² / 12.6 km / 500-vertex refusal limits, free empty pages, TRUNCATED outlines being an arbitrary subset, and two explicitly enumerated coverage gaps. It also discloses an account-dependent behavior (parcel_id only for token/OAuth and paid/trial callers), which no annotation covers.

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

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

It is front-loaded and well-sectioned: purpose and sibling routing first, then entrance, then answer shapes, then filter rules, then coverage and limits. It is nonetheless very dense and some clauses duplicate the schema, so trimming would help, but almost every sentence carries 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?

There is no output schema and 14 loosely typed parameters, yet the description names both answer shapes and their fields, explains truncation, paging, token cost, coverage caveats and hard limits. An agent has everything it needs to call this correctly and to interpret a short or empty result without false conclusions.

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 already 100%, so the baseline is 3; the description still adds real semantics the schema lacks — street must be nominative and whole-word, buildingNumber must be exact and compound numbers ('84/92') will not match '84', empty pages carry close-name suggestions, and minArea/maxArea mean the registered parcel surface. Some content (radius max, teryt precedence, limit defaults) merely restates the schema, keeping it below a 5.

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

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

The first sentence states a concrete verb and resource ('List cadastral parcels') and immediately disambiguates from transactions. It then names four sibling tools (search_parcels, resolve_parcel, search_by_area/search_by_polygon, get_parcel_report) with the condition that selects each, so an agent can route without opening any schema.

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

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

Explicit when-to-use and when-not-to-use guidance is given for the sibling tools, for the entrance (street address vs precinct + number vs id prefix), and for the output mode (light list vs outlines). It also states exclusions directly, e.g. 'not together with a bbox', 'not on outline calls', and 'outside towns use 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, so safety is covered. The description adds substantial behavior beyond that: ambiguous names return several candidates rather than guessing, road parcels are flagged when a point falls on a street, results can be 'truncated', and not_covered/not_computed/corpus_coverage are explained with warnings about misinterpretation. That is rich context an agent would not get from the annotations alone.

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 three usage modes and is organized as bullets, which makes it easy to scan. It is dense but mostly earns its length, though the not_covered paragraph is verbose and could be tightened. It is slightly long for a four-parameter tool, but the structure prevents it from becoming unwieldy.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so: matching parcels include district, area and coordinates, 'truncated' indicates capping, and not_covered/not_computed/corpus_coverage are defined. It also explains the ambiguity response and next-step integration with search_transactions. Nothing essential is missing for correct invocation or interpretation.

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

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

Schema coverage is 100%, so the schema already documents each parameter, but the description adds real semantic value beyond it. It gives concrete examples for parcelId forms and q ('Sabnie 342/5', 'Ełk 461/3'), explains name-matching rules (exact, case-insensitive gmina or precinct), describes ambiguity behavior, and specifies that lat/lng must be a WGS84 point inside the parcel. This meaningfully improves correct parameter use.

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: 'Resolve a land parcel to its cadastral identity.' It immediately distinguishes this from nearby tools by naming the exact alternative for street addresses (list_parcels_in_area) and by pointing to search_transactions for sale history. An agent can tell exactly what this tool is for without opening the schema.

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

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

It states the exclusive usage rule ('using exactly ONE of') and then explains each mode: parcelId, q, and lat/lng. It explicitly rules out street addresses and redirects to list_parcels_in_area(street=, buildingNumber=), and it describes the follow-up path to search_transactions(parcelId). This is explicit when-to-use and when-not-to-use 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 discloses token cost (3 API tokens, 1 with summaryOnly), the bounding-box approximation that makes corners extend past radiusKm, and the exact permalink construction including which output fields to substitute. That is unusually rich context for a read-only tool.

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

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

Front-loaded purpose sentence followed by short labeled blocks (radius guidance, cost, permalink), so it scans well. Slightly dense with the permalink template, but no sentence is filler.

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

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

With 29 parameters and no output schema, it still tells the agent what comes back (deeds and prices), what the id/Location lines look like, and how to build a permalink. Minor gaps around ordering/sort behavior, but nothing that would cause a wrong call.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema lacks: radius sizing per search intent, that the area is a bounding box, that minArea/maxArea apply to every propertyType, and that summaryOnly makes limit/sort/page irrelevant.

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

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

States a specific verb and resource ('Find transactions within a radius of a point') and explicitly disambiguates from the name itself ('Returns TRANSACTIONS, despite the name'), while naming list_parcels_in_area as the alternative for parcels. An agent can pick it apart from search_transactions or search_by_polygon without opening the schema.

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

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

Gives concrete when-to-use conditions (neighborhoods/osiedla rather than TERYT districts, street-level searches), names the direct alternative for a different need, and adds operational rules: radius 0.3-0.5 km for a street, 2-5 km for a city area, and 'Take coordinates from the user, never invent them.'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context beyond that: it costs 5 API tokens, returns transactions with coordinates and prices, includes a permalink construction pattern, and clarifies the naming mismatch. This is useful behavioral information that helps the agent set expectations.

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 routing guidance, then adds cost and permalink details. Every sentence earns its place by helping the agent choose and use the tool correctly.

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 25-parameter read-only tool with no output schema, the description covers purpose, alternatives, token cost, return content, and permalink format. Combined with the fully documented schema, this is complete enough for correct 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 description coverage is 100%, so all 25 parameters are already well documented in the schema. The description only references the polygon and does not add parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: find transactions inside a GeoJSON Polygon. It explicitly distinguishes this from search_by_area for quick looks and list_parcels_in_area for land plots, and clarifies that it returns transactions despite the tool 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?

It gives explicit routing guidance: use this for precise neighborhood/osiedla boundaries, start with search_by_area for a quick look, and use list_parcels_in_area for land plots inside the same shape. It also states the token cost, which helps the agent decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description still adds real behavior: the register is near-complete but not live, empty results are ambiguous rather than proof of non-existence, and the call is token-free. The only residual friction is the muddled parenthetical 'a street address: list_parcels_in_area', which slightly clouds the routing instead of sharpening it.

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 constraint in the first clause, and the coverage caveat and cost note are compact, high-value lines. The nested parenthetical in the routing sentence costs a little readability but nearly every sentence carries distinct information.

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

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

For a two-parameter search with no output schema, it covers everything an agent needs: what comes back (district, area, GPS coordinates), how to interpret an empty result, and when to escalate to resolve_parcel with the full ID. No annotation or schema gap is left unaddressed.

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 both parameters ('q' prefix with min 3 chars, 'limit' 1-10) are documented inline, so the schema already carries the load. The description's example prefix '146518_8.01' duplicates the schema example rather than extending it, so this is baseline territory.

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

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

States a specific verb and resource ('autocomplete land parcels by cadastral ID PREFIX only') and immediately bounds the scope by naming the operations it is not ('never by area'). The routing sentence names the two siblings that handle area/shape and full-ID resolution, so an agent can 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?

Explicitly partitions the task space: prefix search here, list_parcels_in_area for a place or shape, resolve_parcel for a coordinate or 'locality + number'. It even supplies a negative rule ('never by area') that closes the most likely misuse path.

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 cover the read-only safety profile, but the description adds crucial behavioral context: silent zero-row failures when location names aren't RCN districts, literal street matching where a miss looks like 'no transactions', null-rate caveats for marketType and transaction_date, and interpretation of inline [...] notes for computed values. These are non-obvious traits that materially affect correct invocation.

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 information-dense and front-loads the core capability before moving to workflow, data caveats, and permalink construction. There is some redundancy with the schema's own parameter descriptions (e.g., street matching, marketType nulls), which a stricter version could trim, but little is wasted.

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 33-parameter, zero-required tool with no output schema, the description is remarkably complete: it states what fields are returned, explains the mandatory location-resolution workflow, discloses major data gaps, and even gives the permalink template for linking to a result. An agent has everything needed to avoid common failure modes.

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 rich per-parameter descriptions, so the baseline is 3. The description still adds value by framing teryt= as the preferred exact-match routing parameter after list_locations, and by highlighting that location= is only for rcn_district values. Some notes (street nominative form, marketType null drop) duplicate schema text, keeping this from a 5.

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

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

States a specific verb ('Find'), resource ('individual Polish real-estate transactions'), and scope (national RCN registry, 8M+ notarial deeds, not asking prices). It also lists the filterable dimensions and distinguishes the data source from asking-price sources, making it immediately clear how this differs from sibling search 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?

Explicitly prescribes the prerequisite workflow: resolve place with list_locations, then pass its TERYT code as teryt=. It warns that location= only works for RCN districts and that other names silently return zero rows, and routes neighborhood searches to search_by_area. This is exactly the when/when-not/alternatives guidance an agent needs.

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