noaa-climate-mcp-server

Get NOAA Billion-Dollar Disasters

noaa_climate_get_billion_dollar_disasters

Read-only

Query NOAA/NCEI’s retired Billion-Dollar Weather and Climate Disasters archive (1980–2024), with CPI-adjusted and unadjusted costs and deaths. No years after 2024 are added; CPI adjustments are preserved from the archive, not rebased to current prices. Every cost is in WHOLE US DOLLARS, converted from each export’s declared unit (declaredCostUnit): millions per event, billions per national year, millions per state year. Default calls return individual disasters; summary=true returns per-year counts and costs by class plus an "All Disasters" total. Filter with startYear/endYear (overlapping disasters included), disasterType (exact NCEI class, e.g. "Tropical Cyclone"), minCostInUsd, and state (two-letter postal code). coveredYears reports the span actually present in the export. Under a state scope, per-event rows carry the NATIONAL cost of disasters that reached that state, never a state share, so summing states double-counts; per-year rows carry a binned range instead of a point estimate. Separate from CDO and noaa_climate_search_storm_events; no token required.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of disasters or years to return (1–100). Defaults to 50. Larger positive integers are clamped to 100 with a notice unless NOAA_CLAMP_LIMITS=false.
`state`	No	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.
`offset`	No	Zero-based index of the first matching record to return. Defaults to 0.
`endYear`	No	Latest year to include (1980 or later). The retired archive ends in 2024; years past coveredYears.last return no records rather than an error. Optional.
`summary`	No	Return per-year counts and costs by disaster class instead of individual disasters. Defaults to false.
`startYear`	No	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.
`disasterType`	No	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.
`minCostInUsd`	No	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.

Output Schema

Name	Required	Description
`cap`	No	The limit that was applied. Omitted otherwise.
`mode`	No	Which shape this response carries: "events" populates disasters, "summary" populates summaries.
`error`	No	Present when the call failed. Absent on success.
`scope`	No	"US" for the national record, or the two-letter state code that was requested.
`shown`	No	Records returned on this page. Omitted otherwise.
`notice`	No	Archive retirement and preserved CPI-adjustment disclosure, composed with any clamp, empty-page, exhaustion, or truncation guidance.
`costBasis`	No	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.
`disasters`	No	Individual disasters for the requested page. Present when mode is "events".
`exhausted`	No	True when offset is past the end of a non-empty match set — the page is empty but matches exist. Omitted otherwise.
`summaries`	No	Per-year tallies for the requested page. Present when mode is "summary".
`truncated`	No	True when more matches exist beyond this page. Omitted otherwise.
`sourceFile`	No	The exact NCEI export this response was read from, e.g. "events-US.csv".
`totalCount`	No	Records matching every filter across the whole export, before offset and limit.
`coveredYears`	No	The year span the export actually holds, read from its rows.
`declaredCostUnit`	No	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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 23, 2026

changedInput schema / properties / endYear / description

Previous value: -"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."New value: +"Latest year to include (1980 or later). The retired archive ends in 2024; years past coveredYears.last return no records rather than an error. Optional."

changedInput schema / properties / limit / description

Previous value: -"Maximum number of disasters or years to return (1–100). Defaults to 50."New value: +"Maximum number of disasters or years to return (1–100). Defaults to 50. Larger positive integers are clamped to 100 with a notice unless NOAA_CLAMP_LIMITS=false."

changedInput schema / properties / limit / maximum

Previous value: -100New value: +9007199254740991

removedInput schema / properties / state / minLength
```
Removed value: -1
```
addedInput schema / properties / state / pattern
```
Added value: +"^\\s*[A-Za-z]{2}\\s*$"
```

changedOutput schema / properties / coveredYears / properties / last / description

Previous value: -"Latest year present in the export — the last year NCEI has finished assessing, which trails the current calendar year."New value: +"Latest year present in this archived export. The retired product covers no years after 2024."

changedOutput schema / properties / disasters / items / properties / cpiAdjustedCostInUsd / description

Previous value: -"Damage in whole US dollars, adjusted to present-day prices. This is the figure comparable across years."New value: +"Damage in whole US dollars with the CPI adjustment preserved from the archived NCEI export; not rebased to current prices."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `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."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "invalid_state_code",
-  "unknown_state",
-  "invalid_year_range",
-  "malformed_export"
-]New value: +[
+  "unknown_state",
+  "invalid_year_range",
+  "malformed_export"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched or the page ran past the end. Omitted otherwise."New value: +"Archive retirement and preserved CPI-adjustment disclosure, composed with any clamp, empty-page, exhaustion, or truncation guidance."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "mode",
+      "scope",
+      "sourceFile",
+      "declaredCostUnit",
+      "coveredYears",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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"
+}

removedOutput schema / required

Removed value: -[
-  "mode",
-  "scope",
-  "sourceFile",
-  "declaredCostUnit",
-  "coveredYears",
-  "totalCount"
-]

AddedAug 19, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral detail beyond the readOnlyHint/openWorldHint annotations: the archive is retired and ends in 2024, CPI adjustments are preserved rather than rebased, costs are converted to whole US dollars from declared units, and state-scoped rows carry national costs rather than state shares. These caveats are exactly the kind of operational context an agent needs before invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the dataset identity, time span, and unit caveats, and its sentences are generally substantive. It is dense for a single paragraph and repeats some schema-level filter details, but the complexity of the archive and state-scope caveats justify most of its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given eight parameters, full schema description coverage, an output schema, and read-only/open-world annotations, the description is complete enough for correct invocation. It covers dataset limits, default versus summary behavior, unit conversion, state-scope pitfalls, and sibling-tool separation without needing to explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter semantics: declared cost units, the fact that summing state results double-counts, how minCostInUsd behaves in summary mode, and coveredYears reporting. It does not need to re-document every parameter because the schema already does so thoroughly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a concrete verb and resource: querying NOAA/NCEI’s retired Billion-Dollar Weather and Climate Disasters archive. It clearly scopes the dataset to 1980–2024 and distinguishes the tool from CDO and noaa_climate_search_storm_events, so an agent can identify its role without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context, including default per-disaster results versus summary=true for per-year counts, and names sibling tools it is separate from. However, it does not explicitly state the conditions under which an agent should choose noaa_climate_search_storm_events or CDO instead, so the alternative routing is implied rather than fully prescribed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All noaa-climate-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.