usaspending-mcp-server

Disaster and Emergency Spending

usaspending_disaster_spending

Read-onlyIdempotent

Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.) broken down by agency, CFDA assistance program, recipient, or geography. Use the dimension parameter to select the breakdown axis: overview (top-level totals), agency, cfda, recipient, or geography. Filter by DEF codes (Disaster/Emergency Funding codes) to isolate a specific emergency appropriation. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	Page number (1-based)
`limit`	No	Maximum results per page (1–100). Applies to the agency, cfda, recipient, and geography dimensions; geography pages through its areas ranked by aggregated_amount, highest first. Ignored for overview.
`filters`	No	Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)
`dimension`	Yes	Breakdown axis: overview (top-level totals and DEF code funding), agency (by awarding agency), cfda (by assistance program), recipient (by recipient), geography (by state/county)
`spending_type`	No	Data type for the agency dimension: award (award-level obligations and outlays) or total (includes direct non-award spending, plus total budgetary resources). Ignored for cfda, recipient, and overview, which report award-level amounts either way; the geography dimension is not user-controllable and always reports obligation-based amounts.	award

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	recipient: the result-set ceiling the upstream applied. geography: the page size (limit).
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of results returned on this page.
`notice`	No	recipient: why the total is a cap and how to bring the set under it. geography: how many areas rank below this page and how to reach them.
`totals`	No	Totals across every matching row, as reported upstream — not a sum of this page. Present for the agency, cfda, and recipient dimensions; the members depend on dimension and spending_type. Absent for overview and geography.
`results`	No	Breakdown results (empty for overview dimension)
`overview`	No	Top-level overview totals (dimension=overview only)
`dimension`	No	Breakdown dimension returned
`truncated`	No	recipient: true when the upstream capped the reachable result set rather than counting it. geography: true when more areas rank below this page.
`totalCount`	No	Total items for paginated dimensions (when available)
`current_page`	No	Current page (non-overview dimensions)
`has_next_page`	No	Whether there are more pages
`page_metadata`	No	Pagination metadata (non-overview dimensions)
`spending_type`	No	Data type returned — award/total for agency; the requested value echoed for cfda and recipient, whose amounts do not vary with it; obligation for geography; spending for overview
`applied_dimension`	No	Breakdown dimension applied
`truncationCeiling`	No	geography: the lowest aggregated_amount on this page — no area on a later page has a higher one.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 13, 2026

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

changedInput schema / properties / limit / description

Previous value: -"Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated."New value: +"Maximum results per page (1–100). Applies to the agency, cfda, recipient, and geography dimensions; geography pages through its areas ranked by aggregated_amount, highest first. Ignored for overview."

changedOutput schema / properties / cap / description

Previous value: -"The result-set ceiling the upstream applied."New value: +"recipient: the result-set ceiling the upstream applied. geography: the page size (limit)."

changedOutput schema / properties / notice / description

Previous value: -"Caveat explaining a capped total and how to bring the set under the cap."New value: +"recipient: why the total is a cap and how to bring the set under it. geography: how many areas rank below this page and how to reach them."

changedOutput schema / properties / results / items / properties / display_name / description

Previous value: -"Geographic display name (geography dimension)"New value: +"Geographic display name (geography dimension); absent on the unattributed row"

changedOutput schema / properties / results / items / properties / shape_code / description

Previous value: -"Geographic code (geography dimension)"New value: +"Geographic code (geography dimension). Absent on the unattributed row: spending with no recorded place of performance, which still ranks and counts as an area."

changedOutput schema / properties / truncated / description

Previous value: -"True when the upstream capped the reachable result set rather than counting it."New value: +"recipient: true when the upstream capped the reachable result set rather than counting it. geography: true when more areas rank below this page."

addedOutput schema / properties / truncationCeiling

Added value: +{
+  "description": "geography: the lowest aggregated_amount on this page — no area on a later page has a higher one.",
+  "type": "number"
+}

Changed5 schema fields changedSep 25, 2026

changedInput schema / properties / spending_type / description

Previous value: -"Data type for the agency and recipient dimensions: award (award-level obligations and outlays) or total (includes direct non-award spending). Ignored for cfda and overview; the geography dimension is not user-controllable and always reports obligation-based amounts."New value: +"Data type for the agency dimension: award (award-level obligations and outlays) or total (includes direct non-award spending, plus total budgetary resources). Ignored for cfda, recipient, and overview, which report award-level amounts either way; the geography dimension is not user-controllable and always reports obligation-based amounts."

changedOutput schema / properties / results / items / properties / id / description

Previous value: -"Item ID"New value: +"Item ID. On the recipient dimension, a recipient hash ID for usaspending_get_recipient — the recipient-level (-R) ID when the recipient has several."

addedOutput schema / properties / results / items / properties / total_budgetary_resources

Added value: +{
+  "description": "Total budgetary resources in USD for this row (agency dimension with spending_type total)",
+  "type": "number"
+}

changedOutput schema / properties / spending_type / description

Previous value: -"Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview"New value: +"Data type returned — award/total for agency; the requested value echoed for cfda and recipient, whose amounts do not vary with it; obligation for geography; spending for overview"

addedOutput schema / properties / totals

