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, and recipient dimensions; ignored for overview and geography, which are not paginated.
`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	The result-set ceiling the upstream applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of results returned on this page.
`notice`	No	Caveat explaining a capped total and how to bring the set under the cap.
`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	True when the upstream capped the reachable result set rather than counting it.
`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

Schema Changelog

Changes observed during successful MCP inspections.

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

Behavior3/5

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

Annotations already declare readOnly, openWorld, and idempotent behavior, so the safety profile is covered. The description adds useful cross-references for where DEF codes can be found but does not mention pagination caveats or response behavior; those are at least partly covered by the schema and output schema.

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

Conciseness5/5

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

Three sentences with no filler: the first states the core action and scope, the second gives the primary usage instruction, and the third adds a useful cross-reference. Information is front-loaded and every sentence earns its place.

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

Completeness4/5

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

The description covers the central selection logic (dimension + DEF codes) and points to where DEF codes can be sourced. Pagination and dimension-specific caveats live in the schema, which is rich enough to support correct calls. A small gap is the lack of explicit guidance distinguishing this tool from sibling spending-by-category or spending-by-geography tools.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds the acronym expansion for DEF codes and a cross-reference to other tools, but largely repeats dimension options and filtering behavior already present in the schema.

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 uses a specific verb ('Fetch') and names an exact resource: disaster and emergency supplemental spending. It enumerates the breakdown axes (overview, agency, cfda, recipient, geography) and highlights the DEF-code focus, which clearly distinguishes it from sibling spending tools.

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 gives explicit operating instructions: use the dimension parameter to choose the breakdown axis and use DEF codes to isolate a specific emergency appropriation. It does not explicitly name sibling alternatives or state when not to use this tool, but the disaster/emergency scope makes the intended context clear.

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.