Keyless US streamflow / river-gauge / water-quality data from the USGS National Water Information System. Real-time and historical readings for tens of thousands of monitoring sites: discharge, gage height, water temperature, precipitation, dissolved oxygen, and more.
Three well-defined tools with complete input schemas and clear descriptions. Tool names follow verb_noun convention (current_conditions, daily_values, find_sites). Descriptions are detailed (150-200 chars) and explain WHAT, WHEN, and WHAT-RETURNS. All parameters have type declarations and descriptions. However, output schemas are not formally documented, only inferred from code. Parameter descriptions lack format constraints (e.g., date format YYYY-MM-DD is mentioned but not enforced via pattern). No error handling guidance for invalid inputs (bad site numbers, date ranges, state codes). No pagination guidance despite find_sites returning capped results.
Latest instantaneous (real-time) readings for one or more USGS gauge sites. Returns the most recent value per site × parameter — e.g. current streamflow and gage height for a river. Common parameter codes: 00060 = discharge/streamflow (ft³/s), 00065 = gage height (ft), 00010 = water temperature (°C), 00045 = precipitation (in), 00095 = specific conductance, 00300 = dissolved oxygen, 63680 = turbidity. Keyless.
Daily-values time series for a single USGS site + parameter over a date range. Returns one statistic per day (default mean). Useful for trends, hydrographs, and historical comparison. Common statCd: 00003 = mean, 00001 = max, 00002 = min. Common parameter codes: 00060 = discharge (ft³/s), 00065 = gage height (ft), 00010 = water temperature (°C). Keyless.
Discover active USGS gauge sites in a US state that are currently reporting a given parameter (real-time). Returns sites with their latest reading; useful for finding which gauges are live in a region. Can match many sites, so results are capped. Keyless.
Output schemas not formally documented. Code infers structure (count, readings array with site_number, site_name, latitude, longitude, parameter, parameter_code, unit, latest_value, datetime) but LLMs cannot see this without reading implementation. Agents cannot plan downstream operations confidently.
Parameter descriptions lack format constraints. 'start_date' and 'end_date' mention YYYY-MM-DD but do not declare a regex pattern or minLength/maxLength. 'state' accepts 2-letter codes but no enum constraint. LLMs may pass invalid formats (e.g., '2024/01/15' or 'Colorado') without validation feedback.
No error recovery guidance. If a site number is invalid or a date range is out of bounds, the tool returns {error: '...'} but does not suggest next steps (e.g., 'Try find_sites() to discover valid site numbers'). Agents cannot self-correct.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 60 | 2026-07-28+ | v2 |
find_sites returns capped results (default 30, max 60) but no pagination support. If an agent needs all sites in a state, it cannot iterate. Description mentions 'results are capped' but offers no next_cursor or offset mechanism.
Parameter 'limit' in find_sites lacks min/max bounds in schema. Description says 'default 30, max 60' but schema does not enforce this. LLMs may pass limit=1000 without validation.