Added value: +{
+  "additionalProperties": false,
+  "description": "Totals across every matching row, as reported upstream — not a sum of this page. Present for the agency, cfda, and recipient dimensions; the members depend on dimension and spending_type. Absent for overview and geography.",
+  "properties": {
+    "award_count": {
+      "description": "Number of awards across the result set (award-level breakdowns)",
+      "type": "number"
+    },
+    "obligation": {
+      "description": "Obligations in USD across the whole matching result set",
+      "type": "number"
+    },
+    "outlay": {
+      "description": "Outlays in USD across the whole matching result set",
+      "type": "number"
+    },
+    "total_budgetary_resources": {
+      "description": "Total budgetary resources in USD across the result set (agency dimension with spending_type total)",
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

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": [
+      "dimension",
+      "spending_type",
+      "results",
+      "applied_dimension"
+    ]
+  },
+  {
+    "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: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "api_unavailable",
+            "api_timeout"
+          ],
+          "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: -[
-  "dimension",
-  "spending_type",
-  "results",
-  "applied_dimension"
-]

Changed4 schema fields changedJul 27, 2026

addedOutput schema / properties / cap

Added value: +{
+  "description": "The result-set ceiling the upstream applied.",
+  "type": "number"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Caveat explaining a capped total and how to bring the set under the cap.",
+  "type": "string"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of results returned on this page.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the upstream capped the reachable result set rather than counting it.",
+  "type": "boolean"
+}

Changed6 schema fields changedJul 17, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum results per page (1–100, not used for overview dimension)"New value: +"Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated."

changedInput schema / properties / spending_type / description

Previous value: -"Data type: award (award-level obligations and outlays) or total (includes direct non-award spending). Applies to agency and recipient dimensions only."New value: +"Data type for the agency and recipient dimensions: award (award-level obligations and outlays) or total (includes direct non-award spending). Ignored for cfda and overview; the geography dimension is not user-controllable and always reports obligation-based amounts."

changedOutput schema / properties / results / items / properties / aggregated_amount / description

Previous value: -"Aggregated amount in USD (geography dimension)"New value: +"Obligation-based spending amount in USD (geography dimension)"

addedOutput schema / properties / results / items / properties / per_capita

Added value: +{
+  "description": "Obligation-based spending per capita in USD (geography dimension)",
+  "type": "number"
+}

addedOutput schema / properties / results / items / properties / population

Added value: +{
+  "description": "Population of the geographic area (geography dimension)",
+  "type": "number"
+}

changedOutput schema / properties / spending_type / description

Previous value: -"Data type returned (award or total)"New value: +"Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview"

Changed2 schema fields changedJun 12, 2026

removedOutput schema / properties / result_total

Removed value: -{
-  "description": "Total items for paginated dimensions (when available)",
-  "type": "number"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total items for paginated dimensions (when available)",
+  "type": "number"
+}

Changed2 schema fields changedJun 4, 2026

changedInput schema / properties / filters / description

Previous value: -"Optional filters — def_codes narrows to a specific emergency appropriation"New value: +"Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)"

changedInput schema / properties / filters / properties / def_codes / description

Previous value: -"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Omit to include all emergency funding."New value: +"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Required for all dimensions except overview — the upstream API returns HTTP 422 when omitted for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."

Changed5 schema fields changedMay 30, 2026

addedOutput schema / properties / applied_dimension

Added value: +{
+  "description": "Breakdown dimension applied",
+  "type": "string"
+}

addedOutput schema / properties / current_page

Added value: +{
+  "description": "Current page (non-overview dimensions)",
+  "type": "number"
+}

addedOutput schema / properties / has_next_page

Added value: +{
+  "description": "Whether there are more pages",
+  "type": "boolean"
+}

addedOutput schema / properties / result_total

Added value: +{
+  "description": "Total items for paginated dimensions (when available)",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "dimension",
-  "spending_type",
-  "results"
-]New value: +[
+  "dimension",
+  "spending_type",
+  "results",
+  "applied_dimension"
+]

First observedMay 29, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, openWorldHint). The description goes beyond them by disclosing that def_codes is required for non-overview dimensions and that the upstream API returns HTTP 422 when omitted, plus where DEF codes can be discovered (get_award account_obligations_by_defc, get_agency def_codes).

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?

Three front-loaded sentences with no filler; the dimension-selection guidance comes before the DEF-code mechanics. It is dense but every sentence carries actionable information, with only minor redundancy between the description and the schema's def_codes note.

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?

An output schema exists, so return values need not be explained. The description covers axis selection, the required-filter rule, and the geographic constraint, which is everything needed to invoke this five-parameter tool correctly.

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 already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: the five dimension values are explained in prose, def_codes is tied to a concrete source field in sibling tools, and the DEF-code example for COVID-19 aids selection.

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 names a specific verb and resource ('Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.)') and enumerates the breakdown axes. It is clearly distinguishable from siblings like usaspending_spending_by_category and usaspending_spending_by_geography because it is scoped to DEF-code disaster funding.

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?

It states how to pick a breakdown ('Use the dimension parameter to select the breakdown axis') and when DEF codes are needed to isolate an emergency appropriation. It stops short of explicitly naming an alternative tool to use instead when the caller does not want disaster-scoped spending.

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

All usaspending-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.