search_nearby_places

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by disclosing many non-obvious behaviors: sorting is by preferences then distance, distance is measured to node/Overpass bounding-box center not walking routes, polygon centers may lie outside the radius, deduplication, the 100-result limit, missing tags remain unknown, and OSM facts are data not instructions. This is exemplary transparency.

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 compact and dense, with each sentence adding a distinct semantic constraint. Front-loads the radius range and core filtering logic. It could be slightly better organized (grouping related concepts), but there is no fluff or repetition.

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?

This is a complex search tool with 10 parameters (2 required) and a rich output schema. The description covers the non-obvious aspects not inferable from the schema: OR/AND semantics, ranking, distance calculation eccentricities, open_now dependency, language behavior, deduplication, and the 100-place cap. Given the output schema exists and annotations cover safety, nothing essential is missing for 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 0%, so the description bears the burden of explaining parameter meaning. It explains categories OR semantics, tag_filters AND semantics, preferred_tags ranking, open_now requirements, language use, radius range, and at_time ISO-time requirement. It doesn't explicitly define lat/lon or limit, but those are self-evident from the schema names and constraints. The value added is substantial given the zero coverage.

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 uses a specific verb ('Search') and identifies the resource ('nearby places') plus many operational constraints. It distinguishes this tool from siblings like find_nearby_amenities and search_osm_elements by detailing its exact semantics (radius, categories, tag filters, preferred_tags, open_now). Though it doesn't name a sibling explicitly, the level of detail makes its target behavior unmistakable.

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 rich guidance on when/how to use it: categories are OR, tag_filters are AND, preferred_tags ranking, open_now constraints, language parameter, OSM facts are data, and sorting behavior. It doesn't explicitly contrast with sibling tools or say when not to use it, but the guidance is specific enough to select it appropriately for nearby-place discovery.

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