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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), and the description adds genuinely new behavioral facts: readings are typically 15 minutes apart, old readings are flagged stale, the value is gauge height rather than water depth, it is not a flood-warning service, and it costs 1 credit. These are exactly the caveats that prevent misinterpretation of the returned number.

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 core capability is front-loaded in the first sentence, followed by audience, provenance, caveats and cost. It is slightly long at four-plus sentences, but each one carries distinct information (data source, staleness, unit semantics, non-flood-warning disclaimer), so little is wasted.

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?

There is no output schema, yet the description still tells the agent what comes back: a level, a low/normal/high classification against the typical range, and flow where measured. Combined with the staleness note and credit cost, an agent has everything needed to call and interpret this tool.

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 single station_id parameter is documented there, including the example format and the pointer to river_levels_near for discovery. The description only reinforces that it is 'one' gauge — it adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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 names a specific verb and resource — 'Latest water level at one Environment Agency gauge' — plus what is returned (level vs. typical range, and flow where available). This clearly separates it from siblings like river_flow_now, river_level_history and river_level_record without the agent needing to open their schemas.

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 supplies audience context ('useful for boaters, anglers and residents asking whether the river is high right now'), which implies the 'now' use case. However, it never names an alternative tool or states when NOT to use it — e.g. that historical questions belong to river_level_history or that station discovery is done via river_levels_near — so the agent must infer routing from sibling names.

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