TerraMCP

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

Annotations cover the safety profile (readOnly, openWorld, idempotent=false, destructive=false), and the description layers on substantial extra context: no API key required, anonymous rate limits of 60/hour and 300/day per IP and session, key-based fallback after monthly quota, SI normalisation, provenance, and licence warnings. This is exactly the behavioral detail annotations cannot carry.

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 purpose and scope are front-loaded, which is good, but the paragraph is padded with boilerplate ('TerraMCP is a Wrench AI service') that does not help an agent call the tool. Rate-limit and licence sentences earn their place; the marketing line does not.

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 single-parameter read-only list tool with no output schema, the description supplies the operational constraints an agent needs: scope, licensing, auth-free access, and throttling. It is only slightly short on return-shape hints, saying merely 'returns source data and provenance'.

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?

Only one parameter (limit) exists and schema description coverage is 100%, so the schema already documents its bounds and default. The description adds nothing about the limit parameter, making the baseline 3 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 and resource ('List BGS OGC API Features collections') and narrows scope precisely to the two collections with verified OGL terms. The implicit contrast with bgs_features (collections vs features) is inferable but never made explicit, so it falls short of full sibling differentiation.

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?

The description explains which collections are included and why others are excluded ('pending licence checks'), which is useful selection context. However, it gives no explicit when-to-use guidance or routing to sibling tools such as bgs_features for the actual feature data.

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?

Goes well beyond the annotations (readOnly/openWorld/non-destructive) by disclosing anonymous rate limits (60/hour, 300/day per IP and session), the no-API-key open-data model, quota fallback behavior, SI normalisation of hydrological units, provenance in the response, and the interpretative caveat about bbox vs. point conditions. This is exactly the operational context annotations cannot carry.

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 the key caveat are front-loaded in the first two sentences, which is the right ordering. It is dense but mostly earns its place, with only mild promotional filler ('TerraMCP is a Wrench AI service') that could be trimmed.

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 carries the return-value burden and does so reasonably ('bounded properties and geometry summaries', source data and provenance). Combined with the rate limits and the bbox-vs-point caveat, an agent has enough to call and interpret it, though field-level detail on the returned properties 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 description coverage is 100%, so the baseline is 3. The description reinforces the bbox semantics of radius_km and the 10 km cap and points at bgs_collections for collection values, but these largely restate what the schema already documents, adding little new parameter-level meaning.

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 (query), a specific resource (BGS borehole index / geology 625k features), and the spatial scope (features intersecting a WGS84 bounding box around a UK point, up to 10 km). The named collection set makes it clearly distinct from siblings like bgs_collections (which lists collections) or the EA/flood spatial tools.

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 clear context for use (spatial proximity query in the UK, radius capped at 10 km) and implicitly routes the agent to bgs_collections for the collection identifier. It also supplies an important interpretive exclusion — bbox matches do not establish conditions at the exact point — but names no explicit alternative tool when a point-exact answer is needed.

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?

Goes well beyond the annotations (readOnly/openWorld/non-destructive) by disclosing BYO OpenTopography key requirements, an Enterprise key for commercial use, a mandatory TerraMCP Bearer key with a URL, and what the response contains (source data plus provenance, hydrological units normalised to SI). These are exactly the operational facts an agent cannot infer from 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?

Front-loaded with the core action and the bbox constraint, which is good. However 'TerraMCP is a Wrench AI service' is filler and the OpenTopography key requirement is effectively stated twice ('BYO OpenTopography key only' / 'your own OpenTopography key').

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 describing the return ('source data and provenance') and the unit convention. Auth prerequisites, size limits and dataset options are all covered, leaving nothing critical unstated for a 2-parameter 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 description coverage is 100%, so bbox ordering, the 100 km² cap and the dataset enum are already documented. The description largely restates these ('Supply WGS84 bbox [west,south,east,north] covering at most 100 km² and dataset'), adding little syntax or selection guidance beyond what the schema provides.

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?

Specific verb ('Get') plus a precisely bounded resource ('a bounded elevation GeoTIFF from OpenTopography'), scoped to a stated purpose ('terrain analysis'). It is unmistakably distinct from every sibling, none of which retrieve DEM rasters.

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?

States the triggering condition ('where an appropriate local DEM is unavailable') and routes the agent to an alternative for a specific region ('UK projects should prefer Defra 1 m LiDAR DTM'). Both when-to-use and when-to-use-something-else are explicit.

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?

Beyond the annotations (readOnly, openWorld, non-destructive), the description discloses anonymous rate limits (60/hour, 300/day per IP and session), that no API key is required with anonymous fallback after quota, that geometry is omitted from returns, that hydrological units are normalised to SI, and that source licence warnings apply. This is substantial operational context the annotations do not carry.

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 is correctly front-loaded, but the description is dense with boilerplate that does not aid tool selection: 'TerraMCP is a Wrench AI service', quota fallback mechanics, and licence-warning phrasing consume space. It is not wasteful enough to be a 2, but several sentences do not earn their place in a selection-time description.

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 usefully sketches the return shape (bounded attributes, no full geometry, source data and provenance) and notes SI normalisation and result limits. Combined with rich annotations and a fully documented schema, an agent has enough to invoke it correctly; only the precise attribute set returned is left unstated.

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 description coverage is 100%, so each of the five parameters is already documented, and the description largely restates that (WGS84, bounding-box behaviour, bounded result set). The only mild addition is framing the search as a 'small' bounding box, which does not materially extend the schema's meaning. 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?

Names a specific verb (Query) and four concrete resources (Main Rivers, Recorded Flood Outlines, Flood Warning Areas, Spatial Flood Defences) scoped to a WGS84 bounding box. It also implicitly separates itself from the flood-warning siblings by stating the data are 'not live warnings or a site-specific flood risk determination', so an agent can distinguish it from flood_list_warnings and flood_zone_at_point.

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?

