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

No annotations are provided, so the description carries the full load. It does disclose the output shape and the longitude/latitude ordering, which is genuinely useful and prevents a common agent error. However it omits whether result volume is bounded by the default limit, how sorting/ordering affects the collection, and whether photos without GPS are silently excluded.

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?

Two sentences, zero waste, with the output format and coordinate order front-loaded before the filter-parity note. Nothing could be trimmed without losing information.

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 not be described, and the description correctly covers the shape and coordinate convention that an agent must know to render a map. For a 13-parameter, annotation-free query tool it is close to complete, though a note on default limit behavior and the implicit GPS filter would close the remaining gap.

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 69%, which sits in the mid band, so the schema does much of the work. The description adds only a pointer that filters match media.list, without clarifying the undocumented parameters (limit, shop_id, near_lng, taken_before, summary_status) or the interaction between has_location and the tool's inherent GPS restriction.

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?

States the specific verb and resource: returns photos that have GPS as a GeoJSON FeatureCollection, with the coordinate order spelled out. It distinguishes itself from media_list by naming the representation ('ready for a map') and by deferring filtering to media.list's filter set, so an agent knows this is the geo-export variant.

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?

'ready for a map' implies the when-to-use case (mapping spatially-located photos), but there is no explicit guidance on when NOT to use it – e.g. that media_list/media_search should be used when no map/GeoJSON is needed. The reference to media.list only explains filter parity, not tool selection.

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