Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nws-weather-usgs-water-mcp Get active alerts and current gage height for New Orleans"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server combining National Weather Service alerts and forecasts with
modern USGS water data. Weather comes from api.weather.gov; water data uses
the official Python dataretrieval.waterdata module and APIs under
api.waterdata.usgs.gov. It does not call legacy
waterservices.usgs.gov endpoints.
No API key is required. A persistent local cache reduces repeated calls while keeping live readings fresh.
One MCP for weather and water: correlate forecasts and alerts with nearby gauges without configuring separate services.
Current USGS stack: all water retrieval uses modern Water Data APIs—not
waterservices.usgs.gov.
Keyless by default: NWS needs an identifying User-Agent, but neither data
source requires credentials.
Public-API friendly: bounded queries and source-specific SQLite TTLs reduce repeat traffic without letting safety data become stale.
MCP-ready results: every data response is bounded, structured, JSON-safe, and explicit about cache state and truncation.
Related MCP server: stormscope
Tool | Purpose |
| Active NWS watches, warnings, and advisories for a point |
| Multi-period NWS point forecast |
| Up to 168 hourly periods with precipitation probability |
| Latest raw Area Forecast Discussion from an NWS office |
| Resolve a point to its NWS office, grid, and zones |
get_active_alerts is the highest-priority safety tool. An empty successful
result means NWS reports no active alerts for that point; it is not an error.
The primary tools use domain-friendly names and sensible USGS parameter-code defaults:
Tool | Purpose |
| Find nearby gauges that have a latest reading, with exact distance |
| Case-insensitive partial site-name search, optionally by state |
| Latest discharge ( |
| Current discharge compared with this date's median and percentiles |
| Bounded 1-25 site anomaly batch with visible, uncached per-site failures |
| Annual peaks with all-time, seasonal, and current-flow context |
| Mean daily discharge ( |
| Latest gage height ( |
| Rising/steady/falling gage-height trend without mixing time series |
| Latest water temperature ( |
| Latest gage height plus published action/flood thresholds |
| Local and UTC sunrise, sunset, noon, and civil twilight |
get_flood_stage reports only thresholds published in the USGS time-series
metadata. It does not invent a flood threshold when a site has none.
The server also exposes generic tools for monitoring locations, time series,
continuous and daily observations, latest values, field measurements, peaks,
statistics, water-quality samples, reference tables, and collection queryables.
Use get_server_info to discover supported collections and common parameter
codes. Use get_cache_info and clear_cache to inspect or reset local caching.
Category | Tools |
NWS weather and solar |
|
Focused USGS water |
|
General USGS access |
|
Server and cache |
|
Python 3.10 or newer and uv are recommended.
Run directly from the GitHub source without a permanent installation:
uvx --from git+https://github.com/wylieswanson/nws-weather-usgs-water-mcp.git \
nws-weather-usgs-water-mcpFrom a source checkout:
uv sync --frozen
uv run nws-weather-usgs-water-mcpRun those commands from a source checkout. Press Ctrl-C to stop the stdio server.
The server uses stdio transport and runs without credentials. GeoPandas is not required; geometries are returned as JSON coordinate arrays.
Results default to 200 rows and are capped at 5,000 rows. Change the process cap only when needed:
USGS_WATERDATA_MAX_ROWS=10000 uv run nws-weather-usgs-water-mcpUse an absolute path to this checkout:
{
"mcpServers": {
"nws-weather-usgs-water-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/nws-weather-usgs-water-mcp",
"run",
"nws-weather-usgs-water-mcp"
],
"env": {
"NWS_USER_AGENT": "nws-weather-usgs-water-mcp (you@example.com)"
}
}
}
}Neither API requires a key. NWS requires an identifying User-Agent; the
server supplies one automatically, and NWS_USER_AGENT lets you provide the
recommended application/contact value. If a deployment later needs higher
USGS limits, add "API_USGS_PAT": "your_key" to the same env object. That
optional key is sent only to USGS in the X-Api-Key header and is never cached.
Successful results are cached in a per-user SQLite database. SQLite provides safe access when several MCP client processes share the cache, and a cache failure never prevents a live API request.
Data | Default TTL |
NWS active alerts | 60 seconds maximum |
NWS forecasts and forecast discussions | 15 minutes |
NWS point-to-grid mapping | 7 days |
Latest readings, nearby gauges, flood stage, flow anomaly | 10 minutes |
Stage trend | 5 minutes |
Annual peak-flow history | 7 days |
Sun times for a resolved date/timezone | 7 days |
Continuous observations | 10 minutes |
Daily observations and USGS statistics | 6 hours |
Field data and other collections | 30 minutes |
Samples | 1 hour |
Site and time-series metadata | 6 hours |
Reference tables and queryable schemas | 24 hours |
Each tool result includes a cache object with hit, age_seconds, and
ttl_seconds. Only successful responses are cached; API errors are not.
Variable | Purpose |
| Disable caching |
| Override the OS-specific cache directory |
| Limit stored query results |
| Override defaults; alerts remain capped at 60s |
| Override alert TTL, capped at 60 seconds |
| Override forecast TTL |
| Override point-grid TTL |
| Override discussion TTL |
| Override current/latest-value TTL |
| Override stage-trend TTL |
| Override annual peak-flow history TTL |
| Calendar months classified as monsoon; all others are cool season |
| Override continuous-observation TTL |
| Override daily-value TTL |
| Override site/time-series metadata TTL |
| Override reference/queryable TTL |
| Override statistics TTL |
| Override water-quality sample TTL |
| Override deterministic sun-time TTL |
| Median floor below which flow-anomaly ratios are marked unreliable |
| Full-window or recent stage rise classified as rising |
| Full-window or recent stage drop classified as falling |
The get_cache_info MCP tool reports the active path and entry count;
clear_cache deletes all cached responses.
Ask an MCP client:
“Are there active alerts at 34.62, -111.25?”
“Give me the next 24 hourly forecast periods at Bull Pen trailhead.”
“Get the latest Flagstaff forecast discussion.”
“Find streamflow gauges within 20 miles of 33.45, -112.07.”
“What is the current flow at USGS site 01646500?”
“How abnormal is the current flow at Fossil Creek site 09507480?”
“How does West Clear Creek’s current flow compare with its record flood?”
“Give me mean daily flow at 01646500 from 2026-06-01 through 2026-06-30.”
“What are the current gage height and published flood stage at 01646500?”
“Is West Clear Creek at 09505800 rising over the last six hours?”
“When are sunrise, sunset, and civil dusk at 34.62, -111.25?”
“Find sites containing ‘Salt River’ in Arizona.”
Bare USGS site numbers such as 01646500 are automatically normalized to
modern monitoring-location IDs such as USGS-01646500. Time-series values can
be provisional, so consumers should retain approval_status and qualifier.
Flow-anomaly results retain the arithmetic ratio at low magnitudes but add
ratio_reliable and a percentile-led flow_state. When the day-of-year median
is below MIN_RELIABLE_MEDIAN_CFS, consumers should rank or alert from
flow_state and percentile_bucket, not the raw ratio. Classified states are
high, above_normal, normal, below_normal, low, and negligible;
flow_state is null only when no current observation exists to classify.
Stage-trend results group observations by time_series_id, compute each trend
independently, and return only the series with the largest rise. This prevents
primary and bubbler stages at different datums from corrupting change and rate
calculations. approval_status and qualifier remain attached to the selected
series. get_water_temperature retains the upstream value and
unit_of_measure fields and adds value_c and value_f conveniences.
Peak-flow results return one normalized discharge peak per water year. The
metadata.summary object contains the record peak, its date, years of record,
median annual peak, latest flow, and current_vs_record. It also groups those
annual records by the calendar month of peak_date: monsoon defaults to
July–September and cool season to October–June. Each season includes its peak,
peak date, median, and qualifying-year count; current_vs_monsoon_record
compares the latest flow with the configured monsoon record. Override the
monsoon months with USGS_PEAK_MONSOON_MONTHS using comma-separated months or
inclusive ranges such as 6-9; the cool season is always the complement.
Historical peaks are cached independently from the fresher current-flow
reading.
Sun times are calculated locally with Astral. Coordinates resolve to an IANA
timezone through the bundled timezonefinder data unless tz is supplied.
Every event has both _local and _utc ISO timestamps; no external API is
called and the tool does not estimate a canyon-specific latest safe start.
Data tools return a consistent envelope designed for MCP clients:
{
"data_type": "current_flow",
"row_count": 1,
"columns": ["monitoring_location_id", "time", "value", "unit_of_measure"],
"max_rows_reached": false,
"records": [{"monitoring_location_id": "USGS-01646500", "value": 1234}],
"metadata": {"source_url": "https://api.waterdata.usgs.gov/..."},
"cache": {"enabled": true, "hit": false, "age_seconds": 0, "ttl_seconds": 600}
}Fields within records vary by source collection. max_rows_reached tells the
client that it should narrow the query or deliberately request a larger bound.
Missing pandas values serialize as JSON null; timestamps use ISO 8601 and
geometries are plain coordinate arrays.
This project targets api.weather.gov and the versioned modern endpoints at
api.waterdata.usgs.gov, including the OGC API v0 collections. Those APIs
can evolve, so pin this package by release and review the changelog before
upgrading. NWS and USGS remain authoritative; this server only retrieves,
composes, bounds, caches, and serializes their data.
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyrightThe service layer is separate from the MCP registration layer, allowing unit tests to validate filtering, row caps, site-ID normalization, and JSON-safe serialization without network calls.
Other Python services can reuse the same validated operations without starting an MCP subprocess:
from nws_weather_usgs_water_mcp import operations
result = operations.get_current_flow("09507480")operations.py is the supported protocol-neutral facade. server.py is the
MCP adapter; HTTP applications should not call it through stdio or JSON-RPC.
See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md before publishing or contributing. Coding agents should also follow AGENTS.md; Claude-specific project context is in CLAUDE.md.
Delete all locally cached NWS and USGS API responses for this server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Find nearest active gauges with a latest reading, sorted by distance.
Coordinates are WGS84 decimal degrees. The default parameter 00060 finds streamflow gauges; use 00065 for gage height or 00010 for water temperature.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes | ||
| max_rows | No | ||
| radius_miles | No | ||
| parameter_code | No | 00060 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get active NWS watches, warnings, and advisories for a point.
Check this first for flood and severe-weather safety questions. An empty successful result explicitly means NWS reports no active alerts there.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Show whether local caching is enabled, its location, size, and TTL policy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
List the filterable fields and schemas for a modern OGC collection.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get the latest streamflow/discharge (parameter 00060) for a USGS site.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get mean daily streamflow (parameter 00060, statistic 00003).
start and end are ISO dates such as 2025-01-01.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| start | Yes | ||
| site_id | Yes | ||
| max_rows | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get discrete field measurements, metadata, channel measurements, or peaks.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| time | No | ||
| max_rows | No | ||
| properties | No | ||
| water_year | No | ||
| parameter_code | No | ||
| monitoring_location_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get current gage height and any published action/flood-stage thresholds.
Threshold availability varies by site. Values come from modern time-series metadata; this operation does not infer a threshold when none is published.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Compare current discharge with date normals for 1-25 USGS sites.
Duplicate site IDs are removed while preserving input order. as_of
optionally selects the comparison day using an ISO date; current discharge
remains the latest observation. The records use the same fields and
reliability guidance as get_flow_anomaly. If individual upstream
requests fail, successful records remain available and structured failures
are reported in metadata.errors; partial responses are never cached.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | ||
| site_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Compare current discharge with the median and percentiles for this date.
as_of optionally selects the comparison day using an ISO date. Current
discharge remains the latest observation. Sites without normal statistics
return current flow with a null ratio and a plain-language explanation.
When ratio_reliable is false, use flow_state and
percentile_bucket instead of ranking by the raw ratio.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | ||
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get the latest raw NWS Area Forecast Discussion for a three-letter WFO.
| Name | Required | Description | Default |
|---|---|---|---|
| office | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get 1-168 hours of NWS forecast data with hourly precipitation odds.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes | ||
| hours | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get the latest continuous or daily value per matching time series.
| Name | Required | Description | Default |
|---|---|---|---|
| bbox | No | ||
| kind | Yes | ||
| max_rows | No | ||
| properties | No | ||
| statistic_id | No | ||
| parameter_code | No | ||
| monitoring_location_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get continuous or daily observations for one or more sites.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| time | No | ||
| max_rows | No | ||
| properties | No | ||
| statistic_id | No | ||
| parameter_code | No | ||
| approval_status | No | ||
| monitoring_location_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get annual discharge peaks with all-time, seasonal, and current context.
Seasons use peak-date calendar months. By default, monsoon is July through September and cool season is the complementary October-through-June span. A seasonal peak is the largest annual peak whose date falls in that season, not the maximum flow observed during the season each year: a year whose annual peak was a winter flood contributes nothing to the monsoon figure even if it also had a large summer pulse. Treat it as informational scale, not a safety threshold.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get the NWS multi-period forecast for a latitude and longitude.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Describe this server, its limits, common codes, and supported collections.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Detect whether one site's gage height is rising, steady, or falling.
window is an ISO 8601 duration from 15 minutes through 72 hours. The
default is PT6H. Each gage-height time series is evaluated separately;
the result uses the series with the greatest rise and never mixes datums.
| Name | Required | Description | Default |
|---|---|---|---|
| window | No | PT6H | |
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get historical summary statistics for specific monitoring locations.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| end_date | No | ||
| max_rows | No | ||
| start_date | No | ||
| normal_type | No | ||
| interval_type | No | ||
| parameter_code | No | ||
| computation_type | No | ||
| monitoring_location_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Calculate local and UTC solar events using an IANA timezone.
When tz is omitted, the timezone is resolved locally from the point.
date is an ISO date and defaults to today in that timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | ||
| lat | Yes | ||
| lon | Yes | ||
| date | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get the latest gage height/water level (parameter 00065) for a site.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get discrete water-quality samples from the modern USGS Samples API.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | narrow | |
| end_date | No | ||
| max_rows | No | ||
| start_date | No | ||
| characteristic | No | ||
| parameter_code | No | ||
| monitoring_location_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Get latest water temperature with Celsius and Fahrenheit values.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Resolve a point to its NWS office, grid, forecast zone, county, and fire zone.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Look up parameter, statistic, site-type, state, county, or other codes.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| max_rows | No | ||
| collection | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Find USGS monitoring locations by site, state, county, type, HUC, or bbox.
| Name | Required | Description | Default |
|---|---|---|---|
| bbox | No | ||
| state | No | ||
| max_rows | No | ||
| site_type | No | ||
| properties | No | ||
| county_code | No | ||
| skip_geometry | No | ||
| site_type_code | No | ||
| hydrologic_unit_code | No | ||
| monitoring_location_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Search monitoring locations by a case-insensitive partial name.
state accepts a full name, two-letter postal abbreviation, or FIPS code.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| state | No | ||
| max_rows | No | ||
| site_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Discover time series, their parameters, units, availability, and IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| bbox | No | ||
| begin | No | ||
| state | No | ||
| max_rows | No | ||
| properties | No | ||
| parameter_code | No | ||
| hydrologic_unit_code | No | ||
| monitoring_location_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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.
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.
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.
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.
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.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.2clear_cachefind_gaugesget_active_alertsget_cache_infoget_collection_queryablesget_current_flowget_daily_flowget_field_dataget_flood_stageget_flow_anomaliesget_flow_anomalyget_forecast_discussionget_hourly_forecastget_latest_valuesget_observationsget_peak_flowsget_point_forecastget_server_infoget_stage_trendget_statisticsget_sun_timesget_water_levelget_water_quality_samplesget_water_temperatureget_wfo_for_pointlookup_reference_datasearch_monitoring_locationssearch_sitessearch_time_seriesScored across 29 tools
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.
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.
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.
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.
Hosted MCP server for Xweather weather data: conditions, forecasts, alerts, and more.
Smarter Weather MCP: forecasts, alerts, outlooks, observations, AQI, grids, and map imagery.
Get US weather forecasts, active alerts, and current observations.
Flood MCP — wraps Open-Meteo Flood API (free, no auth)