TerraMCP

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

Beyond the annotations (which already declare readOnly, openWorld, non-idempotent, non-destructive), the description adds genuinely useful operational context: it is an authenticated router requiring the caller's own OpenTopography key, and commercial use needs an Enterprise key. It also discloses the return shape (normalised SI units plus source provenance). It stops short of describing coverage/rate limits or what happens on key failure, but this is solid added value.

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?

Two sentences with no padding, and the auth/licensing constraint is placed after the return statement. Slight waste in the leading 'TerraMCP authenticated router: dem_clip' fragment, which repeats the tool name instead of spending those words on purpose.

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 partially cover returns, but for a geospatial clip tool with 0% schema coverage it omits the bbox convention, dataset selection rationale, output format/resolution/nodata handling, and coverage limits. An agent cannot call this confidently from the description alone.

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 0%, so the description carries the full burden for two parameters and adds nothing: the four-element bbox ordering (presumably minLon/minLat/maxLon/maxLat), its coordinate order, and the meaning/tradeoffs of the six dataset enum values (COP30, COP90, SRTMGL1, etc.) are all unexplained. Only a vague hint that output is 'normalised SI' indirectly touches on units.

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 'TerraMCP authenticated router: dem_clip' largely restates the tool name rather than stating what it does; an agent must infer 'clip' means extracting DEM elevation data for a bounding box. The second sentence clarifies the return ('normalised SI data and source provenance'), which signals an elevation-data retrieval tool, but the specific verb+resource+scope is never stated outright and no sibling is distinguished.

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 no when-to-use guidance, no guidance on choosing this over siblings like usgs_daily or ea_hydro_series, and no indication of when to pick which dataset. The only usage-adjacent content is the key requirement ('BYO OpenTopography key only'), which is a prerequisite, not a routing rule.

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, destructive=false, openWorld, and non-idempotent. The description adds two useful facts beyond them: authentication is required and results are returned as normalised SI values with source provenance. It does not explain the non-idempotency, rate limits, or pagination.

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?

Only two sentences, but the first is tautological filler that repeats the tool name, and the informative content is thin. It is short due to under-specification rather than genuine conciseness.

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, 0% parameter coverage, four required fields, three enums, and a rich sibling set, the description leaves an agent without the information needed to select or correctly invoke the 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?

Six parameters at 0% schema description coverage and the description names none of them. It says nothing about station_id, property, start/end formats, period granularity, or the statistic enum, so it fails to compensate for the total coverage gap.

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 largely restates the tool name ("TerraMCP authenticated router: ea_hydro_series") and adds only "Returns normalised SI data and source provenance." It never states the actual resource, namely hydrological time series for Environment Agency stations, so an agent cannot distinguish it from siblings like nrfa_get_timeseries or usgs_daily.

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?

There is no when-to-use guidance and no mention of alternatives, despite several overlapping time-series siblings (nrfa_get_timeseries, usgs_daily, flood_get_readings). The only context is "authenticated," which is not usage routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds two pieces of context beyond the annotations: that calls require authentication ('authenticated router') and that results carry normalised SI units plus source provenance. It does not explain the unusual idempotentHint=false for what appears to be a read, nor any rate limits or result caps.

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?

Two short sentences with no filler, which is good, but the opening clause 'TerraMCP authenticated router: flood_find_stations' merely restates the tool name and title rather than front-loading the actual function. The routing hint is placed after the boilerplate instead of first.

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 is the only place return values could be explained, and 'normalised SI data and source provenance' is too vague for a spatial station search (no mention of station list, distances, or metadata fields). Combined with 0% parameter coverage and no guidance on units or pagination via limit, it leaves meaningful gaps for a 5-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 0% across five parameters, so the description must carry the burden, and it largely does not. It clarifies only the 'parameter' enum (rainfall) and leaves lat, lon, radius_km, and limit entirely unexplained — an agent must infer that radius_km is the search radius and limit caps results.

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 name plus 'flood_find_stations' implies a station lookup, and the description adds that it returns normalised SI data and source provenance, plus a rainfall-specific hint. However it never states the core operation (find flood monitoring stations near a lat/lon within a radius), and the 'authenticated router' framing is boilerplate rather than purpose. Sibling tools like rainfall_stations and nrfa_station_info are named only in passing.

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 one conditional routing rule: 'Set parameter=rainfall to find rainfall stations, or use rainfall_stations', which is genuinely useful alternative-pointing. But there is no guidance on when to choose this over flood_get_readings, nrfa_station_info, or ea_hydro_series, and no mention of required lat/lon proximity context.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that output is normalised to SI units with source provenance and covers all station measures, plus an 'authenticated' hint, but it omits pagination/rate-limit behaviour and gives no hint about what idempotentHint=false means for repeated calls.

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?

