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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: the Nominatim data source, a maximum of 5 hits, display name and address parts in results, pricing, and the x-credit-token header option. This goes well beyond the annotations and helps the agent understand external dependencies and call costs.

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 dense but each sentence earns its place: core functionality, result shape, data-quality caveat, and pricing/authentication context. It front-loads the primary purpose before cost details, making it easy for an agent to quickly identify 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?

Given the rich annotations and the presence of an output schema, the description provides enough context for correct invocation: both geocoding modes, parameter patterns, result count, data-source caveat, and access/pricing model. Nothing essential is missing for an agent to decide when and how to call 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 descriptions are present for all three parameters, so the baseline is 3. The description adds meaningful semantics by showing that q= is for forward geocoding while lat=+lon= are used together for reverse geocoding, clarifying how the parameters combine into two distinct usage modes.

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 clearly states a specific verb and resource: 'Address ↔ coordinates via OpenStreetMap' with forward and reverse geocoding modes. It also distinguishes itself by calling out 'Community map data — not a postal authority,' separating it from address-verification siblings like address_check and address_trust.

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 description gives clear usage context for both forward geocoding with q= and reverse geocoding with lat=+lon=. It offers an implicit when-not by stating it is not a postal authority, but it does not explicitly name alternative sibling tools, so it falls short of a 5.

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