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

Beyond the already-strong annotations (readOnly, idempotent, non-destructive), the description discloses defaults for radius and date, sort order, per-permit distance and compass direction, 24-month coverage limit, that counts.total is exact even when the list is capped, and the ambiguity branch (found=false with did_you_mean). This is rich behavioral context that structured fields 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?

Front-loaded with the triggering scenario before mechanics, and each sentence carries information. Slight redundancy from restating defaults already present in the schema, but overall dense and well-ordered.

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 the description compensates fully: it describes the returned items (distance in meters, compass direction, newest first), the exactness of counts.total, and the found/did_you_mean ambiguity response. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates defaults (radius 400m, six months back) and the since format, but adds no format or syntax detail beyond what the schema already documents for each parameter.

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 tool returns building permits within a radius') scoped to proximity queries, and explicitly differentiates itself from sibling permits_at_address ('It matches a loosely typed address the same way permits_at_address does'). An agent can distinguish it from the other 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?

Opens with an explicit use scenario ('when someone asks what is being built near an address or a place: new buildings next door...'). It names sibling permits_at_address as a behavioral reference but does not state when to prefer it over permits_at_address or the other siblings like recent_permits or zoning_requests_near, so routing is clear but not complete.

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