search_places_nearby

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

Annotations already declare readOnlyHint=true and destructiveHint=false, signaling a safe read operation. The description adds critical behavioral details beyond annotations: the radius-based circle constraint, popularity/distance ranking, the 20-result limit (even though the parameter max_results has a default of 10, the description clarifies the absolute ceiling), and the lack of paging. It doesn't mention that results are returned as a JSON array of place objects or any specific output format, but the presence of an output schema alleviates that need.

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 sentences, all essential. The first sentence states the core operation and ranking. The second provides sibling differentiation. The third adds critical constraints and examples. This is tight and front-loaded, though the lack of enum details for rank_by and implicitly for detail slightly reduces completeness for a zero-coverage schema.

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 7 parameters, 0% schema coverage, and a relevant sibling, the description covers the most important aspects: spatial use case, alternative tool, output limits, and filter examples. It misses explaining the 'detail' parameter and the exact format for rank_by, but those are less critical for an initial call. The output schema presumably details return fields, so the description's brevity on output is acceptable.

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%, meaning the description must fully explain the parameters. The description mentions the circle concept (implying radius_metres and the centre latitude/longitude), the ranking (rank_by), and the filter (included_types with examples). However, it does not explain the 'detail' parameter or the exact valid values for 'rank_by' (e.g., POPULARITY vs. DISTANCE). It also does not explicitly describe the bounds or meaning of latitude/longitude. Despite these gaps, the explanation adds substantial value beyond the bare schema titles.

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 specific verbs ('List places inside a circle') and names the ranking bases ('popularity or by distance'). It clearly distinguishes this tool from its sibling 'search_places_by_text' by contrasting spatial vs. text-based queries.

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 explicitly states when to use this tool ('when you have a point and want what is around it') and when to use the sibling ('use search_places_by_text when you can describe what you want'). It also notes key constraints: up to 20 results, no paging, and gives examples of valid filter types.

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