Server definition
- Hash
- sha256:1c24d3700fd597faf5c620944660f6b0153eac14c5dda44ac8c606f99829745b
- What it is
- What a remote MCP server returned when asked what it offers: 10 tools
The blob, as servednamed by its sha256
{
"instructions": "NOAA Climate Data Online (CDO) API v2 — historical weather observations and climate data.\nPrimary workflow: noaa_climate_find_locations → noaa_climate_find_stations → noaa_climate_fetch_data.\nDiscovery: noaa_climate_list_datasets → noaa_climate_list_data_categories → noaa_climate_list_data_types.\nLocation categories: noaa_climate_list_location_categories enumerates the 12 valid locationCategoryId values.\nDate range limits: daily datasets (GHCND etc.) max 1 year per request; monthly/annual (GSOM, GSOY) max 10 years.\nAlways pass units=metric or units=standard to noaa_climate_fetch_data — raw GHCND values are tenths-of-unit integers.\nSevere-weather events are a separate corpus: noaa_climate_search_storm_events reads the NCEI Storm Events Database (tornado, hail, flood, hurricane damage and casualties), needs no token, and requires a year.\nDisaster costs are a third corpus: noaa_climate_get_billion_dollar_disasters reads NCEI's Billion-Dollar Weather and Climate Disasters (1980 through the last fully assessed year), needs no token, and reports every cost in whole US dollars.",
"tools": [
{
"description": "Fetch historical observation records from a NOAA CDO dataset for a given date range. Requires datasetId (e.g., GHCND for daily, GSOM for monthly), startDate, and endDate. Optionally scope to specific stations, locations, and data types. Date range limits per request: sub-daily, daily, and radar datasets (GHCND, PRECIP_15, PRECIP_HLY, NORMAL_DLY, NORMAL_HLY, NEXRAD2, NEXRAD3) are limited to 1 year; monthly and annual datasets (GSOM, GSOY, NORMAL_MLY, NORMAL_ANN) are limited to 10 years. A full calendar year always fits, leap years included — the limit runs to the end of the calendar month 1 (or 10) years after startDate. For climate normals (NORMAL_*), use startDate=2010-01-01 and endDate=2010-12-31 — that is the API proxy year regardless of which 30-year period is being described. Returns flat tuples of { date, datatype, station, value, attributes }. Strongly recommended: pass units=metric or units=standard — without it, GHCND values are raw tenths-of-unit integers (TMAX=256 = 25.6°C, PRCP=12 = 1.2mm). GSOM/GSOY are already scaled.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"datasetId": {
"description": "Dataset ID to query (e.g., GHCND for daily data, GSOM for monthly, GSOY for annual, NORMAL_DLY/MLY/ANN/HLY for 1981–2010 climate normals, NEXRAD2/NEXRAD3 for weather radar). Determines date range limit: GHCND/PRECIP_*/NORMAL_DLY/NORMAL_HLY/NEXRAD2/NEXRAD3 allow 1-year max per request; GSOM/GSOY/NORMAL_MLY/NORMAL_ANN allow 10-year max.",
"minLength": 1,
"type": "string"
},
"datatypeId": {
"description": "One or more data type IDs to include (e.g., [\"TMAX\", \"TMIN\", \"PRCP\"]). Without this, all data types for the dataset are returned. Use noaa_climate_list_data_types to discover valid IDs. Optional.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"endDate": {
"description": "End date for observations (YYYY-MM-DD). Must be within 1 year of startDate for sub-daily/daily/radar datasets (GHCND, PRECIP_15, PRECIP_HLY, NORMAL_DLY, NORMAL_HLY, NEXRAD2, NEXRAD3) or within 10 years for monthly/annual datasets (GSOM, GSOY, NORMAL_MLY, NORMAL_ANN) — measured to the end of the calendar month that many years after startDate, so a full calendar year (2024-01-01 to 2024-12-31) always fits. For any NORMAL_* dataset use 2010-12-31.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"includemetadata": {
"default": true,
"description": "Include pagination metadata in the response. Defaults to true.",
"type": "boolean"
},
"limit": {
"default": 25,
"description": "Maximum number of records to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationId": {
"description": "One or more location IDs to filter by (e.g., [\"FIPS:37\", \"ZIP:98101\"]). Broader than stationId — returns data from all stations within the location. Optional.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first record to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Optional.",
"enum": [
"datatype",
"date",
"station"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"startDate": {
"description": "Start date for observations (YYYY-MM-DD). For NORMAL_* datasets use 2010-01-01 regardless of the years being analyzed — 2010 is the API proxy year for all normals.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"stationId": {
"description": "One or more station IDs to filter by (e.g., [\"GHCND:USW00024233\"]). Obtain from noaa_climate_find_stations. Multiple IDs return comparative readings across stations. Optional.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"units": {
"description": "Unit system for returned values. Without this parameter, GHCND returns raw tenths-of-unit integers (TMAX=256 = 25.6°C). Strongly recommended: pass metric (SI units) or standard (Fahrenheit/inches). Optional.",
"enum": [
"standard",
"metric"
],
"type": "string"
}
},
"required": [
"datasetId",
"startDate",
"endDate"
],
"type": "object"
},
"name": "noaa_climate_fetch_data",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount",
"effectiveQuery"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"effectiveQuery": {
"description": "Summary of the effective query: dataset, date range, units, and any station/location/datatype filters applied.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `date_range_exceeded`: endDate is past the end of the calendar month 1 year after startDate for sub-daily/daily/radar datasets (GHCND, PRECIP_*, NORMAL_DLY, NORMAL_HLY, NEXRAD2, NEXRAD3), or 10 years after it for monthly/annual datasets (GSOM, GSOY, NORMAL_MLY, NORMAL_ANN). `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: Bad dataset ID, date format, or unknown station/location/datatype ID. Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"date_range_exceeded",
"upstream_auth_failed",
"validation_error"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when includemetadata=true.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching records.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "1-based starting index of this page as returned by the NOAA CDO API.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no records were returned — echoes query parameters and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Flat array of observation records sorted by date by default.",
"items": {
"additionalProperties": false,
"description": "A single observation record.",
"properties": {
"attributes": {
"description": "Quality flags and measurement attributes. Omitted when not provided.",
"type": "string"
},
"datatype": {
"description": "Data type ID (e.g., TMAX, PRCP).",
"type": "string"
},
"date": {
"description": "Observation date-time in ISO 8601 format.",
"type": "string"
},
"station": {
"description": "Station ID that recorded this observation.",
"type": "string"
},
"value": {
"description": "Observed value. Unit depends on the dataset and units parameter. For GHCND without units, this is a raw tenths-of-unit integer.",
"type": "number"
}
},
"required": [
"date",
"datatype",
"station",
"value"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching observation records before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search for geographic locations by category (CITY, ST, CNTY, CNTRY, ZIP, CLIM_REG, etc.). Returns location IDs used in station search and data queries. Without locationCategoryId, returns all location types; noaa_climate_list_location_categories lists the valid values. Use locationCategoryId=ST to list US states (51 entries — small enough to retrieve completely). To find a location by name, pass nameContains alongside locationCategoryId — the CDO API has no name parameter, so this server enumerates the category and matches the substring itself. It works for any category under the size limit stated on nameContains, which is every category except ZIP; a datasetId or datacategoryId filter can bring a category back under that limit. For a category still too large, sort alphabetically with sortField=name and page through results. Location IDs: states as FIPS:37 (NC), cities as CITY:US530018 (Seattle), zip codes as ZIP:98101, countries as FIPS:US. Obtain location IDs here, then pass them to noaa_climate_find_stations or noaa_climate_fetch_data.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"datacategoryId": {
"description": "Filter to locations with this data category (e.g., \"TEMP\"). Optional.",
"minLength": 1,
"type": "string"
},
"datasetId": {
"description": "Filter to locations covered by this dataset (e.g., \"GHCND\"). Optional.",
"minLength": 1,
"type": "string"
},
"endDate": {
"description": "Filter to locations with data on or before this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"limit": {
"default": 25,
"description": "Maximum number of results to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationCategoryId": {
"description": "Category filter. Use ST for states (51 entries), CNTY for counties, CITY for cities (large set — thousands of entries), CNTRY for countries, ZIP for zip codes, US_TERR for US territories, CLIM_REG for NOAA climate regions, CLIM_DIV for climate divisions, HYD_ACC/HYD_CAT/HYD_REG/HYD_SUB for hydrological categories. Call noaa_climate_list_location_categories when you do not know which category to use — it returns the authoritative set. Optional — omit to return all location types.",
"minLength": 1,
"type": "string"
},
"nameContains": {
"description": "Case-insensitive substring match on the location name. The CDO API has no name parameter, so this server applies the match itself, across the whole category rather than one page — which bounds it to a category holding at most 4000 locations. Requires locationCategoryId; adding datasetId or datacategoryId narrows a category that is otherwise too large. Example: locationCategoryId=\"CITY\" with nameContains=\"seattle\". Optional.",
"minLength": 1,
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first result to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Use name with sortOrder=asc to browse alphabetically when searching for a specific city or location name. Optional.",
"enum": [
"id",
"name",
"mindate",
"maxdate",
"datacoverage"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"startDate": {
"description": "Filter to locations with data on or after this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
}
},
"type": "object"
},
"name": "noaa_climate_find_locations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"appliedNameFilter": {
"description": "The nameContains value this response was filtered by. Present only when nameContains was supplied; every count below then describes the filtered set, not the whole category.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A filter parameter is not recognized by the NOAA CDO API (e.g., unknown datacategoryId or datasetId). `name_filter_requires_category`: nameContains was supplied without a locationCategoryId to scope the enumeration. `name_filter_category_too_large`: The requested locationCategoryId holds more locations than nameContains can enumerate. Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"upstream_auth_failed",
"validation_error",
"name_filter_requires_category",
"name_filter_category_too_large"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when the API returns it.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching locations — the post-filter match count when appliedNameFilter is present.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "Starting index of this page: 1-based as returned by the NOAA CDO API, or the zero-based offset you supplied when appliedNameFilter is present.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no locations matched — echoes applied filters and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Matching locations.",
"items": {
"additionalProperties": false,
"description": "A single location entry.",
"properties": {
"datacoverage": {
"description": "Fractional data coverage (0–1). Omitted when not provided by the API.",
"type": "number"
},
"id": {
"description": "Location ID (e.g., FIPS:37, CITY:US530018, ZIP:98101).",
"type": "string"
},
"maxdate": {
"description": "Latest date data is available for this location. Omitted when not provided.",
"type": "string"
},
"mindate": {
"description": "Earliest date data is available for this location. Omitted when not provided.",
"type": "string"
},
"name": {
"description": "Human-readable location name.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching locations before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search for weather observation stations by location, bounding box, dataset, and data type. Returns station IDs, names, coordinates, elevation, and data coverage dates. Filter by locationId (e.g., \"FIPS:37\" for all NC stations), extent (lat/lon bounding box), datasetId, datatypeId, and date range. Station IDs returned here are used as stationId in noaa_climate_fetch_data. A station must have data for the dataset and date range you want — filter by datasetId and startDate/endDate to ensure compatibility. Common station ID formats: GHCND:USW00024233, COOP:010008.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"datacategoryId": {
"description": "Filter to stations with data in this category (e.g., \"TEMP\"). Optional.",
"minLength": 1,
"type": "string"
},
"datasetId": {
"description": "Filter to stations that have data in this dataset (e.g., \"GHCND\" for daily observations). Optional.",
"minLength": 1,
"type": "string"
},
"datatypeId": {
"description": "Filter to stations that record these data types (e.g., [\"TMAX\", \"TMIN\", \"PRCP\"]). Optional.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"endDate": {
"description": "Filter to stations with data on or before this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"extent": {
"description": "Bounding box filter as \"minLat,minLon,maxLat,maxLon\" (e.g., \"47.5,-122.4,47.7,-122.1\" for central Seattle). Optional.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 25,
"description": "Maximum number of results to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationId": {
"description": "Filter to stations within this location ID (e.g., \"FIPS:37\" for NC, \"CITY:US530018\" for Seattle). Obtain from noaa_climate_find_locations. Optional.",
"minLength": 1,
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first result to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Optional.",
"enum": [
"id",
"name",
"mindate",
"maxdate",
"datacoverage"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"startDate": {
"description": "Filter to stations with data on or after this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
}
},
"type": "object"
},
"name": "noaa_climate_find_stations",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A filter parameter is not recognized by the NOAA CDO API (e.g., unknown locationId or datacategoryId). Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"upstream_auth_failed",
"validation_error"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when the API returns it.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching stations.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "1-based starting index of this page as returned by the NOAA CDO API.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no stations matched — echoes applied filters and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Matching stations.",
"items": {
"additionalProperties": false,
"description": "A single station entry.",
"properties": {
"datacoverage": {
"description": "Fractional data coverage (0–1). Omitted when not provided.",
"type": "number"
},
"elevation": {
"description": "Station elevation. Unit depends on elevationUnit. Omitted when not provided.",
"type": "number"
},
"elevationUnit": {
"description": "Unit for elevation (e.g., \"Meters\"). Omitted when not provided.",
"type": "string"
},
"id": {
"description": "Station ID (e.g., GHCND:USW00024233, COOP:010008).",
"type": "string"
},
"latitude": {
"description": "Station latitude in decimal degrees. Omitted when not provided.",
"type": "number"
},
"longitude": {
"description": "Station longitude in decimal degrees. Omitted when not provided.",
"type": "number"
},
"maxdate": {
"description": "Latest date data is available at this station. Omitted when not provided.",
"type": "string"
},
"mindate": {
"description": "Earliest date data is available at this station. Omitted when not provided.",
"type": "string"
},
"name": {
"description": "Station name.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching stations before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Query NOAA/NCEI’s Billion-Dollar Weather and Climate Disasters — the curated record of US disasters whose damage passed $1 billion, with CPI-adjusted and unadjusted costs, deaths, and one of seven classes (Drought, Flooding, Freeze, Severe Storm, Tropical Cyclone, Wildfire, Winter Storm). Every cost returned is in WHOLE US DOLLARS: NCEI declares a different unit in each export — millions for the per-event file, billions for the national per-year file — and this server converts from whichever unit the file declares, echoing it back as declaredCostUnit. Default calls return individual disasters; summary=true returns per-year counts and costs by class plus an \"All Disasters\" total. Filter with startYear/endYear (a disaster overlapping either end is included), disasterType (exactly as NCEI writes it, e.g. \"Tropical Cyclone\"), minCostInUsd, and state (a two-letter US postal code). Coverage runs from 1980 to the last year NCEI has finished assessing — currently 2024, not the current calendar year — and coveredYears reports what the export holds. Under a state scope, per-event rows are national disasters that reached that state and carry the NATIONAL cost, never a state share, so summing states double-counts; per-year rows carry a binned cost range instead of a point estimate. This is a different NOAA corpus from the CDO tools and from noaa_climate_search_storm_events: no token, and the curated set of major disasters rather than every severe-weather event.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"disasterType": {
"description": "Restrict to one NCEI disaster class, written exactly as NCEI writes it. In summary mode this also drops the \"All Disasters\" total from each year, leaving only the named class. Optional.",
"enum": [
"Drought",
"Flooding",
"Freeze",
"Severe Storm",
"Tropical Cyclone",
"Wildfire",
"Winter Storm"
],
"type": "string"
},
"endYear": {
"description": "Latest year to include (1980 or later). NCEI publishes a year only once its assessment settles, so a year past coveredYears.last returns nothing rather than an error. Optional.",
"maximum": 9007199254740991,
"minimum": 1980,
"type": "integer"
},
"limit": {
"default": 50,
"description": "Maximum number of disasters or years to return (1–100). Defaults to 50.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"minCostInUsd": {
"description": "Floor on CPI-adjusted cost in whole US dollars — 1e9 is one billion. In summary mode this is compared against the year’s \"All Disasters\" total, or against the named disasterType when one is given; where only a binned range exists, the top of the bin has to clear the floor. Optional.",
"minimum": 0,
"type": "number"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first matching record to return. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"startYear": {
"description": "Earliest year to include (1980 or later). A disaster whose span reaches into the range is included even when it began earlier. Optional — omit for the whole record.",
"maximum": 9007199254740991,
"minimum": 1980,
"type": "integer"
},
"state": {
"description": "Two-letter US postal code (e.g. \"CA\", \"TX\", \"PR\") scoping the query to NCEI’s per-state export instead of the national one. Per-event rows then carry the national cost of each disaster that reached the state, not a state share; per-year rows carry a binned cost range instead of a point estimate. Optional.",
"minLength": 1,
"type": "string"
},
"summary": {
"default": false,
"description": "Return per-year counts and costs by disaster class instead of individual disasters. Defaults to false.",
"type": "boolean"
}
},
"type": "object"
},
"name": "noaa_climate_get_billion_dollar_disasters",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"mode",
"scope",
"sourceFile",
"declaredCostUnit",
"coveredYears",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that was applied. Omitted otherwise.",
"type": "number"
},
"costBasis": {
"const": "national",
"description": "Present when a state scope is queried in events mode: every cost below is the NATIONAL cost of a disaster that reached the state, not that state’s share of it, so adding states together double-counts. Omitted for the national scope and in summary mode.",
"type": "string"
},
"coveredYears": {
"additionalProperties": false,
"description": "The year span the export actually holds, read from its rows.",
"properties": {
"first": {
"description": "Earliest year present in the export.",
"type": "number"
},
"last": {
"description": "Latest year present in the export — the last year NCEI has finished assessing, which trails the current calendar year.",
"type": "number"
}
},
"required": [
"first",
"last"
],
"type": "object"
},
"declaredCostUnit": {
"description": "The cost unit this export declares in its own preamble, e.g. \"millions of dollars\". Every cost below is already in whole US dollars; this names the unit it was converted from.",
"type": "string"
},
"disasters": {
"description": "Individual disasters for the requested page. Present when mode is \"events\".",
"items": {
"additionalProperties": false,
"description": "A single billion-dollar disaster.",
"properties": {
"beginDate": {
"description": "Event start as an ISO calendar date (YYYY-MM-DD).",
"type": "string"
},
"cpiAdjustedCostInUsd": {
"description": "Damage in whole US dollars, adjusted to present-day prices. This is the figure comparable across years.",
"type": "number"
},
"deaths": {
"description": "Deaths NCEI attributes to the disaster.",
"type": "number"
},
"disasterType": {
"description": "One of NCEI’s seven disaster classes, e.g. \"Tropical Cyclone\".",
"type": "string"
},
"endDate": {
"description": "Event end as an ISO calendar date (YYYY-MM-DD).",
"type": "string"
},
"name": {
"description": "NCEI’s event name, e.g. \"Hurricane Helene (September 2024)\".",
"type": "string"
},
"unadjustedCostInUsd": {
"description": "Damage in whole US dollars of the year the disaster occurred.",
"type": "number"
}
},
"required": [
"name",
"disasterType",
"beginDate",
"endDate",
"cpiAdjustedCostInUsd",
"unadjustedCostInUsd",
"deaths"
],
"type": "object"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_state_code`: state was supplied in a form other than a two-letter US postal code. `unknown_state`: The state code is well formed but NCEI publishes no export under it. `invalid_year_range`: startYear is later than endYear, so the range can never match a record. `malformed_export`: The export downloaded but is not the expected table — no header row, no rows, missing columns, or no declared cost unit. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_state_code",
"unknown_state",
"invalid_year_range",
"malformed_export"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when offset is past the end of a non-empty match set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"mode": {
"description": "Which shape this response carries: \"events\" populates disasters, \"summary\" populates summaries.",
"enum": [
"events",
"summary"
],
"type": "string"
},
"notice": {
"description": "Guidance when nothing matched or the page ran past the end. Omitted otherwise.",
"type": "string"
},
"scope": {
"description": "\"US\" for the national record, or the two-letter state code that was requested.",
"type": "string"
},
"shown": {
"description": "Records returned on this page. Omitted otherwise.",
"type": "number"
},
"sourceFile": {
"description": "The exact NCEI export this response was read from, e.g. \"events-US.csv\".",
"type": "string"
},
"summaries": {
"description": "Per-year tallies for the requested page. Present when mode is \"summary\".",
"items": {
"additionalProperties": false,
"description": "One year of the per-year record.",
"properties": {
"byDisasterType": {
"description": "One entry per class the year’s row carries: the seven disaster classes plus the \"All Disasters\" total, or only the named class when disasterType was set.",
"items": {
"additionalProperties": false,
"description": "One disaster class’s tally within the year.",
"properties": {
"confidenceBoundsInUsd": {
"additionalProperties": false,
"description": "NCEI’s uncertainty bands around costInUsd, in whole US dollars. Published on the national export only; omitted for a state scope, which reports costRangeInUsd instead.",
"properties": {
"lower75": {
"description": "Lower bound of the 75% confidence interval, in whole US dollars.",
"type": "number"
},
"lower90": {
"description": "Lower bound of the 90% confidence interval, in whole US dollars.",
"type": "number"
},
"lower95": {
"description": "Lower bound of the 95% confidence interval, in whole US dollars.",
"type": "number"
},
"upper75": {
"description": "Upper bound of the 75% confidence interval, in whole US dollars.",
"type": "number"
},
"upper90": {
"description": "Upper bound of the 90% confidence interval, in whole US dollars.",
"type": "number"
},
"upper95": {
"description": "Upper bound of the 95% confidence interval, in whole US dollars.",
"type": "number"
}
},
"required": [
"lower75",
"upper75",
"lower90",
"upper90",
"lower95",
"upper95"
],
"type": "object"
},
"costInUsd": {
"description": "CPI-adjusted cost in whole US dollars. Omitted for a state scope, where NCEI publishes costRangeInUsd instead of a point estimate.",
"type": "number"
},
"costRangeInUsd": {
"additionalProperties": false,
"description": "The cost bin NCEI publishes for a state scope in place of a point estimate. Omitted on the national export.",
"properties": {
"high": {
"description": "Top of the bin, in whole US dollars.",
"type": "number"
},
"low": {
"description": "Bottom of the bin, in whole US dollars.",
"type": "number"
}
},
"required": [
"low",
"high"
],
"type": "object"
},
"disasterType": {
"description": "One of the seven disaster classes, or \"All Disasters\" for the year’s total.",
"type": "string"
},
"eventCount": {
"description": "Billion-dollar disasters of this class in the year.",
"type": "number"
}
},
"required": [
"disasterType",
"eventCount"
],
"type": "object"
},
"type": "array"
},
"year": {
"description": "The calendar year these tallies cover.",
"type": "number"
}
},
"required": [
"year",
"byDisasterType"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Records matching every filter across the whole export, before offset and limit.",
"type": "number"
},
"truncated": {
"description": "True when more matches exist beyond this page. Omitted otherwise.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Fetch full metadata for a single weather station by its ID (e.g., \"GHCND:USW00024233\", \"COOP:010008\"). Returns name, coordinates, elevation, and the full date range for which data is available. Use when you have a station ID from noaa_climate_find_stations and want its complete details, or to verify a station before querying data.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"stationId": {
"description": "Station ID to fetch (e.g., \"GHCND:USW00024233\", \"COOP:010008\"). Obtain from noaa_climate_find_stations.",
"minLength": 1,
"type": "string"
}
},
"required": [
"stationId"
],
"type": "object"
},
"name": "noaa_climate_get_station",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"id",
"name"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"datacoverage": {
"description": "Fractional data coverage (0–1). Omitted when not provided by the API.",
"type": "number"
},
"elevation": {
"description": "Station elevation. Unit depends on elevationUnit. Omitted when not provided.",
"type": "number"
},
"elevationUnit": {
"description": "Unit for elevation (e.g., \"Meters\"). Omitted when not provided.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `not_found`: Station ID format is valid but no station exists with that ID. `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. Other values are possible when a failure originates below the handler.",
"examples": [
"not_found",
"service_unavailable",
"rate_limited",
"upstream_auth_failed"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"id": {
"description": "Station ID.",
"type": "string"
},
"latitude": {
"description": "Station latitude in decimal degrees. Omitted when not provided by the API.",
"type": "number"
},
"longitude": {
"description": "Station longitude in decimal degrees. Omitted when not provided by the API.",
"type": "number"
},
"maxdate": {
"description": "Latest date data is available at this station (YYYY-MM-DD). Omitted when not provided.",
"type": "string"
},
"mindate": {
"description": "Earliest date data is available at this station (YYYY-MM-DD). Omitted when not provided.",
"type": "string"
},
"name": {
"description": "Station name.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "List data categories that group related data types — Temperature, Precipitation, Wind, Pressure, Sunshine, Sky cover, Weather Type, and more. Use to discover what types of measurements are available before calling noaa_climate_list_data_types. Optionally filter by dataset, location, station, or date range. There are 42 categories in total.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"datasetId": {
"description": "Filter to categories available in this dataset (e.g., \"GHCND\", \"GSOM\"). Optional.",
"minLength": 1,
"type": "string"
},
"endDate": {
"description": "Filter to categories with data on or before this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"limit": {
"default": 25,
"description": "Maximum number of results to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationId": {
"description": "Filter to categories available at this location ID. Optional.",
"minLength": 1,
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first result to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Optional.",
"enum": [
"id",
"name"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"startDate": {
"description": "Filter to categories with data on or after this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"stationId": {
"description": "Filter to categories available at this station ID. Optional.",
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"name": "noaa_climate_list_data_categories",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A filter parameter is not recognized by the NOAA CDO API (e.g., unknown datasetId). Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"upstream_auth_failed",
"validation_error"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when the API returns it.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching categories.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "1-based starting index of this page as returned by the NOAA CDO API.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no data categories matched — echoes applied filters and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Matching data categories.",
"items": {
"additionalProperties": false,
"description": "A single data category entry.",
"properties": {
"id": {
"description": "Data category ID (e.g., TEMP, PRCP, WIND).",
"type": "string"
},
"name": {
"description": "Human-readable category name.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching data categories before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List available data types (measurement labels like TMAX, TMIN, PRCP, SNOW) for a given dataset or category. Pass a datasetId to see what is measured in that dataset, or a datacategoryId (e.g., \"TEMP\") to see all temperature-related types. Hundreds of types exist across all datasets. Use this before calling noaa_climate_fetch_data when the data type IDs are unknown. Common GHCND types: TMAX (max temperature), TMIN (min temperature), PRCP (precipitation), SNOW (snowfall), SNWD (snow depth), AWND (average wind speed).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"datacategoryId": {
"description": "Filter to data types in this category (e.g., \"TEMP\" for temperature types, \"PRCP\" for precipitation). Optional.",
"minLength": 1,
"type": "string"
},
"datasetId": {
"description": "Filter to data types available in this dataset (e.g., \"GHCND\", \"GSOM\"). Optional.",
"minLength": 1,
"type": "string"
},
"endDate": {
"description": "Filter to data types with data on or before this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"limit": {
"default": 25,
"description": "Maximum number of results to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationId": {
"description": "Filter to data types available at this location ID. Optional.",
"minLength": 1,
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first result to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Optional.",
"enum": [
"id",
"name",
"mindate",
"maxdate",
"datacoverage"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"startDate": {
"description": "Filter to data types with data on or after this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"stationId": {
"description": "Filter to data types available at this station ID. Optional.",
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"name": "noaa_climate_list_data_types",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A filter parameter is not recognized by the NOAA CDO API (e.g., unknown datacategoryId or datasetId). Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"upstream_auth_failed",
"validation_error"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when the API returns it.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching data types.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "1-based starting index of this page as returned by the NOAA CDO API.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no data types matched — echoes applied filters and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Matching data types.",
"items": {
"additionalProperties": false,
"description": "A single data type entry.",
"properties": {
"datacoverage": {
"description": "Fractional data coverage (0–1). Omitted when not provided by the API.",
"type": "number"
},
"id": {
"description": "Data type ID (e.g., TMAX, TMIN, PRCP).",
"type": "string"
},
"maxdate": {
"description": "Latest date this data type is available (YYYY-MM-DD). Omitted when not provided.",
"type": "string"
},
"mindate": {
"description": "Earliest date this data type is available (YYYY-MM-DD). Omitted when not provided.",
"type": "string"
},
"name": {
"description": "Human-readable data type name.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching data types before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List available NOAA CDO datasets with their IDs, names, and temporal coverage. Returns all ~11 datasets by default (no required parameters). Optionally filter to datasets that contain a specific data type, cover a location or station, or overlap a date range. Common datasets: GHCND (daily observations, 1763–present), GSOM (monthly summaries), GSOY (annual summaries), NORMAL_DLY/MLY/ANN/HLY (1981–2010 climate normals). Use this first to discover available datasets before calling noaa_climate_fetch_data.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"datatypeId": {
"description": "Filter to datasets containing these data type IDs (e.g., [\"TMAX\", \"PRCP\"]). Optional.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"type": "array"
},
"endDate": {
"description": "Filter to datasets with data on or before this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"limit": {
"default": 25,
"description": "Maximum number of results to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"locationId": {
"description": "Filter to datasets covering this location ID (e.g., \"FIPS:37\" for NC). Optional.",
"minLength": 1,
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first result to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Optional.",
"enum": [
"id",
"name",
"mindate",
"maxdate",
"datacoverage"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"startDate": {
"description": "Filter to datasets with data on or after this ISO date (YYYY-MM-DD). Optional.",
"pattern": "^(?:\\d{4}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|\\d{4}-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\\d|3[01])(?:T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?)?)$",
"type": "string"
},
"stationId": {
"description": "Filter to datasets covering this station ID (e.g., \"GHCND:USW00024233\"). Optional.",
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"name": "noaa_climate_list_datasets",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: Bad date format or unrecognized filter ID. Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"upstream_auth_failed",
"validation_error"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when the API returns it.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching datasets.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "1-based starting index of this page as returned by the NOAA CDO API.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no datasets matched — echoes applied filters and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Matching datasets.",
"items": {
"additionalProperties": false,
"description": "A single CDO dataset entry.",
"properties": {
"datacoverage": {
"description": "Fractional data coverage (0–1). Higher is more complete.",
"type": "number"
},
"id": {
"description": "Dataset ID (e.g., GHCND, GSOM, GSOY).",
"type": "string"
},
"maxdate": {
"description": "Latest date available in the dataset (YYYY-MM-DD).",
"type": "string"
},
"mindate": {
"description": "Earliest date available in the dataset (YYYY-MM-DD).",
"type": "string"
},
"name": {
"description": "Human-readable dataset name.",
"type": "string"
}
},
"required": [
"id",
"name",
"datacoverage",
"mindate",
"maxdate"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching datasets before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List the location categories that scope noaa_climate_find_locations — CITY, CLIM_DIV, CLIM_REG, CNTRY, CNTY, HYD_ACC, HYD_CAT, HYD_REG, HYD_SUB, ST, US_TERR, and ZIP. Call this first when you do not know which locationCategoryId to pass, including the hydrological categories needed to reach a basin or region. There are 12 categories in total. This endpoint takes pagination and sort only — NOAA CDO ignores dataset, location, station, and date filters here, so none are offered.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"limit": {
"default": 25,
"description": "Maximum number of results to return (1–1000). Defaults to 25.",
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first result to return for pagination. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"sortField": {
"description": "Sort results by this field. Optional.",
"enum": [
"id",
"name"
],
"type": "string"
},
"sortOrder": {
"description": "Sort direction. Optional; defaults to asc.",
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
"type": "object"
},
"name": "noaa_climate_list_location_categories",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `service_unavailable`: NOAA CDO API is unreachable or returning errors. `rate_limited`: NOAA CDO throttled the request — the configured token went over its rate limit. `upstream_auth_failed`: NOAA CDO rejected the API token this server is configured with. `validation_error`: A pagination or sort parameter is not recognized by the NOAA CDO API. Other values are possible when a failure originates below the handler.",
"examples": [
"service_unavailable",
"rate_limited",
"upstream_auth_failed",
"validation_error"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exhausted": {
"description": "True when the requested offset is past the end of a non-empty result set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"metadata": {
"additionalProperties": false,
"description": "Pagination metadata. Present when the API returns it.",
"properties": {
"resultset": {
"additionalProperties": false,
"description": "Pagination cursor fields for this response.",
"properties": {
"count": {
"description": "Total number of matching location categories.",
"type": "number"
},
"limit": {
"description": "Page size used for this response.",
"type": "number"
},
"offset": {
"description": "1-based starting index of this page as returned by the NOAA CDO API.",
"type": "number"
}
},
"required": [
"count",
"limit",
"offset"
],
"type": "object"
}
},
"required": [
"resultset"
],
"type": "object"
},
"notice": {
"description": "Guidance when no location categories were returned. Omitted otherwise.",
"type": "string"
},
"results": {
"description": "Matching location categories.",
"items": {
"additionalProperties": false,
"description": "A single location category entry.",
"properties": {
"id": {
"description": "Location category ID, passed as locationCategoryId to noaa_climate_find_locations (e.g., CITY, ST, HYD_REG).",
"type": "string"
},
"name": {
"description": "Human-readable category name.",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of location categories before the page limit.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search the NCEI Storm Events Database for one calendar year — tornadoes, hail, floods, hurricanes, winter storms, heat, and every other NWS Storm Data event type, with magnitude, direct and indirect deaths and injuries, property and crop damage, and the episode and event narratives. This is a different NOAA corpus from the CDO tools on this server: it carries discrete severe-weather events rather than station observations, needs no token, and is published as one bulk file per year, so year is required. Filter with state (the full upper-case name NCEI writes, e.g. \"FLORIDA\" — not the postal code \"FL\"), eventType (the exact NWS label, e.g. \"Tornado\", \"Hail\", \"Flash Flood\", \"Hurricane (Typhoon)\", matched case-insensitively), month, and minDamageInUsd. Damage arrives from NCEI as a magnitude-suffixed string (\"75.00K\", \"1.20M\", \"1.00B\") and is returned as both the raw cell and a parsed dollar amount; an unreported figure is omitted entirely rather than reported as zero, and minDamageInUsd therefore excludes those rows and says how many it dropped. Results come back in the source file's own row order, paged with limit and offset, and totalCount is the true match count for the whole year.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"eventType": {
"description": "Filter to this NWS event type, matched case-insensitively against the exact label (e.g. \"Tornado\", \"Hail\", \"Flash Flood\", \"Hurricane (Typhoon)\"). A miss returns the labels present in that year. Optional.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of events to return (1–100). Defaults to 50.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"minDamageInUsd": {
"description": "Filter to events whose property damage parses to at least this many dollars. Excludes every row whose damage NCEI did not report — about a fifth of a recent year — since an unreported figure cannot be shown to clear the threshold. Optional.",
"minimum": 0,
"type": "number"
},
"month": {
"description": "Filter to events whose begin date falls in this month (1–12). Optional.",
"maximum": 12,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Zero-based index of the first matching event to return. Defaults to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"state": {
"description": "Filter to this state or territory, written as the full name NCEI uses (e.g. \"FLORIDA\", \"PUERTO RICO\"), matched case-insensitively. Postal codes like \"FL\" match nothing. Optional.",
"minLength": 1,
"type": "string"
},
"year": {
"description": "Calendar year to search (1950 through the current partial year). Required — NCEI publishes one file per year, so an unscoped search would download every year back to 1950.",
"maximum": 9007199254740991,
"minimum": 1950,
"type": "integer"
}
},
"required": [
"year"
],
"type": "object"
},
"name": "noaa_climate_search_storm_events",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"year",
"sourceFile",
"events",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that was applied. Omitted otherwise.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `year_unavailable`: The NCEI directory listing has no details file for the requested year. `service_unavailable`: The NCEI bulk file server would not hand back a usable file: the directory index is unreachable or carried no details files, the year bundle it names is gone, or the downloaded bundle did not decompress. `malformed_export`: The year decompressed but is not the expected table — required columns are missing, or the file carried no rows. Other values are possible when a failure originates below the handler.",
"examples": [
"year_unavailable",
"service_unavailable",
"malformed_export"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"events": {
"description": "Matching events for the requested page, in the source file’s own row order.",
"items": {
"additionalProperties": false,
"description": "A single storm event.",
"properties": {
"beginDateTime": {
"description": "Event start as NCEI writes it, e.g. \"30-APR-24 20:33:00\".",
"type": "string"
},
"beginLatitude": {
"description": "Latitude of the event start in decimal degrees. Omitted when absent.",
"type": "number"
},
"beginLongitude": {
"description": "Longitude of the event start in decimal degrees. Omitted when absent.",
"type": "number"
},
"countyOrZone": {
"description": "County/parish or NWS forecast zone name. Omitted when not provided.",
"type": "string"
},
"countyOrZoneType": {
"description": "Whether countyOrZone is a county (\"C\") or an NWS forecast zone (\"Z\"). Omitted when not provided.",
"type": "string"
},
"damageCrops": {
"additionalProperties": false,
"description": "Crop damage. Omitted when NCEI reported no figure.",
"properties": {
"amountInUsd": {
"description": "Dollar value parsed from raw. Omitted when the cell did not parse (the live files carry a few malformed cells such as a bare \"K\"); the raw text is still returned.",
"type": "number"
},
"raw": {
"description": "The upstream cell verbatim, e.g. \"0.00K\", \"1.20M\", \"1.00B\" — never rewritten.",
"type": "string"
}
},
"required": [
"raw"
],
"type": "object"
},
"damageProperty": {
"additionalProperties": false,
"description": "Property damage. Omitted when NCEI reported no figure.",
"properties": {
"amountInUsd": {
"description": "Dollar value parsed from raw. Omitted when the cell did not parse (the live files carry a few malformed cells such as a bare \"K\"); the raw text is still returned.",
"type": "number"
},
"raw": {
"description": "The upstream cell verbatim, e.g. \"0.00K\", \"1.20M\", \"1.00B\" — never rewritten.",
"type": "string"
}
},
"required": [
"raw"
],
"type": "object"
},
"deathsDirect": {
"description": "Deaths caused directly by the event. Omitted when not reported.",
"type": "number"
},
"deathsIndirect": {
"description": "Deaths indirectly attributed to the event. Omitted when not reported.",
"type": "number"
},
"endDateTime": {
"description": "Event end. Omitted when not provided.",
"type": "string"
},
"episodeId": {
"description": "NCEI EPISODE_ID grouping events from one storm system. Omitted for pre-1996 records, which carry no episode.",
"type": "string"
},
"episodeNarrative": {
"description": "Narrative for the whole storm episode, shared by every event in it. Omitted when absent.",
"type": "string"
},
"eventId": {
"description": "NCEI EVENT_ID — unique within the Storm Events corpus.",
"type": "string"
},
"eventNarrative": {
"description": "Narrative for this individual event. Omitted when absent.",
"type": "string"
},
"eventType": {
"description": "NWS event type label, e.g. \"Tornado\", \"Hail\".",
"type": "string"
},
"floodCause": {
"description": "Reported flood cause, e.g. \"Heavy Rain\". Omitted for non-flood events.",
"type": "string"
},
"injuriesDirect": {
"description": "Injuries caused directly by the event. Omitted when not reported.",
"type": "number"
},
"injuriesIndirect": {
"description": "Injuries indirectly attributed to the event. Omitted when not reported.",
"type": "number"
},
"magnitude": {
"description": "Wind speed in knots or hail size in inches, depending on the event type — NCEI populates it only for wind and hail events. Omitted otherwise.",
"type": "number"
},
"magnitudeType": {
"description": "How a wind magnitude was determined: \"EG\" estimated gust, \"ES\" estimated sustained, \"MG\" measured gust, \"MS\" measured sustained. Omitted for non-wind events.",
"type": "string"
},
"source": {
"description": "Who reported the event, e.g. \"ASOS\", \"Trained Spotter\". Omitted when absent.",
"type": "string"
},
"state": {
"description": "Full upper-case state or territory name, e.g. \"FLORIDA\".",
"type": "string"
},
"timezone": {
"description": "Local time zone of the date fields, e.g. \"CST-6\". Omitted when absent.",
"type": "string"
},
"torFScale": {
"description": "Tornado intensity — Enhanced Fujita (\"EF1\", or \"EFU\" when unrated) from 2007 on, original Fujita (\"F3\") before that. Omitted for non-tornado events.",
"type": "string"
},
"torLengthInMiles": {
"description": "Tornado track length in miles. Omitted for non-tornado events.",
"type": "number"
},
"torWidthInYards": {
"description": "Tornado track width in yards. Omitted for non-tornado events.",
"type": "number"
}
},
"required": [
"eventId",
"eventType",
"state",
"beginDateTime"
],
"type": "object"
},
"type": "array"
},
"excludedUnknownDamage": {
"description": "Rows that satisfied every other filter but were dropped by minDamageInUsd because NCEI reported no property-damage figure for them. Omitted when minDamageInUsd was not supplied.",
"type": "number"
},
"exhausted": {
"description": "True when offset is past the end of a non-empty match set — the page is empty but matches exist. Omitted otherwise.",
"type": "boolean"
},
"notice": {
"description": "Guidance when nothing matched or the page ran past the end. Omitted otherwise.",
"type": "string"
},
"scannedRowCount": {
"description": "Rows read from the source file, matched or not. Omitted when unavailable.",
"type": "number"
},
"shown": {
"description": "Events returned on this page. Omitted otherwise.",
"type": "number"
},
"sourceFile": {
"description": "The exact NCEI file this page was read from, including its `_c<publishDate>` suffix — the suffix changes whenever NCEI republishes a year.",
"type": "string"
},
"totalCount": {
"description": "Events matching every filter across the whole year, before offset and limit.",
"type": "number"
},
"truncated": {
"description": "True when more matches exist beyond this page. Omitted otherwise.",
"type": "boolean"
},
"year": {
"description": "The calendar year searched.",
"type": "number"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:1c24d3700fd597faf5c620944660f6b0153eac14c5dda44ac8c606f99829745b | sha256sum