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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description layers on real operational context: upstream providers (Photon with Nominatim fallback), the 404-on-empty-ocean behavior, and that such failures are not charged. It also discloses the payment model (x402 USDC on Base, $0.001 per successful call) and the paywall handshake (unpaid call returns a PaymentRequired object), which annotations cannot express.

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 trigger condition, then the return shape, then data provenance, then error/billing behavior. Three dense sentences with no filler, and the highest-value information (when to use, what you get) leads.

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?

With no output schema, the description takes on the return-value burden and does so (display name, country, city, street when available, matched lat/lon). Combined with error semantics, provenance, and payment details, an agent has everything needed to call it and interpret the result.

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% and both params are documented there with valid ranges, so the schema carries the load. The description adds no syntax, format, or precision guidance beyond what the schema states, so the baseline of 3 applies.

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 gives a specific verb+resource (reverse geocode coordinates into a human-readable place) and enumerates the returned fields. It distinguishes itself implicitly from the forward-geocoding siblings by framing the trigger as 'agent has coordinates', but it never names geocode or geocode_search, so the differentiation is only inferred.

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 gives a concrete when-to-use trigger ('Use when an agent has coordinates (from GPS, a map click or another API) and needs a human-readable place'), which is stronger than most. It omits an explicit when-not / alternative clause (e.g. 'for a text query use geocode_search instead'), so the routing is clear but not fully disambiguated.

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