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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description goes well beyond them with hard limits (500 addresses, 300 places per answer, n up to 50), the count-mode exemption from that cap, the behavior of an unrecognized category word (returns the full list), source-quality caveats ('classic amenities are well covered, trades patchily'), and background-job throttling. Nothing here contradicts the annotations.

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 purpose and routing are front-loaded, and most sentences carry distinct information (limits, categories, source comparison). It is a dense paragraph heavy with parentheticals, which slightly impedes scanning, but there is little pure filler.

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?

For a tool with nested source objects, three modes and no output schema, the description covers inputs, limits, fallbacks and the cross-tool decision well. The shape of results per mode is only lightly implied (the schema notes results come back under the caller's id), so a touch more on return content would make it fully complete.

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?

With 75% schema coverage the schema already documents n, radius_km defaults and the source block, but the description adds meaning the schema lacks: the actual category vocabulary (schema leaves 'category' undocumented), the records × n relationship behind the 300-place cap, and mode semantics. It does not explain the id/name/address fields beyond what the schema says, so it stops short of a 5.

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 a specific verb+resource+scope: 'the nearest places of a kind' for up to 500 addresses/points in the UK and US, and enumerates its three operating modes (nearest, count, list). It explicitly differentiates itself from sibling find_official_places by naming the data sources behind each (open map index vs CQC/NHS registers), so an agent can distinguish the two without opening either schema.

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?

Gives explicit routing: use this for open-map categories (pharmacy, station, supermarket, ...), but use find_official_places for A&E, hospitals, GP practices, care homes, dentists and NHS pharmacies in England 'with ratings', because open map data mixes these up. It also defines when each mode applies (count has no result cap; nearest/list cap at 300). This is close to a complete when/when-not/alternative statement.

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