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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the description is not carrying the safety burden. It nonetheless adds real behavioral facts beyond them: the call is free, results are capped at 12 ids, and a radius under 20 km collapses to the anchor city only. It stops short of describing failure modes or truncation edge cases.

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 short sentences, no padding, each carrying information. The only structural nit is that 'Free.' leads ahead of the purpose statement, so the first thing an agent reads is a cost note rather than what the tool does.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description supplies cost, result caps, radius semantics and a downstream integration hint. It is nearly complete for a 2-parameter tool; only sibling differentiation and error behavior are absent.

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 what the parameters produce ('anchors and radius_km become at most 12 location ids') and how the radius is consumed by the index, which is not derivable from the schema alone. 'Under 20 km only the anchor city is used' partially repeats the schema's radius description, slightly diluting the added value.

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 concrete transformation: anchors plus radius_km are resolved into at most 12 location ids. That is a specific verb+resource an agent can act on. It does not, however, distinguish itself explicitly from the sibling resolve_location, leaving the agent to infer the area-vs-single-location split.

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?

Usage is implied rather than stated: 'The search index has no radius: pass geo_ids as the location filter' tells the agent what to do with the result downstream, and 'Free' signals a cost consideration. There is no explicit when-to-use-this-vs-alternatives guidance (e.g. versus resolve_location or check_candidates).

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