noaa-climate-mcp-server

Get NOAA Billion-Dollar Disasters

noaa_climate_get_billion_dollar_disasters

Read-only

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.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum number of disasters or years to return (1–100). Defaults to 50.
`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). NCEI publishes a year only once its assessment settles, so a year past coveredYears.last returns nothing 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

TableJSON 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	Guidance when nothing matched or the page ran past the end. Omitted otherwise.
`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.

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.9/5.0

Behavior5/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses critical behavioral details: the unit conversion (whole US dollars with declaredCostUnit), the state-scope caveats (national cost not state share, double-counting risk, binned cost ranges for per-year rows), and the coverage window (1980 to assessed year, not current calendar). It even warns about overlap inclusion rules and the difference between per-event and per-year outputs.

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 a single dense paragraph but every sentence carries unique value—no filler. It front-loads the primary purpose and then layers in filtering, unit, and state-scope nuances. While it is lengthy, it is appropriately compact for the complexity (8 optional parameters, two output modes); a bulleted format would improve skimmability but is not necessary.

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?

For a tool with high complexity and subtle edge cases, the description covers all critical aspects: the two output modes (default vs summary), filtering semantics, cost unit conversion, state-scope double-counting warning, coverage years, and the distinction from other NOAA tools. It even explains the meaning of coveredYears and the binned cost range, so an agent has everything needed to call it correctly without additional probing.

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

Parameters5/5

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

Though schema coverage is 100% and the schema already provides rich parameter descriptions, the description adds essential semantics beyond the schema: the exact overlap rule for startYear/endYear, the state parameter's effect on row types and cost interpretation, the minCostInUsd behavior in summary mode (compared against 'All Disasters' or bin tops), and the 'coveredYears' reporting. This goes well beyond the baseline and significantly aids correct invocation.

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 states a specific verb ('Query') and a precise resource (NOAA/NCEI's Billion-Dollar Weather and Climate Disasters) while naming the exact content (curated disasters, cost classes, unit handling). It explicitly distinguishes itself from sibling tools by naming noaa_climate_search_storm_events and the CDO tools, so an agent can immediately tell this is a different corpus.

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

Usage Guidelines5/5

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

The description provides explicit when-to-use guidance: it contrasts itself with the CDO tools and noaa_climate_search_storm_events, explains that it covers curated major disasters rather than every severe-weather event, and details default vs summary modes. It also clarifies the coverage years and how filters behave, leaving no ambiguity about when to choose this tool.

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.