nws-weather-usgs-water-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.7.2
Disambiguation4/5
Most tools have distinct purposes, e.g., get_current_flow vs get_water_level vs get_water_temperature target different parameters. However, get_flow_anomaly and get_flow_anomalies are similar, and get_observations, get_latest_values, and get_field_data could cause confusion despite detailed descriptions.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern (clear, find, get, lookup, search). The most common verb is 'get', and the naming is predictable and uniform throughout.
Tool Count4/5
At 29 tools, the count is slightly high but reasonable for a combined NWS and USGS domain. Each tool covers a specific operation, though some like get_sun_times feel peripheral.
Completeness4/5
The server covers core NWS forecasts/alerts and USGS water data well, including current conditions, historical stats, anomalies, and searches. Minor gaps exist, such as lack of radar/satellite tools, but they are outside the stated domain.
Average 3.6/5 across 29 of 29 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 15 commits in the last 12 weeks
- Last stable release on July 15, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Creative Commons Zero v1.0 Universal.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, read-only, idempotent operation. The description adds that it returns 'historic summary statistics,' implying aggregation, but does not clarify what statistics are computed (e.g., mean, median) or how pagination via max_rows works.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but omits vital detail. It is front-loaded with the core purpose but lacks necessary precision for a tool with 9 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not explain what statistical metrics are returned or how the 'kind' parameter alters the query. The tool has 9 parameters and two required fields; the one-sentence description is insufficient for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and no parameter information in the tool description, the agent must rely solely on parameter names. Critical parameters like 'kind' (enum of period_of_record or date_range) and 'computation_type' remain unexplained, making it difficult to construct correct inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'historical summary statistics' for specific locations, which distinguishes it from sibling tools that retrieve raw observations or current values. However, it does not mention the 'kind' parameter (period_of_record vs date_range) which is essential for understanding the two modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_observations or get_latest_values. The description does not specify use cases, prerequisites, or exclude scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read behavior. The description adds context that the tool returns metadata (parameters, units, IDs) rather than actual data values, which is useful beyond annotations. However, it does not disclose pagination, rate limits, or response size behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficiently worded sentence that covers the core functionality without waste. It could benefit from a slightly more structured breakdown of what is returned (e.g., parameters vs. availability), but it is admirably concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters and no parameter descriptions, the tool description is incomplete. It does not explain how parameters filter results, what the output structure looks like (though output schema exists), or any usage constraints. The single sentence is insufficient for a complex discovery tool with multiple filter dimensions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 9 parameters with 0% description coverage, and the description does not explain any parameter. While parameter titles like 'begin' and 'end' are suggestive, there is no clarification on data types, filtering semantics, or use of optional parameters like 'bbox' or 'hydrologic_unit_code'. The description fails to add value beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Discover' and specifies the resource 'time series, their parameters, units, availability, and IDs', which clearly indicates the tool's purpose of exploring metadata. However, it does not differentiate from sibling tools like 'get_observations' or 'get_latest_values' that also involve time series data, leaving ambiguity about when to use this for discovery vs. retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. The sibling tools include many that retrieve actual time series data, but the description does not contrast discovery with retrieval or mention prerequisites like data availability or time ranges.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only adds the list of returned data types. It does not disclose important behaviors such as pagination (max_rows), performance considerations, or authentication requirements, which are essential for a tool with 7 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. The verb 'Get' is front-loaded, and the entire content is directly about the tool's purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 7 parameters, an output schema, and many siblings, the description is extremely minimal. It does not cover usage context, parameter interactions, or output shape. The agent would need additional knowledge to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It implicitly adds meaning to 'kind' by listing its accepted values, but completely ignores the other 6 parameters (time, max_rows, properties, water_year, parameter_code, monitoring_location_id). The agent is left to infer their semantics from names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('discrete field measurements, metadata, channel measurements, or peaks'), which matches the 'kind' enum. However, it does not differentiate this generic tool from more specific siblings like get_peak_flows or get_current_flow, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusion criteria, leaving the agent to infer usage from the meaning of the 'kind' parameter alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's simple statement is adequate but adds no extra context about pagination, data limits, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence description is too brief for a tool with 8 parameters; it lacks critical information and is under-specified rather than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, many siblings), the description is incomplete—it does not explain typical usage, filtering options, or how it differs from similar tools, even though an output schema covers return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides zero explanation of the 8 parameters (e.g., statistic_id, approval_status), failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'observations' of type 'continuous' or 'daily' for one or more sites, distinguishing it from sibling tools like 'get_current_flow' or 'get_latest_values'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus sibling alternatives (e.g., get_daily_flow vs get_observations with kind=daily), leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive, so the description is not required to cover those. It adds value by specifying that results include both Celsius and Fahrenheit, but lacks other behavioral details like data freshness or caching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential action and output format. It is appropriately concise, though it could include a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and safety annotations, the description adequately covers the tool's purpose and output. However, it fails to document the required parameter, which is a notable gap in completeness for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description does not mention the required site_id parameter or explain its meaning. It misses the opportunity to clarify what site_id refers to (e.g., a monitoring site identifier).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), resource ('water temperature'), and output specifics ('Celsius and Fahrenheit values'). It distinguishes from sibling tools like get_water_level or get_flow by specifying the exact measurement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_water_level, get_observations). The description lacks context for choosing this tool among many similar get_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the context of 'modern OGC collection' but does not disclose additional behavioral traits such as performance, rate limits, or error scenarios. With annotations covering the safety profile, the description provides marginal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, concise and front-loaded with the verb 'List'. Every word is purposeful with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and annotations, the description is minimally adequate. It explains the tool's primary purpose but does not cover when to choose it over siblings or provide parameter details. For a simple fetch tool with one parameter, it meets baseline expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 mentions 'for a modern OGC collection' implying the 'collection' parameter identifies the collection, but it does not specify valid values, format, or examples. The single required parameter lacks sufficient semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists filterable fields and schemas for an OGC collection. The verb 'list' and resource 'filterable fields and schemas' are specific. However, it does not explicitly distinguish from sibling tools, though most siblings are about water flow data, making this tool unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, expected use cases, or exclusions. The agent must infer from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, etc.) already indicate safe read behavior. Description adds 'for a latitude and longitude' but does not disclose additional traits like rate limits or data freshness. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, directly states purpose and inputs. Perfectly concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has output schema, so return format is covered. However, with 0% schema coverage and no parameter details, the description is incomplete for a production context. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions for lat/lon). Description only says 'latitude and longitude' without specifying format, bounds, or required precision. The parameter names are clear but the description adds minimal value beyond the names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'NWS multi-period forecast', with coordinates as inputs. It distinguishes from siblings like get_hourly_forecast by specifying 'multi-period'. However, it could be more explicit about what 'multi-period' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_hourly_forecast or get_forecast_discussion. The description lacks contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this returns the 'latest' value and specifies parameter 00065, which provides some behavioral context but does not disclose units, potential missing data, or site activity requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 14 words, with no filler or redundancy. Every word contributes to meaning, and the single sentence is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter) and the existence of an output schema, the description provides minimal but adequate context: it returns the latest water level for a site. However, it lacks explanation of site_id format and cannot fully stand alone without schema reliance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the site_id parameter is completely undocumented in both schema and description. The description does not clarify that site_id is a USGS site number or its format, leaving the agent without guidance on how to construct valid input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get), the resource (latest gage height/water level), and includes the parameter code. It distinguishes this tool from siblings like get_current_flow by specifying 'water level' and 'gage height', but could be more explicit about differentiating from similar tools like get_stage_trend or get_observations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., get_observations for historical data, get_stage_trend for trends). The description does not specify prerequisites or context, leaving the agent to infer usage from the name and resource alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds 'discrete' and 'modern USGS Samples API', which provides some API context but no additional behavioral traits like pagination or rate limits. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the tool's purpose. It is front-loaded with the key verb and resource, with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich annotations and an output schema, the description fails to provide necessary context for the 7 parameters (0% schema coverage). It does not explain how to use parameters like start_date/end_date or the difference between characteristic and parameter_code, making it inadequate for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning no parameter descriptions are provided. The tool description does not explain any parameter (e.g., profile, characteristic, parameter_code) nor their relationships. This leaves the agent without essential guidance for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'discrete water-quality samples', and specifies the source 'modern USGS Samples API'. This distinguishes it from sibling tools like get_current_flow or get_observations, which are for continuous or different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_observations or search_time_series. There are no mentions of prerequisites, limitations, or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering safety and side effects. The description adds no behavioral context beyond 'look up codes,' such as rate limits or authentication needs, thus providing minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and purpose. No extraneous words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having annotations and an output schema, the description fails to guide parameter usage (e.g., valid collection values, query format). With 0% schema coverage, the description leaves the agent uncertain about how to correctly invoke the tool, making it incomplete for usage decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It names categories like 'parameter, statistic, site-type, state, county, or other codes' but does not clarify the meaning of the 'collection' parameter, the optional 'query' object, or 'max_rows.' The description adds no semantic value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Look up parameter, statistic, site-type, state, county, or other codes.' It uses a specific verb-resource pair ('look up' + 'reference data') and distinguishes this tool from sibling tools like get_observations or search_monitoring_locations by focusing on generic code lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for looking up various codes, but it does not explicitly state when to use this tool versus alternatives like search_monitoring_locations or search_sites. No usage exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive nature. The description adds that the name search is case-insensitive and explains the state parameter's accepted formats, which is helpful context beyond annotations. However, it does not disclose pagination behavior or result limits beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences that convey the core functionality and a key parameter detail. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema, the description covers the main search functionality but omits details about pagination (max_rows) and filtering (site_type). It is adequate but incomplete for a full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 'name' parameter's case-insensitivity and the 'state' parameter's format options, but does not explain 'max_rows' or 'site_type', leaving half the parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches monitoring locations by a case-insensitive partial name, which is a specific verb and resource. However, it does not differentiate from the sibling tool 'search_monitoring_locations', which likely has a similar function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention when not to use it. It simply states what it does without any context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making the safety profile clear. The description adds that it returns mean daily streamflow and that dates are ISO format, which provides useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences are appropriately concise. The first sentence clearly states the tool's purpose, and the second provides key parameter format info. Minor improvement: could structure parameter details more explicitly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered. However, the description fails to document site_id (required) and max_rows, leaving gaps for a 4-parameter, 3-required tool. The description is insufficient for full autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%: no parameter descriptions in the schema. The description only explains that start and end are ISO dates, but omits site_id and max_rows entirely. Two of four parameters remain unexplained, so the description adds limited value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves mean daily streamflow (parameter 00060, statistic 00003). This distinguishes it from sibling tools like get_current_flow, get_peak_flows, etc., which serve different temporal or statistical scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Given many sibling tools for different flow queries, explicit usage context (e.g., 'for historical daily averages, not real-time') would help the agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, making the non-modifying nature clear. The description adds no additional behavioral context (e.g., no mention of what happens if no data matches, or rate limits). Since annotations cover safety well, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise and front-loaded with the core purpose. However, it is too brief; additional structure (e.g., parameter listing) would improve usability without adding fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, 1 required, and many sibling tools, the description lacks completeness. It does not explain how parameters filter results (e.g., bbox vs monitoring_location_id), common use cases, or interaction logic. Output schema exists but parameter documentation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation for any of the 7 parameters. Parameter names like 'bbox', 'statistic_id', and 'properties' remain ambiguous without documentation. The description fails to add meaning beyond the basic schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the latest continuous or daily value per matching time series. It uses a specific verb ('Get') and resource ('latest...value per matching time series'), distinguishing it from siblings like `get_observations` or `get_daily_flow` which return series data generally.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings. The description implies it is for the latest value per series, but doesn't clarify that other tools (e.g., `get_observations`) might be better for historical ranges or specific data types. Usage context is present but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description confirms read-only nature with 'Find' but adds no extra behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Could benefit from slight expansion for parameter details, but remains concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no schema descriptions, the description is too brief. It omits key parameters and does not describe return format or behavior, despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and description only mentions some criteria (site, state, county, type, HUC, bbox) while 10 parameters exist. It fails to explain parameters like max_rows, skip_geometry, properties, site_type_code, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool finds USGS monitoring locations and lists multiple search criteria (site, state, county, type, HUC, bbox). It distinguishes from sibling tools like search_sites and search_time_series by specifying the resource and criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Sibling tools exist but no when-not or preferred usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false. Description adds no extra behavioral context (e.g., what happens on invalid site_id, rate limits, or that it returns a single value). Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low complexity (1 parameter, output schema exists). Description is adequate for basic use but lacks details on parameter format and temporal scope ('latest' ambiguous). Not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no description for site_id in schema). Description only mentions 'for a USGS site' but does not clarify format, example, or constraints. Insufficient for a single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Get', resource 'latest streamflow/discharge' (parameter 00060), and target 'USGS site'. Distinguishes from siblings like get_daily_flow and get_flow_anomalies by specifying 'current' and parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for current real-time flow data but does not explicitly state when to use vs alternatives (e.g., get_daily_flow for historical context). No exclusions or when-not-to-use provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it specifies the data source (NWS), the type of data (forecast with hourly precipitation odds), and the time range (1-168 hours). Annotations already indicate non-destructive, read-only behavior, so the description supplements with useful details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, perfectly front-loaded sentence with no filler. Every word adds value, specifying the tool's function, data source, and key feature (hourly precipitation odds).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits mention of other forecast elements (e.g., temperature, wind) that are likely included. However, it captures the essential distinctive feature (precipitation odds) and the time range, making it mostly complete for a forecast tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, so the description must compensate. It only mentions the hours range (1-168) but fails to explain lat and lon parameters. Without parameter descriptions, an agent lacks context for correct parameter input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves NWS forecast data with hourly precipitation odds for a specific time range (1-168 hours), distinguishing it from sibling tools like get_point_forecast which likely provides different forecast granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like get_point_forecast, which appears to be a closely related sibling. There are no usage constraints, prerequisites, or comparisons to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. Description adds specific resolution outputs (office, grid, zone) without contradicting annotations, but does not disclose additional behaviors like rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and key outputs, no wasted words. Ideal conciseness for a simple lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple purpose, rich annotations, and existence of an output schema, the description sufficiently conveys what the tool does. However, it could improve by noting that coordinates are in decimal degrees or that the output is a JSON object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; description does not explain parameters (lat, lon) beyond their names. No details on valid ranges, precision, or coordinate system, leaving agents to infer from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'resolve' and lists exact outputs (NWS office, grid, forecast zone, county, fire zone), clearly distinguishing from sibling tools that fetch data or alerts for given points.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., get_point_forecast). Context implies it is a coordinate-to-zone lookup, but lacks exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotence and read-only behavior. Description adds context about local timezone resolution and default date, but no additional behavioral traits beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with primary purpose. No redundant or verbose content. Earns its place efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with output schema covering return values. Description covers core usage and key defaults. Could hint at specific solar events returned, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description adds meaning for 'tz' (IANA timezone, local resolution) and 'date' (ISO, defaults). 'lat' and 'lon' are self-explanatory but could specify unit/range. Adds value but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Calculate local and UTC solar events using an IANA timezone', specifying a precise verb and resource. Given sibling tools focus on hydrological data, this tool's purpose is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when 'tz' and 'date' are omitted, providing clear defaults and behavior. While no explicit comparison to siblings, the domain difference makes usage context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral context beyond annotations: sorting by distance, coordinate system (WGS84), and default parameter meaning. Annotations already indicate read-only and idempotent, so no contradiction. Could mention pagination or radius behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key action and result, efficient use of words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details about radius_miles (distance limit vs. search area?), max_rows (pagination), and definition of active gauges. Output schema exists so return values not needed, but parameter behaviors are under-explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains parameter_code options and coordinate format. However, lat/lon range, max_rows, and radius_miles are not described. Partial but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'find' with specific resource 'nearest active gauges' and result 'sorted by distance'. Differentiates from siblings like search_sites or search_monitoring_locations which are broader.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States it finds nearest active gauges with latest reading, and provides parameter codes for different measurements (streamflow, gage height, temperature). Implicitly tells when to use, but lacks explicit alternatives or when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to add safety disclaimers. It adds the specific details shown (enabled, location, size, TTL policy), but does not elaborate on behavior beyond what annotations convey. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the tool's purpose and lists key attributes. It is concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists (not shown but indicated), the description covers the necessary information: what the tool returns (enabled, location, size, TTL policy). No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is trivially 100% covered. Per instructions, 0 parameters yields a baseline of 4. The description adds nothing about parameters, which is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows caching status including enabled, location, size, and TTL policy. It uses a specific verb ('Show') and resource ('cache info') and distinguishes itself from sibling tools like clear_cache or get_server_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking cache configuration, but it does not explicitly state when to use this tool versus alternatives like get_server_info or clear_cache. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by detailing duplicate removal, as_of behavior, partial failure handling, and caching policy (partial responses never cached). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently conveys the main purpose, constraints, and behavioral details. It is front-loaded with the core action. Minor improvement would be structuring into bullets, but it is still concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers inputs, limits, error handling, and relationships. It addresses all key aspects of tool usage without needing to reiterate return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains 'site_ids' as an array of strings for 1-25 USGS sites and 'as_of' as an optional ISO date. However, it does not specify format constraints or default behavior beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Compare current discharge with date normals for 1-25 USGS sites.' It also distinguishes from sibling tools like 'get_flow_anomaly' by specifying multiple sites and adding details about duplicate removal and as_of parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for use: it handles multiple sites, removes duplicates, and references the same fields as 'get_flow_anomaly'. It does not explicitly state when to use this tool instead of alternatives, but the mention of 1-25 sites implies it is for batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavioral nuance: the definition of seasonal peaks (largest annual peak in season, not maximum flow during season) and the caution 'Treat it as informational scale, not a safety threshold.' This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, but the explanation of seasonal peaks could be tightened. Overall, it is reasonably concise for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not explain return values. The tool has a single parameter and the description covers the essential behavioral nuance of seasonal peaks. It is complete for the complexity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is site_id, and its input schema has a title but no description. Schema coverage is 0%, so the description should compensate, but it does not describe site_id at all. The tool description provides no semantic meaning for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get annual discharge peaks with all-time, seasonal, and current context.' It specifies the verb 'get' and the resource 'annual discharge peaks', distinguishing it from siblings like get_current_flow or get_daily_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the definition of seasonal peaks and indicates it is informational, not a safety threshold. However, it does not explicitly state when to use this tool versus alternatives like get_current_flow, though the purpose makes it reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about data source (modern time-series metadata) and a limitation (no inference), which is beneficial beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the core purpose, and the second provides essential caveats. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers purpose, limitations, and data source for this simple, single-parameter read tool. No additional information is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by explaining the 'site_id' parameter. It does not mention the parameter at all, leaving the agent to rely solely on the schema's minimal definition. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves current gage height and published flood-stage thresholds. The verb 'get' and specific resource identifiers differentiate it from sibling tools like 'get_water_level' or 'get_latest_values'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains that threshold availability varies by site and that the operation does not infer thresholds. This provides useful context for when to use the tool, though it does not explicitly contrast with alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the content is 'latest' and 'raw', providing context beyond annotations. However, it doesn't mention potential error responses or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence of 12 words. Every word is necessary: verb, resource, attributes (latest, raw), and parameter constraint (three-letter WFO). No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers the purpose and parameter meaning adequately. It assumes domain knowledge of NWS terminology (WFO) but is sufficient for an AI agent. Could mention that invalid office codes result in errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for the 'office' parameter (0% coverage). The description specifies it must be a 'three-letter WFO', adding crucial formatting and value constraints that the schema lacks. This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'raw NWS Area Forecast Discussion', specifying it's for a three-letter WFO. This distinguishes it from sibling tools like get_point_forecast or get_hourly_forecast, which provide different types of forecast data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing the raw discussion text for a specific WFO, but does not explicitly contrast with alternative tools (e.g., get_point_forecast for numerical forecasts). No guidance on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 tool's safety profile is clear. The description adds value by specifying that the tool describes 'limits, common codes, and supported collections,' providing behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the key action 'Describe this server' and immediately specifies what aspects are covered. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and an output schema exists, the description covers the main purpose. It mentions server limits, common codes, and supported collections, which likely represent the output schema's content. While it could briefly mention output structure, the presence of an output schema makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (trivially). With no parameters to document, the description does not need to add parameter details. The baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to describe the server, its limits, common codes, and supported collections. This distinguishes it from sibling tools that focus on specific data retrieval (e.g., get_observations, get_water_level), making the tool's role as a metadata endpoint clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool over alternatives, but the context of sibling tools suggests it is the go-to for server metadata. However, it lacks explicit when-not-to-use advice or alternatives, resulting in only adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral detail: window duration semantics, separate time series evaluation, selection of series with greatest rise, and datum consistency. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences plus a code block for parameter explanation. It is front-loaded with the primary purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown), the description does not need to detail return values. It adequately conveys the output (rising, steady, falling) and provides enough context for a simple classification tool. Minor gap: no mention of possible edge cases or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It thoroughly explains the window parameter (ISO 8601, range 15min-72h, default PT6H). Site_id is not elaborated but is self-explanatory as a site identifier. Overall, it adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects whether a site's gage height is rising, steady, or falling, specifying the resource (gage height) and action (trend detection). It distinguishes itself from sibling tools like get_water_level or get_latest_values by focusing on trend classification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only explains the window parameter, not the decision context for choosing this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior. The description adds value by specifying that it deletes locally cached responses for NWS and USGS, providing more concrete behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 12 words, no fluff, and front-loads the action. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, zero parameters, and presence of an output schema, the description sufficiently covers the functionality. It includes scope ('for this server') and resource types (NWS, USGS).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. The description does not need to explain parameters, and the baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Delete' and the resource 'locally cached NWS and USGS API responses', making the tool's purpose clear and distinguishing it from the sibling tools that are primarily read operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (clearing cache) but does not explicitly state when to use it or when not to, nor does it mention alternatives. The sibling tools are all read-only, but no guidance is provided for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, open-world traits. The description adds valuable context about the meaning of an empty successful result, which is behavioral information not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no redundancy. The first sentence states the core function, the second provides usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two obvious parameters and an output schema, the description covers purpose, when to use, and the interpretation of empty results. It is sufficiently complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameters lat/lon are self-explanatory from their names and types. The description adds only 'for a point,' which is already implied, and does not provide range or format details. With 0% schema description coverage, minimal extra value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool retrieves active NWS watches, warnings, and advisories for a point, which is a specific verb-resource pairing. It distinguishes from siblings like get_point_forecast by focusing on alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: 'Check this first for flood and severe-weather safety questions.' It implies appropriate usage but does not mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it explains that the comparison uses the latest observation, the as_of parameter selects the comparison date, and how sites without normal statistics are handled. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, and each sentence adds essential information without redundancy. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (anomaly detection with historical stats, reliability flags), the description covers all necessary aspects: purpose, optional parameter, handling of missing stats, and interpretation guidance. An output schema exists, so return values are covered elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains the as_of parameter (optional, ISO date for comparison day) and implies site_id by context. The description adds meaning beyond the schema by clarifying the parameter's role and edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it compares current discharge with median and percentiles for a given date, using the verb 'compare' and the resource 'discharge with median and percentiles'. This distinguishes it from sibling tools like get_current_flow (raw current flow) and get_daily_flow (daily averages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for anomaly detection by comparing current flow to historical statistics for a date. It also provides guidance on interpreting results when ratio_reliable is false. However, it does not explicitly state when to use this tool versus alternatives like get_flow_anomalies (plural) or get_statistics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![nws-weather-usgs-water-mcp MCP server](https://glama.ai/mcp/servers/wylieswanson/nws-weather-usgs-water-mcp/badges/card.svg)](https://glama.ai/mcp/servers/wylieswanson/nws-weather-usgs-water-mcp)

Score Badge

Copy to your README.md:

[![nws-weather-usgs-water-mcp MCP server](https://glama.ai/mcp/servers/wylieswanson/nws-weather-usgs-water-mcp/badges/score.svg)](https://glama.ai/mcp/servers/wylieswanson/nws-weather-usgs-water-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wylieswanson/nws-weather-usgs-water-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server