Tools

Five tools for querying USGS water data, plus two for SQL analytics over the DuckDB-backed canvas dataframes that water_get_series and water_find_sites materialize:

water_list_parameters

Static lookup of well-known USGS parameter codes — no network call, instant response.

• Discover that 00060 = Discharge (ft³/s), 00065 = Gage height (ft), 00010 = Temperature (°C), 72019 = Depth to water level (ft), and more
• Filter by thematic domain: streamflow, groundwater, temperature, meteorological, water-quality, or all
• Use this first — parameter codes are required by every other water tool

water_find_sites

Discover USGS monitoring sites before calling data tools — all other tools require a site number.

• Geographic scoping: bounding box ("west,south,east,north" decimal degrees), 2-letter state code, bare 5-digit FIPS county code (e.g. 51013), or HUC watershed code — either a 2-digit major HUC (02) or an 8-digit minor HUC (02070008), the only two lengths NWIS accepts
• Site type filtering: ST (stream), GW (groundwater well), LK (lake/reservoir), SP (spring), and more
• Parameter filter: only return sites that have data for a specific parameter code — comma-separate to require several (e.g. 00060,00065)
• Data type filter: require sites with real-time (iv), daily (dv), or groundwater (gw) data
• Returns site number, name, coordinates, type, state/county/HUC codes, and drainage area (expanded mode only) — altitude is included in both modes when USGS records it
• Bounded result set: capped at 500 sites inline, with a truncated flag and upstreamTotal (the full upstream count) so an oversized query never overflows the response
• DataCanvas spillover: when the result is truncated and CANVAS_PROVIDER_TYPE=duckdb is set, the full match set is staged to a DuckDB-backed canvas — the response includes canvas_id and table_name to retrieve every match past the 500 cap via water_dataframe_query. Without DataCanvas, narrow the query with additional filters (county, HUC, bbox, parameter, data type) to bring the result under the cap

water_get_readings

Get the latest instantaneous (~15 min) values for one or more USGS monitoring sites.

• Batch up to 100 site numbers in a single call
• Accepts any parameter code discoverable via water_list_parameters
• Configurable lookback period via ISO 8601 duration (e.g. PT2H = last 2 hours, P7D = last 7 days)
• Returns per-site, per-parameter records with timestamp, value, unit, and provisional/approved qualifier
• Bounded by design: each series carries its 10 most recent records, with totalValues reporting how many the period actually held and truncated flagging the cap. Use water_get_series when you need the full series
• Partial batches are explicit: requested sites NWIS returns no data for are named in missingSites rather than dropped silently
• Groundwater depth available via parameterCd=72019 (the legacy gwlevels endpoint was decommissioned November 2025 — use the IV service instead)

water_get_series

Get a historical time series for a site and parameter over a date range.

• Daily values (DV service, one value per day) or instantaneous values (IV service, ~15 min resolution)
• Returns site name, parameter name, unit code, and time-ordered value records with qualifiers
• DataCanvas spillover: large date ranges (>500 records) automatically spill to a DuckDB-backed canvas when CANVAS_PROVIDER_TYPE=duckdb is set — response includes canvas_id and table_name for follow-up SQL via water_dataframe_query
• Without DataCanvas, returns the most recent 500 records with a truncated flag and totalRecords count
• Supports chaining: pass a prior canvas_id to append data to an existing canvas

water_get_conditions

Get current hydrologic conditions placed in full historical context.

• Fetches the current IV reading and the full daily percentile table in parallel
• Classifies the reading: record-high (≥ p95), above-normal (p75–p95), normal (p25–p75), below-normal (p10–p25), low (p05–p10), record-low (< p05)
• Pairs each class with a percentileLabel spelling out the threshold — record-high and record-low mark percentile-of-record extremes, not verified all-time records, and the label says so where the class name does not
• Ranks against the observation's own calendar day, so a reading near midnight is not compared against the neighboring day's percentiles
• Discloses the granularity approximation in comparisonBasis: the reading is instantaneous while the percentiles are approved daily-mean values, so the class is a "how unusual is this" ranking — not a flood-stage or drought determination, which need authoritative thresholds this tool does not fetch
• Validates site and parameterCd at the schema edge; a well-formed value NWIS still rejects surfaces as the typed invalid_request reason rather than an opaque upstream error
• Gracefully degrades when historical context is missing: returns the current reading with historicalContext: null and a historicalContextStatus saying why — no_record (new/short record), no_matching_day (no row for the date), or unavailable (stat call failed — transient and retryable, kept distinct from a sparse record)

water_dataframe_describe / water_dataframe_query

In-conversation SQL analytics over the dataframes that water_get_series and water_find_sites materialize on a DuckDB-backed canvas — time-series tables from the former, full site match sets from the latter.

Workflow:

1. Call water_get_series with a large date range, or water_find_sites with a query that matches more than 500 sites — when DataCanvas is enabled, the response includes canvas_id and table_name
2. Call water_dataframe_describe with the canvas_id to confirm the table schema — series tables carry date_time, value, qualifiers, site_number, parameter_cd, unit_code; site tables carry site_number, site_name, site_type, latitude, longitude, huc_cd, and the expanded fields
3. Call water_dataframe_query with the canvas_id and a SELECT statement to run aggregates, filter, or join

Read-only by default — only SELECT statements are permitted. Results are capped at 10,000 rows; a query matching more comes back with truncated: true. Requires CANVAS_PROVIDER_TYPE=duckdb in the server environment.

Resources and prompts