usgs-water-mcp-server

Look up USGS parameter codes — the 5-digit codes every other tool's parameterCd takes. With no query, lists a curated set of well-known codes with names, units, and thematic group, from a built-in table (no network call): 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), and others; filter it with group. For anything else — turbidity, nitrate, chlorophyll, suspended sediment, salinity — pass query to search the full USGS parameter-code catalog (~19,600 codes) by name and description, or pass a 5-digit code to look it up. A query returns at most 25 entries, matching curated codes first, with total counting every match.

{
  "type": "object",
  "properties": {
    "group": {
      "default": "all",
      "description": "Filter the curated list by thematic domain: \"streamflow\", \"groundwater\", \"temperature\", \"meteorological\", \"water-quality\", or \"all\" (default). Applies to the curated list only — leave it \"all\" when passing query.",
      "type": "string",
      "enum": [
        "streamflow",
        "groundwater",
        "temperature",
        "meteorological",
        "water-quality",
        "all"
      ]
    },
    "query": {
      "description": "Search the full USGS parameter-code catalog. Case-insensitive; every word must start a word in the parameter name or description (e.g. \"turbidity\", \"nitrate filtered\", \"dissolved oxygen\"). A bare 5-digit code (e.g. \"63680\") returns that code. Omit to list the curated codes.",
      "type": "string",
      "maxLength": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "parameters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "5-digit USGS parameter code (e.g. \"00060\")."
          },
          "name": {
            "type": "string",
            "description": "Human-readable parameter name (e.g. \"Discharge\")."
          },
          "unit": {
            "type": "string",
            "description": "Unit of measure (e.g. \"ft³/s\", \"ft\", \"°C\", \"FNU\")."
          },
          "group": {
            "description": "Thematic domain of a curated entry. Absent on usgs-catalog entries.",
            "type": "string",
            "enum": [
              "streamflow",
              "groundwater",
              "temperature",
              "meteorological",
              "water-quality"
            ]
          },
          "description": {
            "description": "USGS catalog description, naming the medium, fraction, and method (e.g. \"Turbidity, water, unfiltered, … formazin nephelometric units (FNU)\"). Present on usgs-catalog entries only.",
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "curated",
              "usgs-catalog"
            ],
            "description": "\"curated\": one of the well-known codes this server lists by default. \"usgs-catalog\": a record from the full USGS parameter-code catalog."
          }
        },
        "required": [
          "code",
          "name",
          "unit",
          "source"
        ],
        "additionalProperties": false,
        "description": "A USGS parameter code entry."
      },
      "description": "Matching parameter entries. Without query: the curated codes. With query: matching curated codes first (each once, as its curated entry), then catalog records whose name holds every query word, then those matched through the description, each by code — at most 25."
    },
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Number of entries that matched, before the 25-entry cap."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when a query matched more than 25 entries and only the first 25 are listed — add words to narrow it."
    },
    "query": {
      "description": "The catalog query searched, trimmed. Absent when listing the curated codes.",
      "type": "string"
    },
    "note": {
      "description": "Guidance when a query matched nothing or was truncated. Absent otherwise.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `query_with_group`: query was combined with a group other than \"all\". group filters the curated list only; the USGS catalog carries no matching grouping. `upstream_error`: The USGS parameter-code catalog could not be read — the request failed, timed out, or returned something other than a catalog page. Other values are possible when a failure originates below the handler.",
              "examples": [
                "query_with_group",
                "upstream_error"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "parameters",
        "total",
        "truncated"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code, filtered by site type and parameter availability. Returns site numbers, names, coordinates, types, altitude, and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Supply exactly one major filter — bbox, stateCd, countyCd, or huc; siteType, parameterCd, and hasDataTypeCd only narrow within it and cannot stand alone. Page through matches with limit/offset (500 per page); truncated=true means matches remain after the returned window and upstreamTotal holds the full count. When the match set exceeds 500 and DataCanvas is enabled, the complete set also stages to a canvas (canvas_id/table_name) — inspect it with water_dataframe_describe, then retrieve it with water_dataframe_query.

{
  "type": "object",
  "properties": {
    "bbox": {
      "description": "Bounding box as \"west,south,east,north\" in decimal degrees (e.g. \"-77.5,38.5,-76.5,39.5\" for the DC metro area). One of the four major filters — bbox, stateCd, countyCd, and huc are mutually exclusive with each other, and exactly one must be supplied.",
      "type": "string",
      "pattern": "^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"
    },
    "stateCd": {
      "description": "2-character US state abbreviation (e.g. \"VA\", \"WA\"). Returns all sites in the state for the given filters. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "countyCd": {
      "description": "FIPS county code(s) as bare 5-digit numbers — state and county digits concatenated, no separator (e.g. \"51013\" for Arlington, VA). Comma-separate up to 20 (e.g. \"51059,51061\"). The 5 digits already encode the state, so the code stands alone. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
      "type": "string",
      "pattern": "^\\d{5}(,\\d{5}){0,19}$"
    },
    "huc": {
      "description": "Hydrologic Unit Code (HUC) scoping results to a watershed. Either a 2-digit major HUC (e.g. \"02\" for the Mid-Atlantic region) or an 8-digit minor HUC (e.g. \"02070008\" for the Middle Potomac). NWIS accepts no other lengths. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
      "type": "string",
      "pattern": "^(\\d{2}|\\d{8})$"
    },
    "siteType": {
      "description": "Site type filter. Common codes: \"ST\" (stream), \"GW\" (groundwater well), \"LK\" (lake/reservoir), \"SP\" (spring), \"AT\" (atmosphere), \"OC\" (ocean), \"ES\" (estuary). Comma-separate multiple types (e.g. \"ST,GW\").",
      "type": "string"
    },
    "parameterCd": {
      "description": "5-digit parameter code to require at each returned site (e.g. \"00060\" for discharge). Use water_list_parameters to discover codes. Comma-separate multiple codes with no spaces (e.g. \"00060,00065\").",
      "type": "string",
      "pattern": "^\\d{5}(,\\d{5})*$"
    },
    "hasDataTypeCd": {
      "description": "Require sites with data of this type. Common values: \"iv\" (real-time/instantaneous), \"dv\" (daily values), \"gw\" (groundwater). Comma-separate multiple types.",
      "type": "string"
    },
    "siteOutput": {
      "default": "basic",
      "description": "\"basic\" returns core identification fields. \"expanded\" adds drainage area, altitude, contributing area, and other metadata.",
      "type": "string",
      "enum": [
        "basic",
        "expanded"
      ]
    },
    "limit": {
      "default": 500,
      "description": "Maximum sites to return inline, 1–500. Default 500 (the inline cap).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Number of matching sites to skip before returning results. Page through matches beyond the inline cap by advancing offset by limit. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "canvas_id": {
      "description": "Canvas ID from a prior call to add this match set as a table on an existing canvas rather than creating a new one. Each distinct filter set gets its own table name, so re-running the identical query replaces its own table while a different query adds another alongside it. Applies only when the match set exceeds the inline cap and DataCanvas is enabled. Omit to start a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "sites": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "siteNumber": {
            "type": "string",
            "description": "USGS site number (8–15 digits). Used by all other water tools."
          },
          "siteName": {
            "type": "string",
            "description": "Human-readable USGS site name (e.g. \"POTOMAC RIVER AT LITTLE FALLS, MD\")."
          },
          "siteType": {
            "type": "string",
            "description": "USGS site type code (e.g. \"ST\"=stream, \"GW\"=groundwater well, \"LK\"=lake/reservoir)."
          },
          "latitude": {
            "type": "number",
            "description": "Decimal latitude in WGS 84."
          },
          "longitude": {
            "type": "number",
            "description": "Decimal longitude in WGS 84."
          },
          "stateCd": {
            "description": "2-digit FIPS state code (e.g. \"51\" for Virginia). Populated only when siteOutput=\"expanded\"; absent in basic mode.",
            "type": "string"
          },
          "countyCd": {
            "description": "3-digit FIPS county code within the state (zero-padded, e.g. \"013\"). Populated only when siteOutput=\"expanded\"; absent in basic mode.",
            "type": "string"
          },
          "hucCd": {
            "description": "Hydrologic Unit Code of the watershed containing this site; width varies (8-digit HUC8 and 12-digit HUC12, e.g. \"020700081005\", are both common — do not assume a fixed width), and absent when NWIS assigns none. Do not pass it straight back to the huc filter (which takes 2 or 8 digits); HUCs nest, so its first 8 digits are the containing HUC8 that filter accepts.",
            "type": "string"
          },
          "drainageArea": {
            "description": "Total drainage area in square miles. Populated only when siteOutput=\"expanded\"; absent in basic mode.",
            "type": "number"
          },
          "altitude": {
            "description": "Altitude of the gage datum in feet above sea level (NAVD 88 or NGVD 29). Present in both basic and expanded modes when USGS records an altitude for the site.",
            "type": "number"
          },
          "contributingArea": {
            "description": "Contributing drainage area in square miles (may differ from drainageArea for regulated basins). Populated only when siteOutput=\"expanded\"; absent in basic mode.",
            "type": "number"
          }
        },
        "required": [
          "siteNumber",
          "siteName",
          "siteType",
          "latitude",
          "longitude"
        ],
        "additionalProperties": false,
        "description": "A USGS monitoring site with location, type, and available data."
      },
      "description": "The requested window of matching USGS monitoring sites — the slice starting at offset, at most limit long (500 max). upstreamTotal holds the full match count; canvas_id/table_name point to the staged full set when it exceeded the cap and DataCanvas is enabled."
    },
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Number of sites returned inline in this response — at most limit, and 0 when offset is at or past upstreamTotal."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when matches remain after the returned window (offset + total < upstreamTotal) — false on the last page, and false for a window starting past the end of the match set, where the notice names the valid offset range instead. Advance offset by limit for the next page, narrow filters (add bbox, countyCd, huc, siteType, parameterCd, or hasDataTypeCd), or when canvas_id is present read the staged set with water_dataframe_describe then water_dataframe_query."
    },
    "upstreamTotal": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Total number of sites matching the query upstream, before limit/offset windowing. Equals total when the whole match set fits in one window."
    },
    "canvas_id": {
      "description": "Canvas ID for the DataCanvas holding the full, uncapped match set. Present only when the match set exceeded the 500-site cap and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query to retrieve sites beyond the inline cap.",
      "type": "string"
    },
    "table_name": {
      "description": "DuckDB table name in the canvas holding all matching sites. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL.",
      "type": "string"
    },
    "filters": {
      "type": "object",
      "properties": {
        "stateCd": {
          "description": "State filter applied, if any.",
          "type": "string"
        },
        "countyCd": {
          "description": "County FIPS filter applied, if any.",
          "type": "string"
        },
        "siteType": {
          "description": "Site type filter applied, if any.",
          "type": "string"
        },
        "parameterCd": {
          "description": "Parameter code filter applied, if any.",
          "type": "string"
        },
        "bbox": {
          "description": "Bounding box filter applied, if any.",
          "type": "string"
        },
        "huc": {
          "description": "HUC watershed filter applied, if any.",
          "type": "string"
        },
        "hasDataTypeCd": {
          "description": "Data type filter applied, if any.",
          "type": "string"
        },
        "siteOutput": {
          "type": "string",
          "enum": [
            "basic",
            "expanded"
          ],
          "description": "Site output mode used (basic or expanded)."
        }
      },
      "required": [
        "siteOutput"
      ],
      "additionalProperties": false,
      "description": "Filters applied to this query."
    },
    "notice": {
      "description": "Advisory about the returned window: the staged canvas and how to read it, the filters to narrow by, the window actually returned, the valid offset range when the request landed past the end of the match set, or the fact that a supplied canvas_id went unused because nothing was staged.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_sites_found`: No sites match the given geographic and filter criteria. `missing_major_filter`: None of bbox, stateCd, countyCd, or huc was supplied. NWIS scopes every site query by exactly one of them; siteType, parameterCd, and hasDataTypeCd only narrow within that scope. `conflicting_major_filters`: More than one of bbox, stateCd, countyCd, and huc was supplied. NWIS accepts exactly one per request. `invalid_request`: NWIS rejected the request. Filter formats are pattern-validated and the major-filter rule is enforced before the call, so this surfaces a well-formed value NWIS still refused — an unknown state, county, HUC, parameter, or site-type code. `upstream_error`: NWIS returned a 5xx error or the request timed out. `canvas_not_found`: The supplied canvas_id names a canvas that never existed or has expired. Raised before the NWIS request, so no upstream call is spent on it. `canvas_capacity_exhausted`: canvas_id was omitted and a fresh canvas was needed to stage the match set, but this tenant already holds the maximum number of active canvases. Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_sites_found",
                "missing_major_filter",
                "conflicting_major_filters",
                "invalid_request",
                "upstream_error",
                "canvas_not_found",
                "canvas_capacity_exhausted"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "sites",
        "total",
        "truncated",
        "upstreamTotal",
        "filters"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Get the latest instantaneous (~15-min, real-time) values for up to 100 USGS sites in one call — per-site, per-parameter records with timestamp, value, unit, and provisional/approved qualifiers. Omitting parameterCd returns every parameter each site publishes. A site measuring one parameter with several sensors returns one series per method, each named by methodId and methodDescription. At most 100 series return per call — every site that returned data keeps at least one, and totalSeries reports how many NWIS returned; pass parameterCd or split the sites across calls to reach the rest. Each series returns only its 10 most recent records (totalValues reports the true count); truncated=true when either cap applied. Use water_get_series for a full date-range series. Sites NWIS returns nothing for are listed in missingSites, not dropped silently. Use water_find_sites first to discover site numbers and available parameters.

{
  "type": "object",
  "properties": {
    "sites": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d{8,15}$",
        "description": "A USGS site number (8–15 digits, e.g. \"01646500\")."
      },
      "description": "One or more USGS site numbers to query. Maximum 100 per call."
    },
    "parameterCd": {
      "description": "Parameter codes to return. Omit to get every parameter each site publishes — one series per site, parameter, and method, so a large batch can exceed the 100-series cap. Use water_list_parameters to discover codes.",
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^\\d{5}$",
        "description": "A 5-digit USGS parameter code (e.g. \"00060\" for discharge)."
      }
    },
    "period": {
      "default": "PT2H",
      "description": "ISO 8601 duration for the lookback period (e.g. \"PT2H\" = last 2 hours, \"P1D\" = last 1 day, \"P7D\" = last 7 days). Default: \"PT2H\" (last 2 hours of readings). Widening it raises totalValues, but each series still returns only its 10 most recent records — use water_get_series to retrieve a full series.",
      "type": "string",
      "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$"
    }
  },
  "required": [
    "sites"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "readings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "siteNumber": {
            "type": "string",
            "description": "USGS site number (8–15 digits, e.g. \"01646500\")."
          },
          "siteName": {
            "type": "string",
            "description": "Human-readable USGS site name (e.g. \"POTOMAC RIVER AT LITTLE FALLS, MD\")."
          },
          "parameterCd": {
            "type": "string",
            "description": "5-digit parameter code (e.g. \"00060\" for discharge)."
          },
          "parameterName": {
            "type": "string",
            "description": "Human-readable parameter name with units (e.g. \"Streamflow, ft³/s\")."
          },
          "unitCode": {
            "type": "string",
            "description": "Unit of measure for the values in this series (e.g. \"ft3/s\", \"ft\", \"°C\")."
          },
          "methodId": {
            "description": "NWIS method ID of this series. A site can measure one parameter with several sensors or at several locations — each is its own method and its own entry in readings. Null only when NWIS returned the series with no method block.",
            "type": [
              "string",
              "null"
            ]
          },
          "methodDescription": {
            "description": "NWIS description of the method, e.g. \"From multiparameter sonde\", \"[(2)]\", or \"7.1 ft from riverbed (top), [Discontinued]\". Null when NWIS leaves it blank, as it does for the default series at most single-sensor sites.",
            "type": [
              "string",
              "null"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "dateTime": {
                  "type": "string",
                  "description": "ISO 8601 date-time of this observation."
                },
                "value": {
                  "type": "string",
                  "description": "Measured value as a string. Empty string when NWIS reported no value for that interval — qualifiers then give the reason (e.g. \"Ssn\" seasonal, \"Dis\" discontinued, \"Dry\", \"Eqp\" equipment malfunction)."
                },
                "qualifiers": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "A USGS data qualifier code (e.g. \"P\" = provisional, \"A\" = approved)."
                  },
                  "description": "Data qualifier codes for this value."
                }
              },
              "required": [
                "dateTime",
                "value",
                "qualifiers"
              ],
              "additionalProperties": false,
              "description": "A single instantaneous reading for this site and parameter."
            },
            "description": "Time-ordered value records for this site and parameter, capped at the most recent 10. Compare with totalValues to see whether the period held more; use water_get_series for the full series."
          },
          "totalValues": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Number of value records NWIS returned for this site and parameter over the requested period, before the 10-record cap. Equals values.length when nothing was capped."
          }
        },
        "required": [
          "siteNumber",
          "siteName",
          "parameterCd",
          "parameterName",
          "unitCode",
          "methodId",
          "methodDescription",
          "values",
          "totalValues"
        ],
        "additionalProperties": false,
        "description": "Time series result for one site + parameter + method combination."
      },
      "description": "Time series per site + parameter + method combination, in NWIS order (site, then parameter code, then method). A method block NWIS returned empty is omitted when another method of the same site and parameter carries values. At most 100: past that, series are kept round-robin across sites — every site's first series, then every site's second — with a site's series carrying values ahead of its empty ones, a series whose every record is no data counting as empty."
    },
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Number of site + parameter + method time series returned in readings (at most 100)."
    },
    "totalSeries": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Number of site + parameter + method time series before the 100-series cap — an empty method block omitted as described under readings is not counted. Greater than total exactly when the cap dropped series; narrow with parameterCd or split the sites across calls to get the rest."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when either cap applied. The series cap: totalSeries > total — pass parameterCd or split the sites across calls. The 10-record cap: some readings[].totalValues > values.length — use water_get_series for the full series."
    },
    "missingSites": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A requested USGS site number that returned no time series."
      },
      "description": "Requested site numbers NWIS returned no series for — the site may not exist, or may not measure the requested parameter(s) in the requested period. Empty when every requested site returned data. Verify these with water_find_sites."
    },
    "query": {
      "type": "object",
      "properties": {
        "sites": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Site numbers queried."
        },
        "parameterCd": {
          "description": "Parameter codes requested, if filtered.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "period": {
          "type": "string",
          "description": "Lookback period applied (ISO 8601 duration)."
        }
      },
      "required": [
        "sites",
        "period"
      ],
      "additionalProperties": false,
      "description": "Query parameters used for this request."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_data_for_parameter`: NWIS returned no time series — the site(s) may not exist, or may not have data for the requested parameter(s) in the requested period. NWIS returns the same empty response for both cases. `invalid_request`: NWIS rejected the request. Input formats are validated against NWIS-accepted patterns before the call, so this surfaces a value that is well-formed but unacceptable upstream. `upstream_error`: NWIS returned a 5xx error, timed out, or sent a response body that is not valid WaterML-JSON (cut off mid-document), and retrying did not clear it. Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_data_for_parameter",
                "invalid_request",
                "upstream_error"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "readings",
        "total",
        "totalSeries",
        "truncated",
        "missingSites",
        "query"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. NWIS can hold several series for one query — one per daily statistic (mean, maximum, minimum) and one per sensor (method); this returns one, reporting its statCd and methodId, and lists the rest in otherSeries so any can be re-requested with the statCd and methodId inputs. By default it returns the daily mean when NWIS returns one with values, and the method with the most records. Large sets (>500 records) return the most recent records inline with truncated=true — the last 500 without DataCanvas, and with DataCanvas enabled the complete series also spills to a canvas (canvas_id/table_name): inspect the staged table with water_dataframe_describe, then read the full series with water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs.

{
  "type": "object",
  "properties": {
    "site": {
      "type": "string",
      "pattern": "^\\d{8,15}$",
      "description": "USGS site number (8–15 digits, e.g. \"01646500\" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers."
    },
    "parameterCd": {
      "type": "string",
      "pattern": "^\\d{5}$",
      "description": "A single 5-digit USGS parameter code (e.g. \"00060\" for discharge, \"00065\" for gage height). One code per call — this tool returns one series. Use water_list_parameters to discover available codes."
    },
    "startDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start date in YYYY-MM-DD format (e.g. \"2024-01-01\")."
    },
    "endDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "End date in YYYY-MM-DD format (e.g. \"2024-12-31\")."
    },
    "seriesType": {
      "default": "daily",
      "description": "\"daily\" returns one value per day (DV service, typically mean/max/min). \"instantaneous\" returns ~15-minute readings (IV service). Default: \"daily\". Use \"instantaneous\" for high-resolution analysis.",
      "type": "string",
      "enum": [
        "daily",
        "instantaneous"
      ]
    },
    "statCd": {
      "description": "Daily statistic to return, as a 5-digit NWIS code: \"00003\" mean, \"00001\" maximum, \"00002\" minimum. Omit for the mean when NWIS returns one with values, otherwise the first statistic that has values; the response names the one returned and lists the others in otherSeries. Daily series only — instantaneous values carry just \"00000\".",
      "type": "string"
    },
    "methodId": {
      "description": "NWIS method ID of the sensor series to return — the methodId or an otherSeries[].methodId from a prior response for the same site, parameter, and seriesType. Omit for the method with the most records. IDs differ between daily and instantaneous series and between daily statistics.",
      "type": "string"
    },
    "canvas_id": {
      "description": "Canvas ID from a prior call to add this series as a table on an existing canvas rather than creating a new one. Each distinct site, parameter code, series type, date range, and selected statistic and method gets its own table name, so re-running the identical query replaces its own table while a different query adds another alongside it. Applies only when the series spills to a canvas. Omit to start a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "site",
    "parameterCd",
    "startDate",
    "endDate"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "siteNumber": {
      "type": "string",
      "description": "USGS site number (8–15 digits, e.g. \"01646500\")."
    },
    "siteName": {
      "type": "string",
      "description": "Human-readable USGS site name."
    },
    "parameterCd": {
      "type": "string",
      "description": "5-digit USGS parameter code (e.g. \"00060\" for discharge)."
    },
    "parameterName": {
      "type": "string",
      "description": "Human-readable parameter name with units (e.g. \"Streamflow, ft³/s\")."
    },
    "unitCode": {
      "type": "string",
      "description": "Unit of measure for all values in this series (e.g. \"ft3/s\", \"ft\")."
    },
    "seriesType": {
      "type": "string",
      "enum": [
        "daily",
        "instantaneous"
      ],
      "description": "\"daily\" = one value per day (DV service); \"instantaneous\" = ~15-minute readings (IV service)."
    },
    "statCd": {
      "type": "string",
      "description": "NWIS statistic code of the returned series: \"00003\" daily mean, \"00001\" daily maximum, \"00002\" daily minimum, \"00000\" for instantaneous values."
    },
    "statName": {
      "description": "Statistic name NWIS attaches to statCd (e.g. \"Mean\", \"Maximum\"). Null when NWIS gives none, as for instantaneous values.",
      "type": [
        "string",
        "null"
      ]
    },
    "methodId": {
      "description": "NWIS method ID of the sensor series returned. Pass it back as the methodId input to request this series again. Null only when NWIS returned the series with no method block.",
      "type": [
        "string",
        "null"
      ]
    },
    "methodDescription": {
      "description": "NWIS description of that method (e.g. \"From multiparameter sonde\", \"7.1 ft from riverbed (top), [Discontinued]\"). Null when NWIS leaves it blank, as it does for the default series at most single-sensor sites.",
      "type": [
        "string",
        "null"
      ]
    },
    "values": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dateTime": {
            "type": "string",
            "description": "ISO 8601 date or date-time of this observation."
          },
          "value": {
            "type": "string",
            "description": "Measured value as a string. Empty string when NWIS reported no value for that interval — qualifiers then give the reason (e.g. \"Ssn\" seasonal, \"Dis\" discontinued, \"Dry\", \"Eqp\" equipment malfunction). A staged canvas table holds NULL for these."
          },
          "qualifiers": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A USGS data qualifier code (e.g. \"P\" = provisional, \"A\" = approved)."
            },
            "description": "Data qualifier codes for this value."
          }
        },
        "required": [
          "dateTime",
          "value",
          "qualifiers"
        ],
        "additionalProperties": false,
        "description": "A single value record with date-time, value, and qualifiers."
      },
      "description": "Time-ordered value records, oldest first within the slice. Holds every record when truncated is false; when truncated, the most recent records only — the last 500 without DataCanvas, or the last N that fit the inline preview budget when the full series is staged on a canvas."
    },
    "totalRecords": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Total number of records in the upstream result set (before any truncation)."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when the result exceeds 500 records and only the most recent were returned inline. When canvas_id is present, inspect the staged table with water_dataframe_describe then read the full series with water_dataframe_query; otherwise narrow the date range."
    },
    "canvas_id": {
      "description": "Canvas ID for the DataCanvas holding the full time series. Present only when truncated=true and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query.",
      "type": "string"
    },
    "table_name": {
      "description": "DuckDB table name in the canvas holding all records. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL.",
      "type": "string"
    },
    "otherSeries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "statCd": {
            "type": "string",
            "description": "NWIS statistic code of this series (e.g. \"00001\")."
          },
          "statName": {
            "description": "Statistic name for statCd (e.g. \"Maximum\"); null when NWIS gives none.",
            "type": [
              "string",
              "null"
            ]
          },
          "methodId": {
            "description": "NWIS method ID of this series — pass as the methodId input.",
            "type": [
              "string",
              "null"
            ]
          },
          "methodDescription": {
            "description": "NWIS description of the method; null when blank.",
            "type": [
              "string",
              "null"
            ]
          },
          "recordCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Number of value records this series holds over the requested range."
          }
        },
        "required": [
          "statCd",
          "statName",
          "methodId",
          "methodDescription",
          "recordCount"
        ],
        "additionalProperties": false,
        "description": "One series NWIS returned for this query that was not selected."
      },
      "description": "Every other statistic × method series NWIS returned for this query — re-request one with its statCd and methodId. Empty when the query produced a single series. A method block with no values over the range is omitted when another method of the same statistic has values."
    },
    "query": {
      "type": "object",
      "properties": {
        "site": {
          "type": "string",
          "description": "Site number queried."
        },
        "parameterCd": {
          "type": "string",
          "description": "Parameter code queried."
        },
        "startDate": {
          "type": "string",
          "description": "Start date applied (YYYY-MM-DD)."
        },
        "endDate": {
          "type": "string",
          "description": "End date applied (YYYY-MM-DD)."
        },
        "seriesType": {
          "type": "string",
          "enum": [
            "daily",
            "instantaneous"
          ],
          "description": "Series type used."
        },
        "statCd": {
          "description": "Statistic code requested, if any.",
          "type": "string"
        },
        "methodId": {
          "description": "Method ID requested, if any.",
          "type": "string"
        }
      },
      "required": [
        "site",
        "parameterCd",
        "startDate",
        "endDate",
        "seriesType"
      ],
      "additionalProperties": false,
      "description": "Query parameters used for this request."
    },
    "notice": {
      "description": "Advisory about this result: the staged canvas table and how to read it, the advice to narrow the date range when the series was truncated with no canvas available, or the fact that a supplied canvas_id went unused because nothing was staged.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_data_for_range`: The site and parameter combination has no data in the requested date range. `invalid_date_range`: endDate is before startDate, or a date passes the YYYY-MM-DD shape check but is not a real calendar date. `invalid_stat_cd`: statCd is not a 5-digit NWIS statistic code. Raised before the NWIS request. `stat_cd_for_instantaneous`: statCd names a daily statistic but seriesType is \"instantaneous\", whose values carry only statistic \"00000\". Raised before the NWIS request. `method_not_found`: No series NWIS returned for this query carries the requested methodId (within the requested statCd, when one is given), or that method returned no values over the range. `invalid_request`: NWIS rejected the request. Input formats are validated against NWIS-accepted patterns before the call, so this surfaces a value that is well-formed but unacceptable upstream. `upstream_error`: NWIS returned a 5xx error, timed out, or sent a response body that is not valid WaterML-JSON (cut off mid-document), and retrying did not clear it. `canvas_not_found`: The supplied canvas_id names a canvas that never existed or has expired. Raised before the NWIS request, so no upstream call is spent on it. `canvas_capacity_exhausted`: canvas_id was omitted and a fresh canvas was needed to stage the series, but this tenant already holds the maximum number of active canvases. Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_data_for_range",
                "invalid_date_range",
                "invalid_stat_cd",
                "stat_cd_for_instantaneous",
                "method_not_found",
                "invalid_request",
                "upstream_error",
                "canvas_not_found",
                "canvas_capacity_exhausted"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "siteNumber",
        "siteName",
        "parameterCd",
        "parameterName",
        "unitCode",
        "seriesType",
        "statCd",
        "statName",
        "methodId",
        "methodDescription",
        "values",
        "totalRecords",
        "truncated",
        "otherSeries",
        "query"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Get a USGS site's current reading ranked against its full period-of-record daily-mean percentiles for the same calendar day — a "how unusual is this" percentileClass (record-high to record-low), not a flood-stage or drought determination (this tool fetches no authoritative thresholds). The reading is instantaneous but the percentiles are daily-mean, so the ranking is approximate (see historicalContext.comparisonBasis). When the record is too short to rank, returns the reading with historicalContext=null instead of an error. A reading NWIS reports as no data (a seasonal, discontinued, dry, or malfunctioning gage) returns an empty currentValue with the qualifiers naming why, and is not ranked. When the site measures the parameter with several sensors (methods), one reading is used and named by methodId/methodDescription — from the sensor its percentile series is described as when one is, otherwise the most recent across them; water_get_readings lists every method. Use water_find_sites and water_list_parameters to resolve inputs.

