usgs-water-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id'], '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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['tables', 'canvas_id']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_disabled', 'canvas_not_found'], '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'tables': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'kind', 'row_count', 'columns'], 'properties': {'kind': {'enum': ['table', 'view'], 'type': 'string', 'description': 'Whether this is a base table or a SQL view.'}, 'name': {'type': 'string', 'description': 'Table or view name â\x80\x94 use as the FROM target in SQL.'}, 'columns': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'type', 'nullable'], '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.'}}, 'description': 'A column in this table.', 'additionalProperties': False}, 'description': 'Column schema for this table.'}, 'row_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Approximate row count for this table (DuckDB estimate; may differ from exact count).'}}, 'description': 'A staged canvas table or view.', 'additionalProperties': False}, 'description': 'Tables and views on this canvas.'}, 'canvas_id': {'type': 'string', 'description': 'The canvas ID that was described â\x80\x94 pass to water_dataframe_query.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id', 'sql'], 'properties': {'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'}, '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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['rows', 'row_count', 'truncated']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'properties': {}, 'description': 'A result row whose keys are the selected column names and values are the corresponding cell values.', 'additionalProperties': {}}, 'description': 'Result rows returned (up to 10,000). Column names match the SELECT clause.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_disabled', 'canvas_not_found', 'table_not_found', 'system_catalog_access', 'invalid_sql'], '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 â\x80\x94 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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'row_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -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 â\x80\x94 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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'huc': {'type': 'string', 'pattern': '^(\\d{2}|\\d{8})$', '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 â\x80\x94 supply exactly one of bbox, stateCd, countyCd, huc.'}, 'bbox': {'type': 'string', 'pattern': '^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$', '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 â\x80\x94 bbox, stateCd, countyCd, and huc are mutually exclusive with each other, and exactly one must be supplied.'}, 'limit': {'type': 'integer', 'default': 500, 'maximum': 500, 'minimum': 1, 'description': 'Maximum sites to return inline, 1â\x80\x93500. Default 500 (the inline cap).'}, 'offset': {'type': 'integer', 'default': 0, 'maximum': 9007199254740991, 'minimum': 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.'}, 'stateCd': {'type': 'string', 'pattern': '^[A-Za-z]{2}$', 'description': '2-character US state abbreviation (e.g. "VA", "WA"). Returns all sites in the state for the given filters. Major filter â\x80\x94 supply exactly one of bbox, stateCd, countyCd, huc.'}, 'countyCd': {'type': 'string', 'pattern': '^\\d{5}(,\\d{5}){0,19}$', 'description': 'FIPS county code(s) as bare 5-digit numbers â\x80\x94 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 â\x80\x94 supply exactly one of bbox, stateCd, countyCd, huc.'}, 'siteType': {'type': 'string', '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").'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', '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.'}, 'siteOutput': {'enum': ['basic', 'expanded'], 'type': 'string', 'default': 'basic', 'description': '"basic" returns core identification fields. "expanded" adds drainage area, altitude, contributing area, and other metadata.'}, 'parameterCd': {'type': 'string', 'pattern': '^\\d{5}(,\\d{5})*$', '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").'}, 'hasDataTypeCd': {'type': 'string', 'description': 'Require sites with data of this type. Common values: "iv" (real-time/instantaneous), "dv" (daily values), "gw" (groundwater). Comma-separate multiple types.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['sites', 'total', 'truncated', 'upstreamTotal', 'filters']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_sites_found', 'missing_major_filter', 'conflicting_major_filters', 'invalid_request', 'upstream_error', 'canvas_not_found', 'canvas_capacity_exhausted'], '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 â\x80\x94 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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'sites': {'type': 'array', 'items': {'type': 'object', 'required': ['siteNumber', 'siteName', 'siteType', 'latitude', 'longitude'], 'properties': {'hucCd': {'type': 'string', '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 â\x80\x94 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.'}, 'stateCd': {'type': 'string', 'description': '2-digit FIPS state code (e.g. "51" for Virginia). Populated only when siteOutput="expanded"; absent in basic mode.'}, 'altitude': {'type': 'number', '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.'}, 'countyCd': {'type': 'string', 'description': '3-digit FIPS county code within the state (zero-padded, e.g. "013"). Populated only when siteOutput="expanded"; absent in basic mode.'}, 'latitude': {'type': 'number', 'description': 'Decimal latitude in WGS 84.'}, '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).'}, 'longitude': {'type': 'number', 'description': 'Decimal longitude in WGS 84.'}, 'siteNumber': {'type': 'string', 'description': 'USGS site number (8â\x80\x9315 digits). Used by all other water tools.'}, 'drainageArea': {'type': 'number', 'description': 'Total drainage area in square miles. Populated only when siteOutput="expanded"; absent in basic mode.'}, 'contributingArea': {'type': 'number', 'description': 'Contributing drainage area in square miles (may differ from drainageArea for regulated basins). Populated only when siteOutput="expanded"; absent in basic mode.'}}, 'description': 'A USGS monitoring site with location, type, and available data.', 'additionalProperties': False}, 'description': 'The requested window of matching USGS monitoring sites â\x80\x94 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', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Number of sites returned inline in this response â\x80\x94 at most limit, and 0 when offset is at or past upstreamTotal.'}, 'notice': {'type': 'string', '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.'}, 'filters': {'type': 'object', 'required': ['siteOutput'], 'properties': {'huc': {'type': 'string', 'description': 'HUC watershed filter applied, if any.'}, 'bbox': {'type': 'string', 'description': 'Bounding box filter applied, if any.'}, 'stateCd': {'type': 'string', 'description': 'State filter applied, if any.'}, 'countyCd': {'type': 'string', 'description': 'County FIPS filter applied, if any.'}, 'siteType': {'type': 'string', 'description': 'Site type filter applied, if any.'}, 'siteOutput': {'enum': ['basic', 'expanded'], 'type': 'string', 'description': 'Site output mode used (basic or expanded).'}, 'parameterCd': {'type': 'string', 'description': 'Parameter code filter applied, if any.'}, 'hasDataTypeCd': {'type': 'string', 'description': 'Data type filter applied, if any.'}}, 'description': 'Filters applied to this query.', 'additionalProperties': False}, 'canvas_id': {'type': 'string', '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.'}, 'truncated': {'type': 'boolean', 'description': 'True when matches remain after the returned window (offset + total < upstreamTotal) â\x80\x94 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.'}, 'table_name': {'type': 'string', '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.'}, 'upstreamTotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['site', 'parameterCd'], 'properties': {'site': {'type': 'string', 'pattern': '^\\d{8,15}$', 'description': 'USGS site number (8â\x80\x9315 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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['siteNumber', 'siteName', 'parameterCd', 'parameterName', 'unitCode', 'methodId', 'methodDescription', 'currentValue', 'currentDateTime', 'qualifiers', 'historicalContext', 'historicalContextStatus']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'note': {'type': 'string', '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.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_data_for_parameter', 'invalid_request', 'upstream_error'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_data_for_parameter`: NWIS returned no IV data â\x80\x94 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 â\x80\x94 it is reported as historicalContextStatus "unavailable". Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'methodId': {'type': ['string', 'null'], '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.'}, 'siteName': {'type': 'string', 'description': 'Human-readable USGS site name.'}, 'unitCode': {'type': 'string', 'description': 'Unit of measure for currentValue and the historical percentiles (e.g. "ft3/s", "ft").'}, '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).'}, 'siteNumber': {'type': 'string', 'description': 'USGS site number (8â\x80\x9315 digits, e.g. "01646500").'}, 'parameterCd': {'type': 'string', 'description': '5-digit USGS parameter code that was queried (e.g. "00060").'}, 'currentValue': {'type': 'string', 'description': 'Most recent observed value as a string. Empty string when NWIS reported no value for the reading â\x80\x94 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.'}, 'parameterName': {'type': 'string', 'description': 'Human-readable parameter name with units (e.g. "Streamflow, ft³/s").'}, 'currentDateTime': {'type': 'string', 'description': 'ISO 8601 date-time of the most recent observation.'}, 'historicalContext': {'anyOf': [{'type': 'object', 'required': ['percentileClass', 'percentileLabel', 'p05', 'p10', 'p25', 'p50', 'p75', 'p95', 'periodOfRecord', 'comparisonBasis', 'statSeriesId', 'statSeriesDescription', 'methodMatched'], 'properties': {'p05': {'type': ['number', 'null'], 'description': '5th percentile value in unitCode for this calendar month+day, based on the period of record. Null if that threshold is unavailable.'}, 'p10': {'type': ['number', 'null'], 'description': '10th percentile value in unitCode for this calendar month+day. Null if unavailable.'}, 'p25': {'type': ['number', 'null'], 'description': '25th percentile (lower quartile) in unitCode. Null if unavailable.'}, 'p50': {'type': ['number', 'null'], 'description': 'Median (50th percentile) in unitCode for this calendar month+day. Null if unavailable.'}, 'p75': {'type': ['number', 'null'], 'description': '75th percentile (upper quartile) in unitCode. Null if unavailable.'}, 'p95': {'type': ['number', 'null'], 'description': '95th percentile value in unitCode for this calendar month+day. Null if unavailable.'}, 'statSeriesId': {'type': ['string', 'null'], '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.'}, '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 â\x80\x94 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.'}, 'periodOfRecord': {'type': 'string', 'description': 'Range of years used to compute the percentile statistics (e.g. "1930â\x80\x932025").'}, 'comparisonBasis': {'type': 'string', 'description': 'Fixed disclosure that percentileClass ranks an instantaneous reading against approved daily-mean percentiles â\x80\x94 a cross-granularity approximation, not a flood-stage or drought determination. Present whenever historicalContext is non-null.'}, 'percentileClass': {'enum': ['record-high', 'above-normal', 'normal', 'below-normal', 'low', 'record-low', 'unknown'], 'type': 'string', 'description': 'Classification relative to the full period-of-record: record-high (â\x89¥ p95), above-normal (p75â\x80\x93p95), normal (p25â\x80\x93p75), below-normal (p10â\x80\x93p25), low (p05â\x80\x93p10), record-low (< p05). Decided by the thresholds NWIS published: with p95 blank a value â\x89¥ 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â\x80\x9375th percentile"). When the class was decided without an unpublished threshold, the label names it (e.g. "â\x89¥ 75th percentile; 95th not published") â\x80\x94 the value may lie past it. An unknown class names the published thresholds either side and the blank ones between (e.g. "25thâ\x80\x9395th 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 (â\x89¥ p95 / < p05), not verified all-time records â\x80\x94 this field says so where the class name does not.'}, 'statSeriesDescription': {'type': ['string', 'null'], 'description': 'Location description NWIS gives that statistics series (e.g. "From multiparameter sonde"). Null when blank.'}}, '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.'}, 'methodDescription': {'type': ['string', 'null'], '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.'}, 'historicalContextStatus': {'enum': ['available', 'no_matching_day', 'no_matching_method', 'no_record', 'unavailable'], 'type': 'string', '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 â\x80\x94 exactly, or apart from a bracketed label â\x80\x94 so no series is picked to rank against (note lists them). 'no_record': the stat table is empty â\x80\x94 a new site, or a record too short to compute percentiles. 'unavailable': the statistics service call failed â\x80\x94 a transient upstream error, not a statement about the site's record; retry shortly."}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['sites'], 'properties': {'sites': {'type': 'array', 'items': {'type': 'string', 'pattern': '^\\d{8,15}$', 'description': 'A USGS site number (8â\x80\x9315 digits, e.g. "01646500").'}, 'maxItems': 100, 'minItems': 1, 'description': 'One or more USGS site numbers to query. Maximum 100 per call.'}, 'period': {'type': 'string', 'default': 'PT2H', 'pattern': '^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$', '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 â\x80\x94 use water_get_series to retrieve a full series.'}, 'parameterCd': {'type': 'array', 'items': {'type': 'string', 'pattern': '^\\d{5}$', 'description': 'A 5-digit USGS parameter code (e.g. "00060" for discharge).'}, 'description': 'Parameter codes to return. Omit to get every parameter each site publishes â\x80\x94 one series per site, parameter, and method, so a large batch can exceed the 100-series cap. Use water_list_parameters to discover codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['readings', 'total', 'totalSeries', 'truncated', 'missingSites', 'query']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_data_for_parameter', 'invalid_request', 'upstream_error'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_data_for_parameter`: NWIS returned no time series â\x80\x94 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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'query': {'type': 'object', 'required': ['sites', 'period'], 'properties': {'sites': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Site numbers queried.'}, 'period': {'type': 'string', 'description': 'Lookback period applied (ISO 8601 duration).'}, 'parameterCd': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Parameter codes requested, if filtered.'}}, 'description': 'Query parameters used for this request.', 'additionalProperties': False}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Number of site + parameter + method time series returned in readings (at most 100).'}, 'readings': {'type': 'array', 'items': {'type': 'object', 'required': ['siteNumber', 'siteName', 'parameterCd', 'parameterName', 'unitCode', 'methodId', 'methodDescription', 'values', 'totalValues'], 'properties': {'values': {'type': 'array', 'items': {'type': 'object', 'required': ['dateTime', 'value', 'qualifiers'], 'properties': {'value': {'type': 'string', 'description': 'Measured value as a string. Empty string when NWIS reported no value for that interval â\x80\x94 qualifiers then give the reason (e.g. "Ssn" seasonal, "Dis" discontinued, "Dry", "Eqp" equipment malfunction).'}, 'dateTime': {'type': 'string', 'description': 'ISO 8601 date-time of this observation.'}, '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.'}}, 'description': 'A single instantaneous reading for this site and parameter.', 'additionalProperties': False}, '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.'}, 'methodId': {'type': ['string', 'null'], 'description': 'NWIS method ID of this series. A site can measure one parameter with several sensors or at several locations â\x80\x94 each is its own method and its own entry in readings. Null only when NWIS returned the series with no method block.'}, 'siteName': {'type': 'string', 'description': 'Human-readable USGS site name (e.g. "POTOMAC RIVER AT LITTLE FALLS, MD").'}, 'unitCode': {'type': 'string', 'description': 'Unit of measure for the values in this series (e.g. "ft3/s", "ft", "°C").'}, 'siteNumber': {'type': 'string', 'description': 'USGS site number (8â\x80\x9315 digits, e.g. "01646500").'}, 'parameterCd': {'type': 'string', 'description': '5-digit parameter code (e.g. "00060" for discharge).'}, 'totalValues': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -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.'}, 'parameterName': {'type': 'string', 'description': 'Human-readable parameter name with units (e.g. "Streamflow, ft³/s").'}, 'methodDescription': {'type': ['string', 'null'], '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.'}}, 'description': 'Time series result for one site + parameter + method combination.', 'additionalProperties': False}, '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 â\x80\x94 every site's first series, then every site's second â\x80\x94 with a site's series carrying values ahead of its empty ones, a series whose every record is no data counting as empty."}, 'truncated': {'type': 'boolean', 'description': 'True when either cap applied. The series cap: totalSeries > total â\x80\x94 pass parameterCd or split the sites across calls. The 10-record cap: some readings[].totalValues > values.length â\x80\x94 use water_get_series for the full series.'}, 'totalSeries': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Number of site + parameter + method time series before the 100-series cap â\x80\x94 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.'}, '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 â\x80\x94 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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['site', 'parameterCd', 'startDate', 'endDate'], 'properties': {'site': {'type': 'string', 'pattern': '^\\d{8,15}$', 'description': 'USGS site number (8â\x80\x9315 digits, e.g. "01646500" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers.'}, 'statCd': {'type': 'string', '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 â\x80\x94 instantaneous values carry just "00000".'}, 'endDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': 'End date in YYYY-MM-DD format (e.g. "2024-12-31").'}, 'methodId': {'type': 'string', 'description': 'NWIS method ID of the sensor series to return â\x80\x94 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.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', '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.'}, 'startDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$', 'description': 'Start date in YYYY-MM-DD format (e.g. "2024-01-01").'}, 'seriesType': {'enum': ['daily', 'instantaneous'], 'type': 'string', '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.'}, '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 â\x80\x94 this tool returns one series. Use water_list_parameters to discover available codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['siteNumber', 'siteName', 'parameterCd', 'parameterName', 'unitCode', 'seriesType', 'statCd', 'statName', 'methodId', 'methodDescription', 'values', 'totalRecords', 'truncated', 'otherSeries', 'query']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', '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'], '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.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'query': {'type': 'object', 'required': ['site', 'parameterCd', 'startDate', 'endDate', 'seriesType'], 'properties': {'site': {'type': 'string', 'description': 'Site number queried.'}, 'statCd': {'type': 'string', 'description': 'Statistic code requested, if any.'}, 'endDate': {'type': 'string', 'description': 'End date applied (YYYY-MM-DD).'}, 'methodId': {'type': 'string', 'description': 'Method ID requested, if any.'}, 'startDate': {'type': 'string', 'description': 'Start date applied (YYYY-MM-DD).'}, 'seriesType': {'enum': ['daily', 'instantaneous'], 'type': 'string', 'description': 'Series type used.'}, 'parameterCd': {'type': 'string', 'description': 'Parameter code queried.'}}, 'description': 'Query parameters used for this request.', 'additionalProperties': False}, 'notice': {'type': 'string', '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.'}, 'statCd': {'type': 'string', 'description': 'NWIS statistic code of the returned series: "00003" daily mean, "00001" daily maximum, "00002" daily minimum, "00000" for instantaneous values.'}, 'values': {'type': 'array', 'items': {'type': 'object', 'required': ['dateTime', 'value', 'qualifiers'], 'properties': {'value': {'type': 'string', 'description': 'Measured value as a string. Empty string when NWIS reported no value for that interval â\x80\x94 qualifiers then give the reason (e.g. "Ssn" seasonal, "Dis" discontinued, "Dry", "Eqp" equipment malfunction). A staged canvas table holds NULL for these.'}, 'dateTime': {'type': 'string', 'description': 'ISO 8601 date or date-time of this observation.'}, '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.'}}, 'description': 'A single value record with date-time, value, and qualifiers.', 'additionalProperties': False}, 'description': 'Time-ordered value records, oldest first within the slice. Holds every record when truncated is false; when truncated, the most recent records only â\x80\x94 the last 500 without DataCanvas, or the last N that fit the inline preview budget when the full series is staged on a canvas.'}, 'methodId': {'type': ['string', 'null'], '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.'}, 'siteName': {'type': 'string', 'description': 'Human-readable USGS site name.'}, 'statName': {'type': ['string', 'null'], 'description': 'Statistic name NWIS attaches to statCd (e.g. "Mean", "Maximum"). Null when NWIS gives none, as for instantaneous values.'}, 'unitCode': {'type': 'string', 'description': 'Unit of measure for all values in this series (e.g. "ft3/s", "ft").'}, 'canvas_id': {'type': 'string', '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.'}, '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.'}, 'seriesType': {'enum': ['daily', 'instantaneous'], 'type': 'string', 'description': '"daily" = one value per day (DV service); "instantaneous" = ~15-minute readings (IV service).'}, 'siteNumber': {'type': 'string', 'description': 'USGS site number (8â\x80\x9315 digits, e.g. "01646500").'}, 'table_name': {'type': 'string', '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.'}, 'otherSeries': {'type': 'array', 'items': {'type': 'object', 'required': ['statCd', 'statName', 'methodId', 'methodDescription', 'recordCount'], 'properties': {'statCd': {'type': 'string', 'description': 'NWIS statistic code of this series (e.g. "00001").'}, 'methodId': {'type': ['string', 'null'], 'description': 'NWIS method ID of this series â\x80\x94 pass as the methodId input.'}, 'statName': {'type': ['string', 'null'], 'description': 'Statistic name for statCd (e.g. "Maximum"); null when NWIS gives none.'}, 'recordCount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Number of value records this series holds over the requested range.'}, 'methodDescription': {'type': ['string', 'null'], 'description': 'NWIS description of the method; null when blank.'}}, 'description': 'One series NWIS returned for this query that was not selected.', 'additionalProperties': False}, 'description': 'Every other statistic Ã\x97 method series NWIS returned for this query â\x80\x94 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.'}, 'parameterCd': {'type': 'string', 'description': '5-digit USGS parameter code (e.g. "00060" for discharge).'}, 'totalRecords': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'Total number of records in the upstream result set (before any truncation).'}, 'parameterName': {'type': 'string', 'description': 'Human-readable parameter name with units (e.g. "Streamflow, ft³/s").'}, 'methodDescription': {'type': ['string', 'null'], '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.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'group': {'enum': ['streamflow', 'groundwater', 'temperature', 'meteorological', 'water-quality', 'all'], 'type': 'string', '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 â\x80\x94 leave it "all" when passing query.'}, 'query': {'type': 'string', 'maxLength': 200, '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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['parameters', 'total', 'truncated']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'note': {'type': 'string', 'description': 'Guidance when a query matched nothing or was truncated. Absent otherwise.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['query_with_group', 'upstream_error'], '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 â\x80\x94 the request failed, timed out, or returned something other than a catalog page. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'query': {'type': 'string', 'description': 'The catalog query searched, trimmed. Absent when listing the curated codes.'}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -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 â\x80\x94 add words to narrow it.'}, 'parameters': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name', 'unit', 'source'], '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': {'enum': ['streamflow', 'groundwater', 'temperature', 'meteorological', 'water-quality'], 'type': 'string', 'description': 'Thematic domain of a curated entry. Absent on usgs-catalog entries.'}, 'source': {'enum': ['curated', 'usgs-catalog'], 'type': 'string', 'description': '"curated": one of the well-known codes this server lists by default. "usgs-catalog": a record from the full USGS parameter-code catalog.'}, 'description': {'type': 'string', 'description': 'USGS catalog description, naming the medium, fraction, and method (e.g. "Turbidity, water, unfiltered, â\x80¦ formazin nephelometric units (FNU)"). Present on usgs-catalog entries only.'}}, 'description': 'A USGS parameter code entry.', 'additionalProperties': False}, '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 â\x80\x94 at most 25.'}}, 'additionalProperties': False}