market_reverse_geocode

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful extra context: 'Experimental map API' warns about stability, and the note about capitalized Lat/Lon query parameters reveals a behavioral detail about the underlying API beyond the schema.

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 three short sentences with the core purpose front-loaded. The additional notes about experimental status and parameter capitalization are each informative and non-redundant. No wasted words.

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 a simple read-only tool with two fully documented parameters, a rich annotation set, and an output schema, the description covers the essential context. The only slight gap is that the 'capitalized Lat/Lon' note is not reconciled with the lowercase latitude/longitude schema, which could momentarily confuse an agent, but this does not prevent correct invocation.

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 the schema already provides clear descriptions for both latitude and longitude. The description adds little beyond labeling them as coordinates, so it does not exceed the baseline required when the schema handles the semantic load.

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 specific verb and resource: 'Resolve coordinates into address fields and display_name.' This clearly conveys reverse geocoding. It does not explicitly name the sibling `market_geocode_address` or contrast with it, so it stops short of full sibling differentiation despite the tool name making the distinction obvious.

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 purpose implies when to use the tool: when you have coordinates and need address fields. However, it provides no explicit when-not-to-use guidance, no mention of alternatives, and no prerequisites or context about preferring another tool. The usage is only implied.

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