Three short sentences with the routing rule placed last, so the core capability is front-loaded. The only waste is the name-restating 'TerraMCP authenticated router: flood_get_readings' prefix.

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 partially cover return content (normalised SI data, source provenance), which helps. However, for a 2-parameter tool with zero schema description coverage it says nothing about the inputs, leaving an agent to infer required station_id format and latest_n semantics from the raw schema alone.

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 0% and the description never mentions either parameter. station_id (required) and latest_n (count, default 1, max 100) are left entirely to the raw schema, so the description does not compensate for the documentation gap.

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 ('Returns normalised SI data and source provenance') and clarifies scope ('Returns all station measures'), which separates it from the rainfall-only sibling. The leading 'TerraMCP authenticated router: flood_get_readings' is boilerplate that adds no distinguishing information, but the substantive sentence is clear.

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 names an alternative and the condition that selects it: 'use rainfall_latest for rainfall only', implying this tool is for the broader/all-measure case. It gives no exclusions beyond that single routing rule and no prerequisites (e.g., how to obtain a valid station_id).

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds that the call requires authentication and that output is normalised to SI units with source provenance, but says nothing about pagination, rate limits, or result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is short with no padding, and the identifying clause is front-loaded. However, the opening phrase "TerraMCP authenticated router: flood_list_warnings" redundantly restates the name rather than adding 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?

For a two-parameter filtering tool (county, max_severity) with no output schema and no parameter descriptions, the definition should explain the filtering semantics and warning severity scale. Instead it leaves both parameters and the practical behaviour ambiguous.

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 0% and the description mentions neither parameter. The county filter and the max_severity integer (range 1-4, default 3) are completely undocumented anywhere, so the agent cannot know their intended 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?

The description mostly restates the tool name ("flood_list_warnings") and adds generic boilerplate about returning "normalised SI data and source provenance." It never states what a warning entry is or how this differs from siblings like flood_find_stations or flood_get_readings. Only the name itself conveys the actual purpose.

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?

There is no when-to-use guidance, no prerequisite conditions, and no routing to alternatives such as flood_get_readings or flood_find_stations. The agent must infer usage purely from the tool name.

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, idempotent, closed-world). The description adds genuinely new context not in the annotations: the listing is advertising content explicitly labelled 'Sponsored', and no lead transfer or contact occurs as a side effect.

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?

One sentence, front-loaded with the action and resource, with payload fields and the two key caveats appended. Dense but no filler; a semicolon split for the caveat improves scanability slightly.

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 parameters, no output schema and full annotation coverage, the description supplies what an agent needs: what comes back, that it is sponsored content, and that no contact side effect occurs. It stops short of explaining selection behaviour when multiple listings exist.

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 baseline is 4. The description correctly implies a single-record retrieval with no inputs to specify, and adds no misleading parameter-like language.

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 (Return) and resource (sponsored consultancy listing) and enumerates the returned payload: contact URL, specialisms, CTA. It does not differentiate from siblings, but the siblings listed are all environmental/flood data tools in an unrelated domain, so no confusion is plausible.

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?

There is no statement of when to call this tool, no prerequisites, and no named alternative. The clause 'no automatic contact or lead transfer' is a behavioral boundary, not usage guidance, so an agent gets no routing help.

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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail with no output schema present: unknown values return null and placeholders indicate coming-soon status, which tells the agent how to interpret sparse results rather than misread them as errors or missing data.

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?

Three short sentences, front-loaded with the core action and followed by two clauses that each carry distinct information (null semantics, placeholder semantics). Nothing is repeated from the name, title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full annotation coverage and no output schema, the description adequately covers what is returned and how ambiguous values are represented. Minor gaps remain around invalid-slug behavior and the expected source of the slug, but nothing essential to invoking it correctly 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 0% and the single parameter carries only minLength/maxLength constraints. The description says 'by slug', identifying the lookup key's role and tying it to the identifier produced by the search tools, but adds no format, case-sensitivity or length guidance, so it only partially compensates for the coverage gap.

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 a source by slug') and enumerates the payload ('provenance, score breakdown and access requirements'), so the agent knows this is a detail lookup rather than a list. It does not explicitly name search_sources or top_sources as the alternatives, leaving the distinction to inference from 'by slug'.

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 phrase 'by slug' signals that the agent must already hold a slug, which typically comes from search_sources or top_sources, but no when-to-use or when-not-to-use condition is stated. No prerequisites, error handling for an unknown slug, or sibling routing is 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds the useful detail that results pair disciplines with source counts, but says nothing about ordering, count semantics, or whether counts are totals or per-something.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler or redundancy. Nothing in it needs to be cut.

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 no-param read-only listing tool with annotations covering safety and no output schema, the description is minimally adequate. It never explains what a 'curated consultancy discipline' is in relation to the other source/consultant tools, leaving an agent unsure how to route between them.

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 baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is reported at 100% with an empty properties object.

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 and source counts'), so the agent knows it returns category names plus counts. It does not, however, distinguish itself from related siblings like search_sources or top_sources, which also surface source-oriented data.

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?