The exclusion clause ('Historical/administrative datasets are not live warnings') tells the agent when this tool is the wrong choice and implies the warning siblings are the right ones. However, no alternative tool is named explicitly, so the routing guidance is contextual rather than prescriptive.

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?

Goes well beyond the annotations (readOnly/openWorld/non-destructive), disclosing the OGL v3 licence, the critical caveat that absence is not evidence of no groundwater risk, SI normalisation, provenance handling, and concrete anonymous rate limits (60/hour, 300/day) plus key/quota fallback. This is exactly the operational context annotations cannot convey.

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 purpose and return contents, then adds genuinely useful caveats and rate limits. However, filler such as 'TerraMCP is a Wrench AI service' and the vague 'Source licence warnings apply' consume space without helping the agent select or invoke the tool.

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 carries the return burden well by naming the fields returned (station IDs, aquifer, datum, measures), their downstream use, and provenance/normalisation behavior. Combined with annotations covering the safety profile, an agent has everything needed to call it correctly.

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 description coverage is 100%, so lat, lon, limit and radius_km are fully documented in the schema with ranges and defaults. The description only gestures at 'near a UK point' and adds no format or constraint detail beyond what the schema already provides, so the 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 specific verb (Find), resource (EA Hydrology groundwater monitoring boreholes), and scope (near a UK point), and ties the resource to the sibling ea_hydro_series(property=groundwaterLevel) it feeds. An agent can distinguish this station-locator from the series-reading siblings 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?

Establishes clear context for use and points to the downstream consumer (ea_hydro_series with property=groundwaterLevel), which effectively tells the agent when this tool is the right entry point. It stops short of naming an explicit alternative to use instead or stating a when-not-to-use condition.

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=true, destructive=false), and the description adds substantial behavioral context beyond them: open data with no API key, anonymous rate limits (60/hour, 300/day per IP and session), key-based higher limits with anonymous fallback, SI normalisation, provenance, and source licence warnings. This is exactly the value-add structured fields cannot carry.

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 purpose, date constraints and period/property choices are front-loaded, and nearly every sentence carries an actionable constraint (range limit, statistic matching, rate limits). It is dense and slightly run-on, and 'TerraMCP is a Wrench AI service' is the one throwaway clause, but overall the length is justified.

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 6-parameter read-only query with no output schema, the description covers the essentials an agent needs to call it correctly: valid ID space, statistic/property pairing, interval choice, date ordering and span limits, and even the rate-limit envelope. Nothing material 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?

Schema coverage is 100%, so the schema already documents all six parameters, setting a baseline of 3. The description nonetheless adds decision-relevant meaning the schema lacks — that rainfall pairs with 'total', levels with 'min/max', and that station_id is a Hydrology SUID rather than a flood ID — lifting it above baseline.

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 ('Get qualified EA Hydrology ... time series') and enumerates exactly which properties are served (flow, level, rainfall, groundwater), which cleanly separates it from UK siblings like nrfa_get_timeseries, sepa_series and rainfall_latest. An agent can identify the source family 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?

Gives real selection guidance: use a Hydrology station SUID, match property to a supported statistic (rainfall→total, levels→min/max), pick daily vs 15min, and keep ordered dates ≤366 days apart. It also implicitly routes away from flood tools by warning the ID is 'not a flood-monitoring station ID', but it never names an alternative tool explicitly.

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?

Beyond the annotations (readOnly/openWorld/idempotent=false/destructive=false), it discloses return content ('source data and provenance'), unit normalisation to SI, no-API-key access, concrete anonymous rate limits (60/hour, 300/day per IP and session), key fallback behaviour, and source licence warnings. That is rich operational context annotations cannot carry.

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?

Purpose and disambiguation are front-loaded, followed by return/quantitative details. The TerraMCP branding and quota sentences are denser boilerplate but still actionable for an agent; overall it is appropriately sized with little 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?

With no output schema, the description covers what comes back (source data + provenance), units, auth, rate limits and alternatives. Minor gaps remain around result ordering/pagination of the station list, but the tool is callable correctly from this text.

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 description coverage is 100%, so lat/lon, limit, radius_km (including the bounding-box note) and the parameter enum are already documented. The description only reinforces WGS84 lat/lon and the optional parameter filter, adding no new syntax or constraints, so the 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 specific verb+resource+scope: 'Find nearby EA river level, flow or rainfall stations and their measures to select a gauge.' It explicitly distinguishes itself from the sibling rainfall_stations ('use rainfall_stations for rainfall-only discovery'), so an agent can route correctly without opening 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?

Names the alternative (rainfall_stations) and the condition that selects it, plus the intent ('to select a gauge') and input requirement ('confirmed WGS84 lat/lon'). It stops short of a full when-not matrix, but the key disambiguation is present.

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 safety (readOnlyHint true, destructiveHint false, openWorldHint true), and the description adds genuinely new context: returned source data with provenance, SI normalisation of hydrological units, anonymous rate limits (60/hour, 300/day) with key fallback, and licence warnings. It stops short of describing response shape or how 'latest' ordering is determined, 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?

