Reverse geocode coordinates

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

Annotations already declare readOnlyHint=true, so the tool is known to be non-destructive. The description adds the behavioral detail that it uses Nominatim (an external service), hinting at potential third-party dependencies. No additional behavioral traits are disclosed (e.g., rate limits, fallback behavior, or response structure), but given the annotations cover safety, the description provides minimal extra value.

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 a single short sentence: 'Converts coordinates into the nearest address or place name (Nominatim).' It is front-loaded, contains no filler, and every word adds meaningful context about the action, output, and backend. Ideal conciseness.

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 tool has 3 parameters, no output schema, and is simple conceptually, the description still falls short. It does not explain the return format (e.g., string, object with fields), error cases (e.g., what happens if no address found), or any precision or success criteria. The description is too minimal for an agent to fully understand the tool's behavior without additional knowledge.

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?

The input schema has 3 parameters with only 33% description coverage (language has a description, latitude/longitude do not). The tool description adds no parameter-level details—it does not explain that latitude/longitude should be in decimal degrees (WGS84), nor does it clarify the effect of the optional language parameter. With low schema coverage, the description should compensate, but it fails to do so.

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 'Converts coordinates into the nearest address or place name (Nominatim)', using a specific verb and resource. It uniquely distinguishes this tool from siblings like 'geocode' (which likely does the reverse) and other tools like 'route' or 'find_nearby_pois' by naming the exact conversion task and the backend service.

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 does not explicitly state when to use this tool vs. alternatives. The tool name and description strongly imply it is for converting coordinates to addresses/place names, which suggests the opposite of the sibling 'geocode', but no direct guidance such as 'Use this when you have coordinates; use geocode for addresses' is provided. The usage is implied but not articulated.

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