There is no guidance on when to call this versus search_sources, top_sources, or get_consultant. The agent must infer that this is an enumeration/discovery entry point rather than a search or lookup.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds two useful behavioural facts: calls require authentication, and results are normalised to SI with source provenance attached. It says nothing about pagination, rate limits, or missing-data behaviour, so it is adequate but not rich.

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 text is very short and front-loaded, so it is not bloated, but the first clause ('TerraMCP authenticated router: nrfa_get_timeseries') is pure filler that repeats the name. Space saved is wasted on restatement rather than on the missing parameter and usage detail.

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 tool with four parameters, three of them required, an enum input, and no output schema, the description is far too thin. Only the return format (normalised SI plus provenance) is addressed; nothing about station/date semantics or the data_type choices is covered.

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 0% and the description explains none of the four parameters. The required station_id, start, and end, and especially the data_type enum (gdf/ndf/cdr), are completely undocumented — an agent has no way to know which data type is appropriate without external knowledge.

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 largely restates the tool name ('nrfa_get_timeseries') and adds only that it returns 'normalised SI data and source provenance'. It never states the actual action in domain terms — retrieving a hydrological time series for a given NRFA station across a date range — so an agent cannot confidently distinguish it from siblings like ea_hydro_series, usgs_daily, or flood_get_readings.

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?

There is no when-to-use guidance, no statement of when another series tool is preferable, and no prerequisites beyond the word 'authenticated'. With 15 sibling tools covering overlapping hydrology/rainfall data, this omission forces the agent to guess.

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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered structurally. The description's one useful addition is the "authenticated" cue implying credentials are required, but it says nothing about response shape, units, or failure modes for a non-idempotent, open-world call.

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?

It is short, but half of it is wasted restating the tool name in router boilerplate, and the remaining clause is vague. Brevity here reflects under-specification rather than disciplined concision.

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, no parameter documentation, and a one-line description, the definition is too thin for a tool with a required identifier. It should at minimum name the resource returned and clarify how station_id is sourced.

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?

There is a single required parameter, station_id, with 0% schema description coverage, and the description never mentions it. The agent gets no hint about accepted identifier forms (e.g., NRFA gauging-station number) or constraints beyond the integer/positive type.

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?

"TerraMCP authenticated router: nrfa_station_info" merely restates the tool name, and the only functional claim is "Returns normalised SI data and source provenance." It never says it returns National River Flow Archive station metadata, and it gives no basis for choosing this over nrfa_get_timeseries or the flood/rainfall station 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?

There is no when-to-use, no when-not-to-use, and no mention of any alternative. With siblings like nrfa_get_timeseries and flood_find_stations sharing the NFRA/station domain, the agent is given nothing to route by.

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 readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description adds useful non-annotation context: output is normalised to SI (mm) with source provenance, and 'latest ... only' implicitly explains why idempotentHint=false (results shift over time). It still says nothing about authentication mechanics beyond the label 'authenticated router', rate limits, or what an empty result means.

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?

Three short sentences with the resource and units front-loaded before the parameter nuance. The opening 'TerraMCP authenticated router: rainfall_latest' is largely a restatement of the tool name and could be trimmed, but overall the text is tight and earns most of its space.

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 helpfully states what comes back (normalised SI values in mm plus source provenance), which covers the main return-value question. It is still thin for a tool in a dense station/reading family: no mention of how to obtain a valid station_id, whether missing data is returned, or result ordering.

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 0%, so the description must carry the load. It does clarify that station_id refers to an 'EA flood-monitoring station' and that latest_n is readings 'per measure' with a default of 1, which is real added meaning. It omits the identifier's accepted form/pattern and any guidance on sensible latest_n values up to the 100 cap.

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 ('Returns ... Latest rainfall readings ... in mm, for an EA flood-monitoring station') and adds scope ('latest only', normalised SI, provenance). It is clear what the tool does, but it never names or contrasts with the closest siblings (flood_get_readings, ea_hydro_series, rainfall_stations), so differentiation is left to inference.

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?

'Latest rainfall readings only, in mm, for an EA flood-monitoring station' implies this is the point-reading companion to a time-series tool, and 'latest_n defaults to 1' hints at bounded retrieval. However, there is no explicit when-to-use rule, no exclusion, and no pointer to the sibling that retrieves historical series or the one that resolves a station_id.

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 declare readOnly, openWorld, non-destructive, non-idempotent. The description adds that it is an authenticated router and returns normalised SI data plus source provenance, which is useful auth and return context. It does not contradict annotations and adds value beyond them.

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?