Front-loaded with purpose and routing before operational details, and most sentences carry real information. The 'TerraMCP is a Wrench AI service' line and the trailing licence boilerplate are mildly extraneous but defensible provenance.

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 compensates by stating what is returned (source data and provenance) and how values are normalised, plus auth and rate-limit constraints. An agent has everything needed to call this correctly against a 2-parameter, read-only 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 description coverage is 100%, so both parameters are already documented by the schema, and the description largely restates them ('latest_n is per measure'). It adds the useful provenance hint that station_id comes from flood_find_stations, but no new format or semantic detail. 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 specific verb and resource ('Get recent observations across an EA station's measures') and scopes it to inspecting current conditions. It is clearly separable from sibling readers such as rainfall_latest, nrw_readings and sepa_values by naming the EA station measure scope.

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 routes the agent: station_id must come from flood_find_stations, and rainfall-only queries should use rainfall_latest instead. It also sets a boundary on interpretation ('Observations are not forecasts or design levels'), covering when-not usage.

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, non-destructive, open-world), and the description adds genuinely new operational context: no API key or signup required, anonymous limits of 60 calls/hour and 300/day per IP and session, key-based higher limits, and the anonymous fallback after monthly quota. It also discloses data handling ('normalised to SI') and licence obligations, exactly the kind of behaviour an agent cannot infer from 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?

Well front-loaded: purpose, then filter semantics, then exclusions, then operational limits. Most sentences earn their place, but 'TerraMCP is a Wrench AI service' is pure branding and the quota sentence is longer than needed.

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 does state what comes back ('source data and provenance') and covers access, rate limits, and licence caveats for a zero-required-parameter list tool. The return shape (warning fields, severity levels returned) is only sketched, leaving a minor gap.

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 description coverage is 100%, so both parameters are already documented in the schema. The description restates the severity semantics ('1 most severe, 4 no longer in force; default 3 includes alerts') without adding syntax, format, or edge-case detail beyond the schema, so the 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 specific verb and resource ('List current EA flood warnings and alerts') plus the intent ('to check active warnings for an area'), so an agent immediately knows what the tool returns. It draws a conceptual boundary with 'Not a site-specific risk assessment', which implicitly separates it from flood_zone_at_point, but 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 clear use context (checking active warnings for an area) and a negative condition ('Not a site-specific risk assessment'), which steers the agent away from point-based flood-zone tools. It stops short of naming the alternative tool to use instead, so routing is inferred rather than stated.

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?

Beyond the annotations (readOnly, openWorld, non-idempotent, non-destructive), the description discloses substantial operational context: anonymous rate limits (60/hour, 300/day per IP and session), optional-key behaviour with anonymous fallback, no auth/signup requirement, defence-ignoring methodology, provenance/SI normalisation, and source licence warnings. This is exactly the extra context annotations cannot carry.

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?

Purpose, caveats, and limits are front-loaded and each policy sentence is informative. The line 'TerraMCP is a Wrench AI service' is filler, and the block is dense, but overall it stays on-topic without redundancy.

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 tool with no output schema and read-only annotations, the description covers semantics, methodology caveats, return contents, provenance, auth, and rate limits. Nothing an agent needs to invoke it correctly or set expectations 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?

Schema description coverage is 100% and both lat/lon are fully documented with type, units, and geographic bounds. The description adds only the implicit England scope, offering no additional parameter-level meaning. Baseline 3 is appropriate when the schema already does the heavy lifting.

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 (check EA Flood Map for Planning Flood Zones 2/3) and scopes it to an England point via polygon containment. This clearly separates it from siblings like flood_list_warnings (live warnings) and ea_flood_features (raw features), so an agent can route correctly without opening a 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 when-not guidance: it is not a live flood warning nor a site-specific flood risk assessment, and a no-match result is not a formal Zone 1 determination. The England-only scope is also stated. It does not, however, name the sibling tool an agent should use for those alternative cases, so the routing is implied rather than explicit.

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?

Goes well past the annotations by disclosing that results are Labelled Sponsored, that there is no automatic contact or lead transfer, that discovery requires no API key or signup, and by giving concrete anonymous rate limits (60/hour, 300/day per IP and session). These are exactly the auth, policy, and throttling facts an agent cannot get from readOnlyHint/idempotentHint alone.

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 purpose in the first sentence and keeps the operational facts tight and factual. 'TerraMCP is a Wrench AI service' is the one sentence that contributes little to tool selection, slightly diluting an otherwise economical description.

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 and no parameters, the description carries the informational burden and covers what is returned (contact URL, specialisms) plus the sponsored/no-lead-transfer behavior and access constraints. Complete enough for an agent to call it correctly, though it does not clarify whether one or many listings are returned.

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?

The tool takes zero parameters, so there is no parameter semantics to document; baseline is 4. The description correctly refrains from describing inputs that do not exist.

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 ('Return a sponsored consultancy listing') and names the payload fields (contact URL, specialisms), which is clear. It does not need heavy sibling differentiation because no other sibling deals with consultancy listings, but it never explicitly contrasts its scope against the surrounding environmental-data tools.

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?

'when seeking professional help' gives a light contextual cue for invocation, implying this is for discovery of commercial support rather than geospatial data. However, there is no explicit when-not guidance or named alternative, so usage is inferred rather than stated.

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 safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new behavior: unknown values resolve to null, placeholders flag coming-soon sources, no API key or signup is needed for discovery, and anonymous rate limits are 60/hour and 300/day per IP and session. That rate-limit and null-handling detail is exactly the context annotations cannot convey.

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 is front-loaded, but the description is a run-on mix of purpose, input syntax, null behavior, branding ('TerraMCP is a Wrench AI service'), and rate limits, with several terse fragments ('Unknown values are null. Placeholders explicitly show coming-soon status.'). It is information-dense but scattershot, and the branding sentence is borderline 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?

