UK Data: England river and tide levels

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.

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

Annotations already cover readOnly/idempotent/non-destructive/open-world, so the description's added value is the credit cost, the upstream source (Environment Agency real-time flood-monitoring API), the 6-hour staleness flag, and the caveat that some gauges don't report flow. It does not say what the nearby-search response looks like or how many readings come back, which is a modest remaining gap given there is no output schema.

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-loads the resource and the two modes, then the operational caveats and cost. The 'kayakers, canoeists and anglers' sentence is audience flavor rather than instruction, but it is short and does convey the practical use case, 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?

Covers retrieval mode, units, data source, freshness caveat, coverage limitation, and cost — everything needed to call a 5-parameter, all-optional read tool correctly. Return shape is only implied, but with no output schema and full parameter documentation the description is sufficient.

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 already documents all five parameters including their ranges and defaults. The description reinforces the station_id vs lat/lon exclusivity but says nothing about limit or dist_km, so it adds little meaning beyond the structured fields — the 3 baseline 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?

States a specific resource (river flow in cumecs) and two retrieval modes (single gauge vs nearest gauges to a point). The word 'flow' plus 'cumecs' cleanly separates it from the sibling river_level_now, so an agent can pick between level and flow 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?

Explicitly tells the agent to pass station_id for one gauge or lat/lon for a nearby search, and warns that only some gauges measure flow and that readings older than 6 hours are flagged stale. It never names an alternative sibling (e.g. river_level_now, river_stations_on_river) as the fallback, so there is clear context but no explicit either/or routing.

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

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

Adds value beyond the readOnly/idempotent/openWorld annotations: upstream source (Environment Agency flood-monitoring API), that the series is downsampled rather than raw, that it is not a forecast, and a 1-credit cost. With annotations already covering the safety profile, this is solid but not rich - no mention of rate limits, error behavior for bad station IDs, or update cadence.

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 what the tool returns before the framing sentence and caveats. Mildly dense with parentheticals, but every clause carries information (defaults, window limit, non-forecast caveat, cost).

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?

No output schema exists, and the description compensates by enumerating the returned summary fields (min, max, change since start, rising/falling/steady) plus the thinning caveat. A user could call it correctly; only failure modes and station-ID discovery are unaddressed.

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 all three parameters are already documented in the schema. The description restates the 'since' default and 7-day bound but adds no format examples or guidance on choosing 'points' beyond what the schema says. Baseline 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?

States a concrete verb and resource: river level readings at one gauge over a time window, with summary statistics. The 'history' scope plus the 7-day limit implicitly separates it from river_level_now and river_level_record, though no sibling is named 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?

Gives a real use case ('has the river peaked yet' for flood watchers and anglers) and constraints (up to 7 days back, not a forecast). It never names an alternative tool to use instead, so the when-not guidance is only implied by the time-window framing.

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

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.

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

Annotations already cover read-only, idempotent and open-world, and the description adds genuinely new behavior: the EA flood-monitoring API source, the station-stage scale, limited year coverage and that some gauges publish no records at all, plus a credit cost. Return shape granularity (units, null handling) is the only thing left implicit.

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-loads the return values first, then the use case, then the source and caveats, then cost — a sensible order. The audience list is slightly promotional but doubles as usage guidance, 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?

For a one-parameter read tool with annotations and no output schema, every decision an agent needs is present: what it returns, what the data covers, when it may come back empty, and the credit cost.

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 there is a single parameter with an example, so the schema carries the semantics. The description only implies the single-gauge scoping ("one Environment Agency gauge") and adds nothing about how station_id maps to coverage gaps.

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: record high, record low and highest recent level at one EA gauge, plus the derived delta from the record. This is clearly distinguishable from level-now and level-history siblings even though none are named 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?

Frames the decision context well ("is this a record flood" for journalists, residents, property buyers), which tells an agent when this is the right tool. It stops short of naming alternatives such as river_level_now or river_level_history or stating exclusions.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior, and the description adds material operational context: the Environment Agency source, a 1-credit cost, exact-name matching with one 'River <Name>' retry, reporting of the resolved name, no spelling guessing, and non-downstream ordering. These are real behavioral traits beyond 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 definition is front-loaded with the resource and return fields, then adds matching caveats and cost; every sentence carries operational information. It is somewhat dense, and 'upstream name match' versus 'upstream-to-downstream order' uses 'upstream' in two senses, but there is little outright waste.

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 two-parameter read-only lookup with no output schema, the description is complete: it identifies the source, return fields, matching behavior, ordering caveat, and cost. The limit/pagination detail is already in the schema, so nothing critical is missing.

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 schema description coverage at 100%, the baseline is 3, and the description largely reinforces rather than extends the schema's river_name guidance (exact EA spelling, retry examples). It adds 'reports the name it used' and the no-guessing caveat, but says nothing extra about limit, so it is useful but not a major semantic addition.

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 opens with a specific verb and resource—'Lists the Environment Agency level gauges on a named river in England'—and names the returned fields: station ids, towns and coordinates. That is enough to distinguish it from sibling river-level tools, which report readings or flow rather than a station inventory.

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 a concrete use case ('boaters planning a trip or anyone following a river downstream') and explains the matching limitation and retry, but it never explicitly names alternatives or says when to choose river_level_now or river_flow_now instead. The intended context is clear; exclusions and sibling routing are left implicit.

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