resolve_parcel

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.