With no output schema, the description carries the return-value burden and does describe the payload (evidence, access requirements, router_tools) plus null/placeholder behavior. Combined with the disclosed auth-free discovery and rate limits, an agent has enough to invoke it correctly; only pagination/response shape is left implicit.

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 baseline is 3, but the description adds value beyond the schema: it documents that -api/-mcp/-server suffixes are optional and that unknown values are returned as null. This clarifies accepted input forms and failure behavior that the schema alone does not state.

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 ('Get full source evidence, access requirements and router_tools') and names the return payload. It also positions itself relative to the sibling search_sources, so an agent can distinguish the two. The only weakness is that 'source evidence' is somewhat abstract without domain knowledge.

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 frames the tool as 'the recommended starting point after search_sources' and tells the agent to feed it 'a returned slug', giving clear sequencing context. It stops short of stating when NOT to use it or naming alternatives beyond search_sources, so it is strong context rather than full when/when-not guidance.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new operational context: no API key or signup required, plus anonymous rate limits of 60/hour and 300/day per IP and session.

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 lead sentence is well front-loaded and the rate-limit sentence earns its place. However "TerraMCP is a Wrench AI service" is promotional filler that does not help an agent decide or invoke.

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 zero-parameter, no-output-schema discovery tool, the description covers purpose, usage context, auth posture and rate limits. Nothing critical is missing, though return fields beyond 'source counts' are only loosely described.

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?

The tool takes zero parameters, so the schema carries nothing to explain; baseline 4 applies. The description does hint at the payload shape by mentioning source counts, which is mildly useful.

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 (List) and resource (curated consultancy disciplines with source counts), and frames the tool as a pre-search discovery step. It does not name a sibling tool explicitly, so the differentiation from search_sources/top_sources is only implied.

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?

"browse categories before searching" gives a clear usage context, positioning this as the orientation step ahead of search. There are no exclusions or named alternatives (e.g. top_sources), so it stops short of full routing guidance.

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 readOnly/openWorld/non-idempotent/non-destructive, and the description adds substantial context beyond them: OGL v3 licence, attributes-only return with no determination, source data and provenance, SI normalisation of hydrological units, no-API-key access, concrete anonymous throttling (60/hour, 300/day per IP and session), key-based higher limits with anonymous fallback, and licence warnings.

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?

Purpose and scope are front-loaded in the first sentence, and the remaining sentences each carry operational value (licence, return shape, quotas). The 'TerraMCP is a Wrench AI service' branding sentence is the one low-value entry, but the whole remains compact and readable.

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 present, the description does the necessary work of saying results are attributes plus provenance and not a determination, and it covers access and quota constraints. It stops short of enumerating the returned attribute fields, but for this data-lookup tool it is complete enough to invoke correctly.

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 description coverage is 100%, so lat/lon/limit/radius_km are all already documented, and the description adds only the general notion of a bounding box around a point (already echoed in the schema). Baseline 3 is appropriate when the schema carries the parameter semantics.

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 (Find), a named resource (Natural England Sites of Special Scientific Interest), and the exact spatial scope (intersecting a bounded WGS84 box around an England point). This is clearly distinguishable from all the sibling data-source tools (bgs, ea, nrw, sepa, etc.) without opening any 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?

It conveys the operational context (open data, no signup, anonymous rate limits) and a caveat that results are not a planning or ecological determination, which implies intended use. However, it never states when to pick this tool over an alternative sibling such as planning_entities, nor any explicit exclusions or prerequisites for a query.

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, non-destructive, non-idempotent. The description adds substantial context beyond that: provenance returned, SI unit normalisation, no API key required, explicit rate limits (60/hour, 300/day per IP and session), quota fallback behaviour, and licence warnings.

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?

Purpose and data-format details are front-loaded in the first two sentences, with rate limits and provenance after. It is somewhat long and includes a low-value promotional sentence ('TerraMCP is a Wrench AI service'), but no sentence is severely wasteful.

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 usefully notes that source data and provenance are returned and units are normalised to SI. Rate limits, auth model, and date-range limits round it out; only the exact return shape remains unspecified, which is acceptable.

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 description coverage is 100%, so the schema already documents station_id, data_type enum, and the start/end date constraints. The description restates the same enum meanings and date window rather than adding syntax or edge-case detail, so 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 specific verb and resource: fetch NRFA daily flow or catchment rainfall observations for historical catchment analysis. It also disambiguates 'station_id' as a numeric NRFA gauge identifier, not an EA station ID, which separates it from sibling tools like ea_hydro_series.

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 clear invocation context (station_id, data_type codes, ordered YYYY-MM-DD dates within 366 days) and states open-data access with anonymous limits. It does not, however, say when to prefer this over nrfa_station_info or other series siblings, so 'when-not' guidance is missing.

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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description goes well beyond them with auth requirements ('no API key or signup required'), explicit rate limits (60/hour, 300/day per IP and session), anonymous fallback after quota, licence warnings, and unit normalisation to SI.

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?

Purpose and the sibling routing are front-loaded, and the operational details (limits, licensing, units) are genuine context rather than filler. It is slightly long, and the 'TerraMCP is a Wrench AI service' branding sentence contributes little to tool selection.

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 single-parameter read tool with no output schema, the definition supplies everything an agent needs: what is returned ('source data and provenance'), the unit convention, auth/quota behaviour, and the sibling to use for observations. No material gap remains.

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 parameter is fully documented in the schema. The description only restates that station_id is numeric, adding no format or edge-case detail beyond the schema's own 'not an EA station ID' note, so the 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?

Opens with a specific verb and resource ('Get NRFA gauging-station metadata, river, location and catchment area') and states the purpose (identify a historical flow record). It explicitly distinguishes itself from the sibling nrfa_get_timeseries, so an agent can route 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?

Names the alternative tool and the condition that selects it: 'use nrfa_get_timeseries for observations', implying this tool is for station metadata rather than time series. The required input ('Supply the numeric NRFA station_id') is stated up front.

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 readOnly/openWorld/non-destructive, and the description adds real behavioural context beyond them: anonymous rate limits (60/hour, 300/day per IP and session), no API key required, key fallback after quota, and licence warnings. It stops short of describing pagination or truncation behaviour when limit is applied.

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?

Purpose is front-loaded in the first sentence, followed by output-characteristics and access/limits information, which is well ordered. The 'TerraMCP is a Wrench AI service' line is pure filler that could be dropped, costing it a point.

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 does the right work by characterising the return ('source data and provenance', preserved units/quality codes, SI normalisation). Access terms, limits and licensing are covered, so an agent has what it needs; only pagination/truncation semantics for limit 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 both parameters (station_id, limit) are fully documented in the schema itself, establishing a baseline of 3. The description restates the station_id provenance idea already in the schema and adds nothing about how limit interacts with results, so no lift beyond baseline.

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 uses a specific verb+resource ('Get NRW telemetry measures and latest observations for a station_id') and names the required key, so the agent knows the shape of the call. It does not, however, differentiate itself from near-neighbours like nrw_readings or nrfa_get_timeseries, leaving some ambiguity about which sibling to pick.

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?

Usage is only implied: it takes a station_id from a station discovery tool, so the agent can infer it is a per-station data fetch. There is no explicit when-to-use/when-not guidance and no routing to or away from the many sibling reading/series tools (nrw_readings, ea_hydro_series, nrfa_get_timeseries), which is the main gap.

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 the read-only, open-world, non-destructive profile, yet the description still adds substantial behavior the annotations cannot convey: timestamps lacking an explicit timezone, preservation of source values and quality codes, SI normalisation of hydrological units, provenance returns, anonymous rate limits (60/hour, 300/day) with key-based fallback, and source licence warnings. That is genuinely useful context for an agent.

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?

Purpose and scope are front-loaded in the first sentence, followed by return-value, unit and rate-limit facts. The prose is dense and packs several operational facts into a single block, but every clause carries actionable information, so it is efficient rather than bloated.

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 must cover return values, and it does (source data, provenance, timestamps without timezone, quality codes, SI units). Combined with annotations covering the safety profile and the description covering rate limits and licensing, an agent has everything needed to call it correctly.

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 description coverage is 100%, so all four parameters are already documented, and the baseline is 3. The description reinforces the start/end 7-day ordering constraint and the timezone caveat on returned timestamps, but adds little syntax or format meaning beyond the schema itself.

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 first sentence states a specific verb (Get), resource (NRW telemetry readings), identifier (measure_id) and scope ceiling (at most 7 days), which is far beyond a tautology. It does not, however, explicitly differentiate itself from readings-style siblings such as flood_get_readings, tide_readings or sepa_values, so it stops short of a 5.

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?

Usage is only implied: requiring a measure_id suggests chaining from nrw_measures, and the 7-day cap constrains the request window, but no sentence tells the agent when to pick this tool over alternatives or when-not to use it. Adequate but with a clear gap.

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 substantial context beyond the annotations: data is provisional, open licence with warnings, no key needed, and concrete anonymous rate limits (60/hour, 300/day per IP and session) with key-based fallback. It does not describe result shape or what happens when a name matches multiple stations, but the operational constraints are well covered.

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 purpose is front-loaded and the nrw_measures linkage is well placed, but 'TerraMCP is a Wrench AI service' is pure filler and the licence/auth/rate-limit sentences are dense boilerplate that could be trimmed without losing agent-relevant information.

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 only two params and no output schema, the definition covers licensing, rate limits, provenance, and SI normalisation of hydrological units. The one gap is that it never tells the agent what a returned 'station reference' looks like or how to handle zero/many matches.

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 both `name` and `limit` are already documented in the schema. The description restates name-based searching but adds no syntax hints (partial matching, case sensitivity) or guidance on choosing `limit`, so it sits at the baseline.

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 ('Find Natural Resources Wales telemetry stations by station name') and links the output to the sibling consumer nrw_measures, which separates it from nrw_measures/nrw_readings. It does not explicitly distinguish itself from other provider station finders (sepa_stations, ea_groundwater_stations), but the provider scope is unambiguous.

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?

'Returns station references for nrw_measures' makes the sequence clear: this is the lookup step that feeds the measures tool. There is no explicit when-not or stated alternative for other station lookups, so it stops short of full routing guidance.

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, non-destructive, open-world behaviour, and the description adds real value beyond them: license (OGL v3), the names-vs-addresses distinction, returned provenance, and required credentials. It stops short of describing result shape or rate limits, so a 4 rather than 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?

Purpose and licence caveats are front-loaded in the first sentences, with auth/onboarding details trailing. Mostly earns its place, though the 'TerraMCP is a Wrench AI service' line and the odd 'hydrological units normalised to SI' clause add noise for this tool.

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 does describe what comes back (source data and provenance) and enumerates the credential prerequisites, which is what an agent needs before calling. The copy-pasted hydrological-unit note is irrelevant here but not harmful.

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 description coverage is 100%, so both parameters (query, limit) are already fully documented with bounds in the schema. The description's only added hint is the names-not-addresses caveat for the query, which is the baseline-3 situation.

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 (Search) and resource (OS Open Names in Great Britain), and clarifies the scope by noting these are names, not full postal addresses. It is distinguishable from the sibling hydrology/flood/station tools, though it never explicitly names an alternative.

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?

The description gives authentication context (vaulted OS Data Hub key, TerraMCP Bearer key) but no guidance on when to use this tool versus alternatives, nor any exclusion conditions. Usage must be inferred from the resource name alone.

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?

With annotations only covering the safety profile (readOnly, openWorld, non-idempotent, non-destructive), the description carries a lot of extra behavioral weight: licence terms checked and attribution retained, incomplete coverage caveat, provenance returned, SI normalisation of hydrological units, and concrete rate limits (60/hour, 300/day per IP and session) with anonymous fallback after quota. This is information an agent cannot get from the 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?

The core spatial purpose is front-loaded, which is good, but the paragraph is padded with material that does not help select or invoke the tool, notably 'TerraMCP is a Wrench AI service' and the closing source-licence remark. The quota and licence sentences do earn their place; the branding does not.

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 five-parameter read-only spatial lookup with no output schema, the description covers what an agent needs: what is searched, the spatial semantics, what is returned (source data and provenance), the normalisation applied, the incompleteness caveat, and the authentication/rate-limit regime.

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 description coverage is 100%, so the schema already documents lat, lon, limit, dataset and radius_km with bounds and enums. The description adds only the bounding-box vs radius framing, which the schema's radius_km description already states. 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?

The description names a specific verb and resource ('Find England planning dataset entities intersecting a bounded WGS84 box around a point') and enumerates the datasets covered, so an agent knows exactly what comes back. It does not explicitly distinguish itself from overlapping siblings such as flood_zone_at_point or ea_flood_features, which also serve flood data, so it stops short of a 5.

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?

Usage context is implied rather than stated: the agent learns this is open data needing no key, is rate limited, and is 'not a planning determination', but there is no explicit guidance on when to choose this tool over the sibling flood/designated-site tools. No alternatives or exclusion conditions are named.

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?

Beyond the readOnly/openWorld/destructive annotations, it discloses that source data and provenance are returned, that hydrological units are normalised to SI, that no API key is required, and specific anonymous rate limits (60/hour, 300/day per IP and session) with key fallback behaviour and licence warnings. This is exactly the extra operational context annotations cannot carry.

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?

Purpose, usage, and return/units information are front-loaded and efficient, and the rate-limit and licence notes are useful. The 'TerraMCP is a Wrench AI service' sentence is branding that does not help the agent and is the main bit of 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?

With no output schema, the description still states what is returned (source data and provenance) and covers auth, rate limits, and unit normalisation. It does not detail the shape of the returned readings, but for a simple 2-param read tool this is nearly 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?

Schema coverage is 100%, so the baseline is 3, but the description adds value by naming the exact sibling tool (rainfall_stations) that produces a valid station_id, which the schema only refers to generically as 'the corresponding provider's station discovery tool'. It adds marginal meaning on top of the schema.

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 (Get), resource (recent rainfall observations in mm), and scope (EA rainfall gauge), and it explicitly routes the agent to rainfall_stations for the station_id. An agent can distinguish this from rainfall_stations, nrw_readings, and tide_readings without opening any 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?

It gives the concrete prerequisite 'Use a station_id from rainfall_stations' and explains the latest_n default, which tells the agent how to drive the tool. It stops short of explicit when-not-to-use guidance or naming alternative reading tools for non-EA regions, so it is clear context without 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 cover read-only/open-world/idempotent status, but the description goes well beyond them: return content ('source data and provenance'), unit normalisation to SI, no API key requirement, explicit rate limits (60/hour, 300/day per IP and session), quota fallback behaviour, and licence warnings. That is substantive operational context an agent cannot get from 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?

Purpose and routing are front-loaded in the first two sentences, and the operational details are densely packed. The branding sentence ('TerraMCP is a Wrench AI service') is pure filler, which keeps it from a 5.

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, but the description states what is returned (source data and provenance) and covers auth, rate limits, quota fallback and licensing. For a 4-parameter spatial lookup this is complete enough to call correctly.

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 baseline is 3, but the description adds a meaningful qualifier the schema lacks: coordinates must be *confirmed* WGS84 values and the measurement parameter is fixed to rainfall (i.e. no parameter selection exists). It adds value without duplicating the schema verbatim.

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 ('Find nearby EA rainfall gauges and their measures') and scopes it ('rainfall-only monitoring'). It explicitly contrasts with the sibling flood_find_stations, so an agent can route without opening any 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?

It states when to use this tool ('rainfall-only monitoring') and when not to, naming the alternative ('Use flood_find_stations for river level, flow or mixed station discovery'). The precondition that coordinates must be confirmed WGS84 lat/lon is also given.

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, closed-world). The description adds genuinely new behavioral context: separate sponsored/organic arrays, pinned and flagged sponsored placements, coming-soon placeholders, and explicit rate limits (60/hour, 300/day) and no-API-key access. This is rich, though the rate-limit detail is operationally the most valuable and slightly buried at the end.

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 core purpose and enforcement points, and every clause carries operational information. However, the TerraMCP/Wrench AI branding sentence and some return-format detail add length without helping invocation decisions.

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 carries the return-shape burden well: describes paginated summaries, default/max page sizes, separate sponsored and organic arrays with pagination, and pinned/placeholder behavior. Combined with the 12-param schema, an agent has what it needs to call this correctly.

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 description coverage is 100%, so all 12 parameters are already documented. The description restates the query/use_case/audience substring matching and location_hints behavior, which mostly duplicates the schema rather than adding new syntax or semantics. 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 specific verb (Find) and resource (curated source summaries) plus the discovery scope, and positions itself as 'the recommended starting point' versus get_source. An agent can distinguish this from top_sources and get_source without opening 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?

Explicitly routes: use this for discovery, then 'use get_source for full evidence and enrichment'. Also covers the edge case that unmatched queries return suggestions, so the agent knows not to treat zero hits as failure.

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?

Going well beyond the annotations, the description discloses anonymous rate limits (60/hour, 300/day per IP and session), that no API key is needed, quota fallback behaviour, SI normalisation of hydrological units, provenance/licence warnings, and that source data is returned. These are exactly the operational facts an agent needs and none of them are in the structured fields.

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 purpose and return contents are front-loaded in the first two sentences, with rate-limit and licensing details following usefully. One sentence, "TerraMCP is a Wrench AI service", is pure branding filler that does nothing for tool selection.

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 carries the burden for return values and does so adequately (series IDs, units, source data, provenance). Auth and rate-limit context is thorough; only pagination/limit interaction is left entirely to the schema.

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 description coverage is 100%, so baseline is 3. The description restates "station_id (station number)", which matches the schema's SEPA station_no semantics, but adds no new meaning and says nothing about the limit parameter beyond what the schema already documents.

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 states a specific verb and resource: "List bounded SEPA KiWIS time series for a station_id", and clarifies what is returned (series IDs, reported units/OGL). It is clearly distinguishable from sepa_values (readings) and sepa_stations (station discovery) by the word "series", though it never names those siblings 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?

Usage is only implied: the tool is the middle step of the stations -> series -> values pipeline, and the description hints at discovery by promising series IDs and units. However, it never says when to prefer sepa_series over sepa_values, nor that station_id must first come from sepa_stations (that constraint lives only in the schema).

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?

Beyond the annotations (readOnly/openWorld/non-destructive), the description discloses rate limits (60/hour, 300/day per IP and session), that no API key or signup is needed, that keys raise limits with anonymous fallback after quota, that source licence warnings apply, and that results carry provenance with SI normalisation. This is substantial operational context the structured fields do not carry.

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 purpose and the calling rule, then operational details; most sentences earn their place. The brand line ("TerraMCP is a Wrench AI service") is filler that dilutes an otherwise tight paragraph.

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 does cover the return shape at a high level (source data, provenance, SI normalisation) plus licensing and rate limits. It could be slightly more specific about what a result record contains, but it is adequate for a 5-parameter read-only search tool with full schema coverage.

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 baseline is 3, but the description adds a real constraint the schema does not encode: although no parameter is marked required, the agent must supply either a name or both coordinates. It restates the 50 km radius cap, which is already in the schema, so it does not rise to 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 (Find), resource (SEPA monitoring stations), geography (Scotland), and the two lookup modes (name or WGS84 lat/lon). This cleanly separates it from siblings like sepa_series and sepa_values, which deal in readings rather than station discovery.

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?

"Supply a name or both coordinates; radius maximum 50 km" is an explicit calling rule that tells the agent the two valid invocation shapes. It does not, however, tell the agent when to prefer this over other station tools such as rainfall_stations or ea_groundwater_stations, so tool-selection guidance is absent.

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?

Goes well beyond the readOnly/destructive/idempotent/openWorld annotations by disclosing that values are provisional and may change, that data is OGL-licensed, that units are retained (hydrological units normalised to SI), and concrete rate limits (60/hour, 300/day, anonymous fallback after monthly quota). Auth requirements (no API key needed) are also stated.

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 critical constraints (cap, window) are front-loaded, but the passage is long and includes filler such as 'TerraMCP is a Wrench AI service', which does not help an agent call the tool. Rate-limit and licence details earn their place; the branding sentence does not.

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 carries the burden of describing returns, and it partially does so ('Returns source data and provenance', 'values retain upstream units and timestamps'). Combined with the licence, volatility, and rate-limit notes, an agent has enough to call it correctly, though the exact response shape remains vague.

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 description coverage is 100%, so the schema already documents series_id, start, end, and limit. The description's 'up to 1,000' and 'at most 7 days' merely restate schema constraints, adding no new syntactic or format detail beyond the schema.

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 (Get), resource (SEPA KiWIS observations), and scope (up to 1,000 values by series_id over at most 7 days). The 'by series_id' framing implicitly separates it from sepa_series (identifiers) and sepa_stations, so an agent can distinguish it from siblings.

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?

The 7-day window and series_id requirement imply the use case (fetch observations for a known series over a short window), and the schema points to sepa_series as the source of IDs. However, there is no explicit when-to-use/when-not guidance and no alternative named in the description text itself.

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 carry the safety profile (readOnly, non-destructive, openWorld), and the description adds materially more: anonymous rate limits (60/hour, 300/day per IP and session), keyed higher limits with fallback after monthly quota, open-data/no-signup status, licence warnings, SI normalisation, and retention of datum qualifier and original unit.

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?

Purpose, unit/datum behaviour, and the predictions exclusion are front-loaded before the operational boilerplate. Most sentences earn their place (rate limits, licence), though 'TerraMCP is a Wrench AI service' adds little for tool selection.

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, so the description must cover returns, and it does: source data plus provenance, SI normalisation, retained datum qualifier and original unit. Combined with quota/auth context, 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%, so both parameters (station_id, latest_n) are already documented with patterns, bounds, and defaults. The description adds only output-oriented context (SI metres, datum/unit retention) and no extra parameter semantics, so the 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 specific verb and resource ('Get latest observed tidal levels for an EA station') and explicitly scopes it as observations, not predictions ('Not tide predictions'), which separates it from prediction-style siblings and complements the discovery tool tide_stations named in 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?

Gives clear context ('to inspect coastal water levels') and an explicit exclusion (not tide predictions), and the schema points to the provider's station discovery tool for the required station_id. It doesn't name the discovery sibling (tide_stations) directly in the description, so the routing is strong but not fully explicit.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description goes well beyond them: no API key required, anonymous rate limits (60/hour, 300/day), key-based higher limits with anonymous fallback, SI normalisation, and licence warnings. That is rich operational context an agent needs before calling.

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 the key distinction are front-loaded in the first two sentences, followed by genuinely useful operational facts. The 'TerraMCP is a Wrench AI service' branding sentence earns its place least but is brief; overall the text is tight for the amount of value it carries.

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 steps in to say it returns source data and provenance, and it covers units, auth, rate limits and licensing. It is close to complete for a read-only spatial lookup, though the shape of returned station records could be sketched a little more.

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 description coverage is 100% and all four parameters (lat, lon, limit, radius_km) are already documented with ranges and defaults in the schema. The description adds no parameter-level syntax or format detail beyond the schema, so the 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?

The opening clause gives a precise verb+resource+scope: 'Find EA tidal level stations near a point.' The clarification 'Observed levels, not tide predictions' distinguishes it from a prediction-style sibling, so an agent can separate it from tide_readings 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?

The 'observed levels, not tide predictions' note and the 'qualifier=Tidal Level' hint imply when this tool is appropriate, and 'near a point' implies a spatial lookup. However, it never names tide_readings as the alternative for actual readings or states explicit when-not-to-use conditions, leaving the routing to inference.

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 read-only/idempotent/non-destructive profile, and the description adds real value on top: the limit scoping to organic results only, the guaranteed marking of sponsored placements, and concrete anonymous rate limits (60/hour, 300/day per IP and session). The 'no API key or signup' note also clarifies auth. Only the return shape is left unspecified.

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?

Purpose and the limit caveat are front-loaded well, but 'TerraMCP is a Wrench AI service' is service branding that does not help an agent select or invoke the tool and dilutes an otherwise tight definition. Rate-limit and auth notes do earn their place.

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 tool with annotations carrying the safety profile and no output schema, the description supplies the operational context an agent needs: rate limits, no-signup access, and the organic/sponsored distinction. Nothing critical is missing, though return format and pagination are not addressed.

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 both parameters are fully documented in the schema (limit default/max and category slug). The description's 'limit applies only to organic results' largely restates the schema's 'maximum organic sources to return,' adding only marginal clarity. 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?

Specific verb and resource: 'Return highest evidence-quality organic sources and separate sponsored placements.' The scope ('browse a category') and the organic/sponsored split make it distinguishable from search_sources, though it never explicitly names that sibling. Clear but not fully differentiated.

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?

'to browse a category' implies the use case (category-based discovery rather than keyword search), but there is no explicit when-to-use vs search_sources or list_categories, and no exclusions. Usage is left to inference.

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 and world-open behaviour, so the bar is lower; the description still adds real value with anonymous rate limits (60/hour, 300/day per IP and session), keyed fallback, no-signup, SI normalisation and licence warnings — behaviour genuinely not captured in annotations. Docked one point for the 'TerraMCP is a Wrench AI service' marketing filler, which is not behavioural context.

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?

Purpose and constraints are front-loaded, which is good, but the tail drifts into vendor boilerplate and licensing legalese. The rate-limit sentence earns its place; the 'TerraMCP is a Wrench AI service' clause does not.

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, and the description compensates by noting it returns source data and provenance (with SI normalisation). With annotations covering safety and the schema covering all four parameters, an agent has what it needs to call this correctly; only the return shape remains loosely specified.

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 description coverage is 100%, so the baseline is 3. The description restates the parameter codes and the 'optional USGS- prefix' that the schema already documents, adding the 366-day pair constraint but nothing the schema lacks.

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 ('Get') plus resource and scope ('USGS daily mean discharge, stage or water temperature for historical US monitoring analysis'), and the USGS source cleanly separates it from the NRFA/SEPA/EA/NRW siblings that also serve hydrology series.

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 context ('historical US monitoring analysis') and the parameter code mapping, which implies when to reach for it, but never states when-not to use it or names an alternative tool. Usage is implied rather than prescribed.

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?

With annotations covering only the safety profile (readOnly, non-destructive, open-world), the description contributes substantial extra behavior: unit preservation and detection-limit qualifiers are retained, hydrological units are normalised to SI, provenance is returned, no API key is needed, and explicit anonymous rate limits (60/hour, 300/day) with key-based fallback are disclosed. That is well beyond what the structured fields convey.

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 behavioural facts are front-loaded before the service branding, rate limits and licence boilerplate. Slightly bulky with the TerraMCP/OGL/licence sentences, but each of those carries operational information an agent can act on.

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 explains what comes back (source data plus provenance, preserved units, qualifiers, SI normalisation). Combined with the full parameter documentation and disclosed auth/rate limits, an agent has everything needed to call it correctly.

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 description coverage is 100% and each parameter (start, end, limit, determinand, sampling_point) is fully documented in the schema, so the 3 baseline applies. The description restates the parameter roles in prose but adds no format, constraint or defaulting detail that the schema does not already carry.

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 (Get), a specific resource (EA water-quality observations) and its scoping inputs (sampling_point, dates, determinand code). It is clearly distinguishable from siblings like wq_sampling_points, nrfa_get_timeseries and nrw_readings by naming the EA source and the bounded observation scope.

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?

Usage is implied through the scoping inputs and the referenced sampling_point notation, and the 'bounded' framing hints at date-range constraints. However, the description never says when to prefer this over sibling series tools (ea_hydro_series, nrw_readings, sepa_values) or how to obtain the sampling_point identifier, so the routing guidance is only implicit.

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/openWorld/destructive/idempotent, and the description adds real value beyond them: anonymous rate limits (60/hr, 300/day), no-key/no-signup auth, SI normalisation, provenance, and OGL licence warnings. It stops short of describing return structure or pagination, keeping it out of the 5 range.

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?

Purpose and the safety caveat are front-loaded well, but the definition pads with 'TerraMCP is a Wrench AI service' and repeats licence/quota language. The useful content (scope, limits, SI) is buried among marketing 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 4-param, no-output-schema query tool with annotations, this covers scope, auth, rate limits, and licence adequately. The only gap is that the actual shape of the 'bounded metadata' returned is not hinted at, though no output schema exists to describe it.

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 each parameter (lat, lon, limit, radius_km) is documented with bounds and defaults in the schema. The description adds nothing about parameter syntax or units beyond the schema, so 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 specific verb (Find), resource (Environment Agency water-quality sampling points), and scope (near a WGS84 point, England). Combined with the explicit 'not a water-safety assessment' note, an agent can distinguish it from siblings like wq_measurements and ea_groundwater_stations.

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 useful context ('near a WGS84 point', returns metadata not an assessment), but never names an alternative or states when-not to use it. The sibling wq_measurements is the obvious complement and goes unmentioned, so routing is left to inference.

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