Three short sentences, front-loaded with router/auth and return info before the purpose. No wasted words, though the first sentence partly restates the tool name. Efficient overall.

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?

Given a 4-parameter spatial tool with no output schema, the description covers purpose, auth, and return nature but omits parameter semantics, pagination, and sibling alternatives. It is partially complete but leaves gaps an agent must resolve from 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 coverage is 0% for all 4 parameters; the description only says 'nearby' and parameter=rainfall, adding no meaning for lat, lon, limit, or radius_km. Parameter names and schema constraints help, but the description fails to compensate for the undocumented parameters.

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 ('EA rainfall stations'), with scope 'nearby' and parameter=rainfall. It implicitly distinguishes from rainfall_latest and flood_find_stations but does not name siblings explicitly. Clear enough for selection.

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?

Provides no explicit when-to-use or when-not-to-use guidance, nor alternatives among siblings like rainfall_latest or flood_find_stations. 'Find nearby' implies a spatial lookup but leaves the agent to infer context. No prerequisites stated beyond authentication in the prefix.

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, so safety is covered; the description adds genuinely useful behavior: separate sponsored and organic arrays, organic-only pagination, pinned and flagged sponsored placements, and possible coming-soon placeholders. That sponsored-vs-organic split and the placeholder caveat are real disclosure beyond structured fields, though scoring/filtering behavior (min_score) is left unexplained.

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?

Dense and front-loaded: purpose first, then pagination defaults, then the alternative tool, then result-structure caveats. Every sentence carries information, though the run of clauses about sponsored/organic arrays makes the tail slightly hard to parse in one pass.

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 accepts the burden of describing the return shape and does so (paginated summaries, sponsored/organic arrays, separate pagination, placeholder flags), which is strong for a 9-parameter search tool. Gaps remain around the enum kind values and min_score, so it is not fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully explains that query also matches use cases and audience, that use_case/audience filters do case-insensitive substring matching, and that region includes global sources, but it is silent on kind, category, min_score, and offset 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 (Search) plus the resource and domain scope (curated water, environment, terrain and civil engineering sources), and explicitly distinguishes itself from get_source, which serves the full-record need. An agent can route between search_sources and get_source 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 (get_source for full evidence and enrichment) and states the default/maximum page size, giving clear context for when to search summaries versus fetch detail. It does not state explicit when-not-to-use conditions or how it relates to sibling listing tools like top_sources or list_categories.

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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by disclosing that sponsored placeholders are returned separately and remain explicitly marked, and that the limit affects only organic results.

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 description is two tight sentences, front-loaded with the return behavior and then the important limit-scoping detail. Every sentence adds value and there is no 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 simple read-only tool with annotations and no output schema, the description covers the sponsored/organic split adequately. However, it omits the category parameter entirely and does not define what 'evidence-quality' means, leaving meaningful gaps.

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 0%, so the description must compensate. It explains the limit's scoping but says nothing about the category parameter, its meaning, valid values, or filtering behavior.

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 clear verb and resource: it returns separate sponsored placements and highest evidence-quality organic sources. It conveys the output composition well, but it does not distinguish this tool from siblings such as search_sources or get_source.

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?

There is no explicit guidance on when to use this tool versus search_sources or get_source. The only usage-adjacent statement is that the limit applies only to organic results, which is behavioral rather than selection 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 cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false). The description adds almost nothing beyond what annotations provide — 'authenticated router' is a vague claim that doesn't specify auth mechanism or requirements. No mention of rate limits, data freshness, unit specifics, or provenance format despite claiming to return both.

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 description is very short but not in a good way — it is under-specified rather than concise, with trailing whitespace and no front-loaded functional explanation. Every word present does little work.

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?

A read-only hydrology data tool with 4 params, 0% schema coverage, no output schema, and no annotations that explain data semantics. The description provides nothing about what data is returned, units, site_id format, date semantics, or the meaning of the parameter_code enum. Completely inadequate.

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 0% across 4 parameters, so the description must fully compensate. Instead it says nothing about site_id format, the date range semantics for start/end, or what the parameter_code enum values (00060, 00065, 00010) mean. The description completely fails its parameter-documentation burden.

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 only identifies the router and tool name ('usgs_daily') without stating what the tool does in functional terms. It mentions 'Returns normalised SI data and source provenance', which hints at a data retrieval purpose, but 'usgs_daily' is opaque and the description never explains that it fetches daily USGS hydrological time-series data. It does contextually distinguish from siblings like nrfa_get_timeseries or ea_hydro_series via the USGS provenance, but barely.

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?

No usage guidance whatsoever. The description does not say when to use this tool versus siblings like nrfa_get_timeseries, ea_hydro_series, or rainfall_latest. No prerequisites, no exclusions, no routing logic beyond the opaque tool name.

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