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

Adds real context beyond the readOnly/idempotent annotations: it discloses the refusal policy ('Places, never people: religion or who lives there is refused') and what the response contains (best/worst areas, counts, percentiles, legend, map layer). No rate limits or failure modes mentioned, so not a 5.

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?

A single dense paragraph that front-loads the core purpose before examples and constraints. Nearly every clause carries weight, though the formula/output detail is somewhat packed and could have been left to the 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?

For a complex tool with an output schema and 100% param coverage, the description supplies the missing conceptual layer: what the tool computes, the refusal constraint, and the return contents. Nothing essential to correct invocation is absent.

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 coverage is 100% and the schema itself fully documents top_n, area_ids, criterion, direction, preset_id and deeply explains the formula enum. The description only restates that a criterion is 'sets of OSM tag matchers and a formula', adding little beyond structured fields. Baseline 3 is appropriate.

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 (evaluate) and resource (a criterion counting places within neighbourhood boundaries) with concrete example queries and explicit scope of every London neighbourhood. An agent can distinguish this from rank_areas_by_metric or list_custom_presets without opening the 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?

Clearly states the two input modes (a preset_id from list_custom_presets or a user-built criterion) and gives example phrasings that select the tool. It stops short of explicitly naming alternatives to avoid or the conditions under which another ranking tool is better.

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