usaspending-mcp-server

Disaster and Emergency Spending

usaspending_disaster_spending

Read-onlyIdempotent

Fetch disaster and emergency supplemental spending broken down by agency, CFDA assistance program, recipient, or geography, or request an overview. Filter by DEF codes to select emergency appropriations, then check amount_coverage before interpreting amounts: award breakdowns and geography cover the provider COVID grouping, while overview and agency total cover all requested codes. Rows and award counts can match codes outside the monetary scope. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "dimension": "<dimension>"
    },
    "name": "usaspending_disaster_spending"
  }
}

Input Schema

Name	Required	Description	Default
`page`	No	Page number (1-based)
`limit`	No	Maximum results per page (1–100). Breakdowns rank obligations descending before pagination; geography ranks aggregated_amount. Agency award without award_type_codes collects all provider pages before ranking, so a smaller limit does not reduce that upstream work. 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

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	Upstream messages, ignored filters, empty-page recovery, and guidance for recipient ceilings or remaining geography areas.
`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)
`applied_query`	No	Trimmed recipient query sent upstream
`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
`amount_coverage`	No	Scope of all monetary fields, including geography amounts/per-capita and totals; independent of row membership and counts
`applied_def_codes`	No	DEF codes applied (comma-separated)
`applied_dimension`	No	Breakdown dimension applied
`truncationCeiling`	No	geography: the lowest aggregated_amount on this page within amount_coverage — no area on a later page has a higher reported value.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedNov 3, 2026

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). Optional for overview totals and funding; required for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."New value: +"DEF codes, 1–3 letters or digits, sent uppercased. Optional for overview; required for breakdowns. Amount coverage is reported separately: award breakdowns and geography aggregate only the provider COVID grouping; matching rows and counts may include other codes. Overview and agency total cover all requested codes. Find codes in usaspending_get_agency def_codes fields."

addedInput schema / properties / filters / properties / def_codes / items / description
```
Added value: +"Disaster Emergency Fund Code, e.g. Z or L"
```
addedInput schema / properties / filters / properties / def_codes / items / pattern
```
Added value: +"^[0-9A-Za-z]{1,3}$"
```

changedInput schema / properties / limit / description

Previous 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."New value: +"Maximum results per page (1–100). Breakdowns rank obligations descending before pagination; geography ranks aggregated_amount. Agency award without award_type_codes collects all provider pages before ranking, so a smaller limit does not reduce that upstream work. Ignored for overview."

addedOutput schema / properties / amount_coverage

Added value: +{
+  "additionalProperties": false,
+  "description": "Scope of all monetary fields, including geography amounts/per-capita and totals; independent of row membership and counts",
+  "properties": {
+    "status": {
+      "description": "Coverage of requested DEF codes by monetary fields, not provider record completeness",
+      "enum": [
+        "complete",
+        "partial",
+        "unavailable",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "supported_def_codes": {
+      "description": "Requested codes included in amounts; omitted when unknown",
+      "items": {
+        "description": "DEF code included in amounts",
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "unsupported_def_codes": {
+      "description": "Requested codes excluded from amounts; omitted when unknown",
+      "items": {
+        "description": "DEF code excluded from amounts",
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / totals / properties / obligation / description

Previous value: -"Obligations in USD across the whole matching result set"New value: +"Obligations in USD across the matching result set, within amount_coverage"

changedOutput schema / properties / totals / properties / outlay / description

Previous value: -"Outlays in USD across the whole matching result set"New value: +"Outlays in USD across the matching result set, within amount_coverage"

changedOutput schema / properties / truncationCeiling / description

Previous value: -"geography: the lowest aggregated_amount on this page — no area on a later page has a higher one."New value: +"geography: the lowest aggregated_amount on this page within amount_coverage — no area on a later page has a higher reported value."

Changed7 schema fields changedOct 24, 2026

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). 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."New value: +"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Optional for overview totals and funding; required for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."

addedInput schema / properties / filters / properties / query

Added value: +{
+  "description": "Recipient search text, trimmed before sending. Omitted or blank means no query filter. Ignored with a notice on other dimensions.",
+  "type": "string"
+}

addedOutput schema / properties / applied_def_codes

Added value: +{
+  "description": "DEF codes applied (comma-separated)",
+  "type": "string"
+}

addedOutput schema / properties / applied_query

Added value: +{
+  "description": "Trimmed recipient query sent upstream",
+  "type": "string"
+}

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

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `missing_def_codes`: A non-overview dimension has no DEF codes. `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."

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

Previous value: -[
-  "api_unavailable",
-  "api_timeout"
-]New value: +[
+  "missing_def_codes",
+  "api_unavailable",
+  "api_timeout"
+]

changedOutput schema / properties / notice / description

Previous 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."New value: +"Upstream messages, ignored filters, empty-page recovery, and guidance for recipient ceilings or remaining geography areas."

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

A3.7/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, open-world behavior, yet the description adds genuinely non-obvious traits: award breakdowns and geography aggregate only the provider COVID grouping while overview and agency total cover all requested codes, and matching rows/counts can include codes outside the monetary scope. That is exactly the kind of caveat an agent needs before reporting numbers. It stops short of 5 because nothing is said about pagination cost or failure modes (those live only in the limit schema text).

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

Conciseness3/5

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

The purpose is front-loaded in sentence one, but the second sentence is a single overloaded clause bundling DEF code selection, amount_coverage checking, and per-dimension scope. Substantial portions of the amount-coverage explanation duplicate the def_codes schema description almost verbatim, so the text is dense and partly redundant rather than wasteful.

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?

An output schema exists, so the description needn't document return fields, and it still flags amount_coverage interpretation, which is the main interpretation hazard. Combined with the rich schema for dimension, spending_type, and limit, an agent has enough to call it correctly. The main gap is the absence of sibling routing for overlapping spending tools.

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 description coverage is 100%, so a 3 is the baseline; the description earns above that by adding DEF code discovery pointers ('usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields'), which the schema only partially mirrors. It also ties def_codes semantics to per-dimension amount coverage, giving meaning to the filter beyond its pattern/length constraints.

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

Purpose4/5

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

The first sentence gives a specific verb ('Fetch') and a specific resource ('disaster and emergency supplemental spending'), then enumerates the four breakdown axes plus the overview mode, matching the dimension enum. It is clear what the tool returns, though it does not explicitly distinguish itself from siblings like usaspending_spending_by_geography or usaspending_spending_by_category, which overlap in shape.

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

Usage Guidelines3/5

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

It gives real operational guidance — use DEF codes to select emergency appropriations, and check amount_coverage before interpreting amounts — and routes the agent to usaspending_get_agency/get_award to find DEF codes. However, it never explains when to pick this tool over the generic spending_by_category/spending_by_geography siblings, and the requirement that def_codes is mandatory for non-overview dimensions is only stated in the schema, not the description.

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.

Disaster and Emergency Spending

Tool call template

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources