geo.find_parcel

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

The annotations already declare readOnlyHint and openWorldHint, but the description adds material behavioral context beyond them: results carry provenance and coverage, an empty result with coverage.registry='none' means no source rather than no parcel, and jurisdiction-resolution ambiguity is handled internally. This is exactly the kind of operational nuance an agent needs to interpret results correctly.

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 yet dense; every sentence serves a purpose. The core action is front-loaded, followed by critical operational guidance, and no words are wasted on restating schema fields or repeating annotations.

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

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

For a tool with two query modes, jurisdiction-resolution semantics, candidate disambiguation, provenance/coverage concerns, and an open-world empty-result case, the description covers essentially all behavioral requirements. The output schema covers return shape, so the description only needs to explain semantics, which it does thoroughly.

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

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

With schema description coverage at 0%, the description compensates by explicitly naming the PIN, the lon/lat point, and the jurisdiction string, and by explaining how jurisdiction should be passed ('as given'). It adds meaning beyond the bare schema, though it does not fully detail parameter constraints such as coordinate format or whether pin and lon/lat are mutually exclusive beyond the 'or' phrasing.

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: 'Find parcel records in a Virginia jurisdiction by parcel PIN or by a lon/lat point.' It also scopes the geographic domain and identifies the two supported query modes, making the purpose unambiguous and naturally distinct from sibling tools like geo.find_zoning or geo.find_boundaries.

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 instructs the agent to pass the user's jurisdiction string as given and states that resolution/ambiguities are handled inside the tool, which also implies not to pre-resolve via registry.resolve_jurisdiction. It gives a useful exclusion ('Not for street addresses yet') and a handling rule ('candidate lists must go back to the user unchosen'). It does not explicitly name the zoning/boundaries siblings as alternatives for other query types, so it stops short of full alternative mapping.

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