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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds real context beyond them: the gauge is the nearest working one, it measures a single point rather than the exact location, the record-completeness indicator, the data source and its tipping-bucket nature, and a cost of 1 credit.

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 measurement and units, then audience, then source, then the two caveats and cost. Dense but every clause carries information an agent or user needs.

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?

With no output schema, the description still tells you what comes back: millimetres, wettest 15-minute intensity, and record completeness. Caveats about point measurement and non-forecast status close the remaining gaps for a read-only lookup.

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%, so the schema carries the mechanics. The description still adds interpretation by framing the window as 'last 24 hours (or up to 7 days)' and tying the reading to the nearest working gauge, which explains what dist_km is actually searching for.

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 and resource ('How much rain fell over the last 24 hours... at the nearest working Environment Agency rain gauge, in millimetres') with scope (up to 7 days), units, and source. It also declares what it is NOT ('not a forecast'), which separates it from rain_forecast_next_hours and weather.

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?

Names concrete audiences and the question it answers ('how much rain did we get'), and rules out forecast use. It stops short of naming actual sibling tools, so an agent must infer that rain_forecast_next_hours or river_level_now cover the alternatives.

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