find_pois

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

With no annotations, the description carries the full burden. It usefully discloses that results are sorted by 'interest' and that only places mapped in OpenStreetMap are returned — a real coverage caveat. It omits other behaviors though, such as what happens when `categories` is omitted and how radius/limit interact.

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?

Front-loaded with the core purpose, then the category examples and caveats. The category enumeration is somewhat long but earns its place by mapping opaque enum values to human concepts.

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-format detail is not required. For a read/search tool with 5 params, the description supplies the essential behavioral context (sorting, OSM data source, category semantics); only the default-category behavior is left unstated.

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 schema documents none of the 5 parameters. The description partially compensates by explaining what the category values mean (e.g. `transport` = bus stops/stations for car-free travel), but lat, lon, limit and radius_km get no added meaning.

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 gives a specific verb and resource ('Cherche des points notables autour d'un lieu') plus concrete examples of what kinds of points (cascades, points de vue, lacs, sommets, patrimoine, eau, refuges), and frames the goal as itinerary planning. This distinguishes it from route-finding siblings, though it never names those siblings explicitly.

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?

It hints at usage by tying the tool to itinerary planning and by noting that adding the `transport` category supports car-free departures. However, there is no explicit guidance on when to choose this over find_hiking_routes, find_bivouac_spots, or route_between, so the routing decision is left to inference.

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