{
  "type": "object",
  "properties": {
    "site": {
      "type": "string",
      "pattern": "^\\d{8,15}$",
      "description": "USGS site number (8–15 digits, e.g. \"01646500\" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers."
    },
    "parameterCd": {
      "type": "string",
      "pattern": "^\\d{5}$",
      "description": "5-digit USGS parameter code (e.g. \"00060\" for discharge, \"00065\" for gage height). Use water_list_parameters to discover codes."
    }
  },
  "required": [
    "site",
    "parameterCd"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "siteNumber": {
      "type": "string",
      "description": "USGS site number (8–15 digits, e.g. \"01646500\")."
    },
    "siteName": {
      "type": "string",
      "description": "Human-readable USGS site name."
    },
    "parameterCd": {
      "type": "string",
      "description": "5-digit USGS parameter code that was queried (e.g. \"00060\")."
    },
    "parameterName": {
      "type": "string",
      "description": "Human-readable parameter name with units (e.g. \"Streamflow, ft³/s\")."
    },
    "unitCode": {
      "type": "string",
      "description": "Unit of measure for currentValue and the historical percentiles (e.g. \"ft3/s\", \"ft\")."
    },
    "methodId": {
      "description": "NWIS method ID of the sensor series the current reading comes from. When the site reports the parameter from several, a method with a measured latest reading is preferred, then one whose description a statistics series carries exactly (so reading and percentiles come from one sensor), then the most recent. Null only when NWIS returned the series with no method block.",
      "type": [
        "string",
        "null"
      ]
    },
    "methodDescription": {
      "description": "NWIS description of that method (e.g. \"From multiparameter sonde\", \"[(2)]\"). Null when NWIS leaves it blank, as it does for the default series at most single-sensor sites.",
      "type": [
        "string",
        "null"
      ]
    },
    "currentValue": {
      "type": "string",
      "description": "Most recent observed value as a string. Empty string when NWIS reported no value for the reading — qualifiers then give the reason, and historicalContext does not rank it. A method with a measured latest reading is preferred over one whose latest reading has no value."
    },
    "currentDateTime": {
      "type": "string",
      "description": "ISO 8601 date-time of the most recent observation."
    },
    "qualifiers": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A USGS data qualifier code (e.g. \"P\" = provisional)."
      },
      "description": "Data qualifier codes for the current reading. When currentValue is empty they name why NWIS has no value (e.g. \"Ssn\" seasonal, \"Dis\" discontinued, \"Dry\", \"Eqp\" equipment malfunction)."
    },
    "historicalContext": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "percentileClass": {
              "type": "string",
              "enum": [
                "record-high",
                "above-normal",
                "normal",
                "below-normal",
                "low",
                "record-low",
                "unknown"
              ],
              "description": "Classification relative to the full period-of-record: record-high (≥ p95), above-normal (p75–p95), normal (p25–p75), below-normal (p10–p25), low (p05–p10), record-low (< p05). Decided by the thresholds NWIS published: with p95 blank a value ≥ p75 is above-normal, and with p10 or p05 blank a value below p25 or p10 is below-normal or low. normal requires both p25 and p75; a value the published thresholds cannot place is unknown, as is a reading NWIS reported as no data (currentValue empty). See percentileLabel for the threshold in plain language."
            },
            "percentileLabel": {
              "type": "string",
              "description": "Plain-language threshold for percentileClass (e.g. \"25th–75th percentile\"). When the class was decided without an unpublished threshold, the label names it (e.g. \"≥ 75th percentile; 95th not published\") — the value may lie past it. An unknown class names the published thresholds either side and the blank ones between (e.g. \"25th–95th percentile; 75th not published\"), or, for a reading with no value, says so and names its qualifiers. The record-high and record-low classes mark percentile-of-record extremes (≥ p95 / < p05), not verified all-time records — this field says so where the class name does not."
            },
            "p05": {
              "description": "5th percentile value in unitCode for this calendar month+day, based on the period of record. Null if that threshold is unavailable.",
              "type": [
                "number",
                "null"
              ]
            },
            "p10": {
              "description": "10th percentile value in unitCode for this calendar month+day. Null if unavailable.",
              "type": [
                "number",
                "null"
              ]
            },
            "p25": {
              "description": "25th percentile (lower quartile) in unitCode. Null if unavailable.",
              "type": [
                "number",
                "null"
              ]
            },
            "p50": {
              "description": "Median (50th percentile) in unitCode for this calendar month+day. Null if unavailable.",
              "type": [
                "number",
                "null"
              ]
            },
            "p75": {
              "description": "75th percentile (upper quartile) in unitCode. Null if unavailable.",
              "type": [
                "number",
                "null"
              ]
            },
            "p95": {
              "description": "95th percentile value in unitCode for this calendar month+day. Null if unavailable.",
              "type": [
                "number",
                "null"
              ]
            },
            "periodOfRecord": {
              "type": "string",
              "description": "Range of years used to compute the percentile statistics (e.g. \"1930–2025\")."
            },
            "comparisonBasis": {
              "type": "string",
              "description": "Fixed disclosure that percentileClass ranks an instantaneous reading against approved daily-mean percentiles — a cross-granularity approximation, not a flood-stage or drought determination. Present whenever historicalContext is non-null."
            },
            "statSeriesId": {
              "description": "NWIS statistics time-series ID (ts_id) the percentiles were computed from. A daily-mean series ID, numbered independently of the IV methodId. Null when NWIS omits it.",
              "type": [
                "string",
                "null"
              ]
            },
            "statSeriesDescription": {
              "description": "Location description NWIS gives that statistics series (e.g. \"From multiparameter sonde\"). Null when blank.",
              "type": [
                "string",
                "null"
              ]
            },
            "methodMatched": {
              "type": "boolean",
              "description": "True when statSeriesDescription equals the reported methodDescription, which is how the percentiles are matched to the sensor that produced the reading. False when the descriptions differ but the series was still used — it is the only statistics series whose description matches once the bracketed label the statistics service appends (e.g. \"[BASE GAGE]\") is set aside, or the only statistics series at the site; note says which. The percentiles may then come from a different sensor or location than the reading."
            }
          },
          "required": [
            "percentileClass",
            "percentileLabel",
            "p05",
            "p10",
            "p25",
            "p50",
            "p75",
            "p95",
            "periodOfRecord",
            "comparisonBasis",
            "statSeriesId",
            "statSeriesDescription",
            "methodMatched"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Historical percentile context for the observation's calendar day. Non-null only when historicalContextStatus is \"available\"; see that field for why it is otherwise absent."
    },
    "historicalContextStatus": {
      "type": "string",
      "enum": [
        "available",
        "no_matching_day",
        "no_matching_method",
        "no_record",
        "unavailable"
      ],
      "description": "Why historicalContext is or is not populated. 'available': percentiles for the observation's calendar day are present. 'no_matching_day': the stat table has rows but none for that calendar day. 'no_matching_method': the stat table covers several sensor series at this site and none is identified by the reported method's description — exactly, or apart from a bracketed label — so no series is picked to rank against (note lists them). 'no_record': the stat table is empty — a new site, or a record too short to compute percentiles. 'unavailable': the statistics service call failed — a transient upstream error, not a statement about the site's record; retry shortly."
    },
    "note": {
      "description": "Informational note explaining why historicalContext is null or incomplete, that NWIS reported no value for the current reading, or which statistics series the percentiles came from when methodMatched is false. Absent when the reading is measured and ranked against a statistics series described exactly as its method.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_data_for_parameter`: NWIS returned no IV data — the site may not exist, or may not measure the requested parameter. NWIS returns the same empty response for both cases. `invalid_request`: NWIS rejected the request. Input formats are validated against NWIS-accepted patterns before the call, so this surfaces a value that is well-formed but unacceptable upstream. `upstream_error`: The NWIS IV endpoint returned a 5xx error, timed out, or sent a response body that is not valid WaterML-JSON (cut off mid-document), and retrying did not clear it. A stat-endpoint failure does not raise this — it is reported as historicalContextStatus \"unavailable\". Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_data_for_parameter",
                "invalid_request",
                "upstream_error"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "siteNumber",
        "siteName",
        "parameterCd",
        "parameterName",
        "unitCode",
        "methodId",
        "methodDescription",
        "currentValue",
        "currentDateTime",
        "qualifiers",
        "historicalContext",
        "historicalContextStatus"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Run a read-only SQL SELECT against water data tables staged on a DataCanvas by water_get_series or water_find_sites. Workflow: run water_get_series or water_find_sites (get canvas_id + table_name) → water_dataframe_describe (confirm the table and its columns) → water_dataframe_query (SQL analysis). Only SELECT statements are permitted. At most 10,000 rows are returned; a query matching more is capped and the response sets truncated=true — scope with WHERE/LIMIT, and use SELECT COUNT(*) or water_dataframe_describe to learn the true match count. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas holding the data."
    },
    "sql": {
      "type": "string",
      "description": "Read-only SELECT statement. Reference the table by the table_name from water_get_series or water_find_sites; columns vary by source table, so run water_dataframe_describe first for the exact schema. Example: SELECT date_time, value FROM water_series_01646500_00060 ORDER BY date_time DESC LIMIT 10"
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": {},
        "description": "A result row whose keys are the selected column names and values are the corresponding cell values."
      },
      "description": "Result rows returned (up to 10,000). Column names match the SELECT clause."
    },
    "row_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Number of rows returned in the rows array (up to the 10,000-row cap), not the total matched by the query. When truncated is true the cap was reached, so row_count equals the returned count and undercounts the true total. To get the true match count run SELECT COUNT(*) with the same filter, or call water_dataframe_describe for the full row count of the staged table; page large results with LIMIT/OFFSET."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when the query matched more rows than the 10,000-row cap and the result was capped — rows and row_count then cover only the first 10,000 matches, and the rest are not in this response. False means rows and row_count are the complete result for this query. When true, narrow the query with WHERE, page with LIMIT/OFFSET, or run SELECT COUNT(*) with the same filter for the true total."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this server instance. `canvas_not_found`: The canvas_id does not exist or has expired. `table_not_found`: The SQL names a table that is not staged on this canvas — it may have expired, or was never created. `system_catalog_access`: The SQL reads a database system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*) instead of a staged table. `invalid_sql`: The SQL is not a read-only SELECT, contains disallowed functions, is syntactically invalid, or failed on the staged data (a cast or conversion the engine could not apply). Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled",
                "canvas_not_found",
                "table_not_found",
                "system_catalog_access",
                "invalid_sql"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "rows",
        "row_count",
        "truncated"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List tables and columns staged on a DataCanvas by water_get_series or water_find_sites. Call this after water_get_series or water_find_sites returns a canvas_id to discover the exact table name and column types before writing a query. Then pass the table name to water_dataframe_query. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas to describe."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table or view name — use as the FROM target in SQL."
          },
          "kind": {
            "type": "string",
            "enum": [
              "table",
              "view"
            ],
            "description": "Whether this is a base table or a SQL view."
          },
          "row_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Approximate row count for this table (DuckDB estimate; may differ from exact count)."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "DuckDB column type (e.g. VARCHAR, DOUBLE)."
                },
                "nullable": {
                  "type": "boolean",
                  "description": "True if the column allows NULL values."
                }
              },
              "required": [
                "name",
                "type",
                "nullable"
              ],
              "additionalProperties": false,
              "description": "A column in this table."
            },
            "description": "Column schema for this table."
          }
        },
        "required": [
          "name",
          "kind",
          "row_count",
          "columns"
        ],
        "additionalProperties": false,
        "description": "A staged canvas table or view."
      },
      "description": "Tables and views on this canvas."
    },
    "canvas_id": {
      "type": "string",
      "description": "The canvas ID that was described — pass to water_dataframe_query."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: DataCanvas is not enabled on this server instance. `canvas_not_found`: The canvas_id does not exist or has expired. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_disabled",
                "canvas_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "tables",
        "canvas_id"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}