usaspending-mcp-server

Get Agency Overview

usaspending_get_agency

Read-onlyIdempotent

Fetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year with reported budget data), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdown with obligation and transaction counts for the same fiscal year as the budget totals (the current fiscal year when no budget year is available within 5 seconds); sub_agency_fiscal_year names the year it covers. Accepts exactly one directory toptier_code (e.g., 097 for DoD, 1601 for Labor; one/two-digit numeric inputs are zero-padded to three digits) or an agency_slug (e.g., department-of-defense) — both appear in usaspending_list_agencies results and award search results. When the budget or sub-agency request fails, the overview is still returned and unavailable_sections names each missing section with its reason.

Input Schema

Name	Required	Description
`page`	No	Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.
`agency_slug`	No	URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both.
`toptier_code`	No	Directory toptier agency code (e.g., 097, 012, 1601) from usaspending_list_agencies. One/two-digit numeric values are padded to three digits (80 becomes 080); three/four-digit codes are preserved. Use either toptier_code or agency_slug, not both.

Output Schema

Name	Required	Description
`name`	No	Agency full name
`error`	No	Present when the call failed. Absent on success.
`notice`	No	How to page for more sub-agencies when the breakdown is truncated, and which sections failed to load and whether a retry may recover them. Absent when neither applies.
`mission`	No	Agency mission statement
`website`	No	Agency website URL
`agency_id`	No	Internal agency ID
`def_codes`	No	Disaster/Emergency Funding (DEF) codes applicable to this agency
`fiscal_year`	No	Fiscal year the budgetary totals below reflect: the most recent year with reported budget data, which can trail the current fiscal year (a new year has no amounts until the agency first reports in it)
`abbreviation`	No	Agency abbreviation
`sub_agencies`	No	Sub-agency breakdown within this toptier agency (one page)
`toptier_code`	No	Directory toptier agency code, which can have three or four digits
`outlay_amount`	No	Total outlays in USD for the fiscal year
`sub_agency_page`	No	Current sub-agency page returned. Absent when the sub-agency request failed.
`obligated_amount`	No	Total amount obligated in USD for the fiscal year
`sub_agency_total`	No	Total sub-agencies across all pages (when available)
`subtier_agency_count`	No	Number of sub-agencies within this toptier agency
`unavailable_sections`	No	Sections omitted because their request failed while the agency overview loaded. Absent when every section loaded.
`has_more_sub_agencies`	No	Whether more sub-agency pages are available. Absent when the sub-agency request failed, since pagination is then unknown.
`sub_agency_fiscal_year`	No	Fiscal year the sub-agency breakdown covers, as upstream reports it: the same year as fiscal_year, or the current fiscal year when no budget year was available within 5 seconds — so it can differ from fiscal_year even when both are present. Absent when the sub-agency request failed, or when upstream reports no year for a breakdown requested without one.
`sub_agency_page_metadata`	No	Pagination metadata for the sub-agency breakdown
`budgetary_resources_amount`	No	Total budgetary resources in USD for the fiscal year

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 3, 2026

changedInput schema / properties / toptier_code / description

Previous value: -"3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both."New value: +"Directory toptier agency code (e.g., 097, 012, 1601) from usaspending_list_agencies. One/two-digit numeric values are padded to three digits (80 becomes 080); three/four-digit codes are preserved. Use either toptier_code or agency_slug, not both."

changedOutput schema / properties / toptier_code / description

Previous value: -"3-digit toptier agency code"New value: +"Directory toptier agency code, which can have three or four digits"

Changed9 schema fields changedOct 13, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "sub_agency_page",
-      "has_more_sub_agencies"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    }
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `agency_not_found`: No agency found for the given toptier_code or agency_slug. `missing_input`: Neither toptier_code nor agency_slug was provided. `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: `agency_not_found`: No agency found for the given toptier_code or agency_slug. `missing_input`: Neither toptier_code nor agency_slug was provided. `conflicting_input`: Both toptier_code and agency_slug were provided. `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: -[
-  "agency_not_found",
-  "missing_input",
-  "api_unavailable",
-  "api_timeout"
-]New value: +[
+  "agency_not_found",
+  "missing_input",
+  "conflicting_input",
+  "api_unavailable",
+  "api_timeout"
+]

changedOutput schema / properties / fiscal_year / description

Previous value: -"Fiscal year the budgetary totals below reflect (most recent available)"New value: +"Fiscal year the budgetary totals below reflect: the most recent year with reported budget data, which can trail the current fiscal year (a new year has no amounts until the agency first reports in it)"

changedOutput schema / properties / has_more_sub_agencies / description

Previous value: -"Whether more sub-agency pages are available"New value: +"Whether more sub-agency pages are available. Absent when the sub-agency request failed, since pagination is then unknown."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown."New value: +"How to page for more sub-agencies when the breakdown is truncated, and which sections failed to load and whether a retry may recover them. Absent when neither applies."

addedOutput schema / properties / sub_agency_fiscal_year

Added value: +{
+  "description": "Fiscal year the sub-agency breakdown covers, as upstream reports it: the same year as fiscal_year, or the current fiscal year when no budget year was available within 5 seconds — so it can differ from fiscal_year even when both are present. Absent when the sub-agency request failed, or when upstream reports no year for a breakdown requested without one.",
+  "type": "number"
+}

changedOutput schema / properties / sub_agency_page / description

Previous value: -"Current sub-agency page returned"New value: +"Current sub-agency page returned. Absent when the sub-agency request failed."

addedOutput schema / properties / unavailable_sections

Added value: +{
+  "description": "Sections omitted because their request failed while the agency overview loaded. Absent when every section loaded.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A section omitted from the result because its request failed",
+    "properties": {
+      "message": {
+        "description": "The failure message for this section.",
+        "type": "string"
+      },
+      "reason": {
+        "description": "api_unavailable: USAspending was unreachable or answered with a server error. api_timeout: no answer before the request deadline. upstream_error: USAspending rejected the request.",
+        "enum": [
+          "api_unavailable",
+          "api_timeout",
+          "upstream_error"
+        ],
+        "type": "string"
+      },
+      "retryable": {
+        "description": "Whether retrying the call may load this section.",
+        "type": "boolean"
+      },
+      "section": {
+        "description": "budgetary_resources: fiscal_year and the budget, obligation, and outlay totals. sub_agencies: the sub-agency breakdown and its pagination.",
+        "enum": [
+          "budgetary_resources",
+          "sub_agencies"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "section",
+      "reason",
+      "retryable",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

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": [
+      "sub_agency_page",
+      "has_more_sub_agencies"
+    ]
+  },
+  {
+    "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: `agency_not_found`: No agency found for the given toptier_code or agency_slug. `missing_input`: Neither toptier_code nor agency_slug was provided. `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": [
+            "agency_not_found",
+            "missing_input",
+            "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: -[
-  "sub_agency_page",
-  "has_more_sub_agencies"
-]

Changed14 schema fields changedJul 17, 2026

addedInput schema / properties / page

Added value: +{
+  "default": 1,
+  "description": "Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

removedOutput schema / properties / budget_authority_amount

Removed value: -{
-  "description": "Total budget authority amount in USD for current fiscal year",
-  "type": "number"
-}

addedOutput schema / properties / budgetary_resources_amount

Added value: +{
+  "description": "Total budgetary resources in USD for the fiscal year",
+  "type": "number"
+}

addedOutput schema / properties / fiscal_year

Added value: +{
+  "description": "Fiscal year the budgetary totals below reflect (most recent available)",
+  "type": "number"
+}

addedOutput schema / properties / has_more_sub_agencies

Added value: +{
+  "description": "Whether more sub-agency pages are available",
+  "type": "boolean"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown.",
+  "type": "string"
+}

changedOutput schema / properties / obligated_amount / description

Previous value: -"Total obligated amount in USD for current fiscal year"New value: +"Total amount obligated in USD for the fiscal year"

addedOutput schema / properties / outlay_amount

Added value: +{
+  "description": "Total outlays in USD for the fiscal year",
+  "type": "number"
+}

changedOutput schema / properties / sub_agencies / description

Previous value: -"Sub-agency breakdown within this toptier agency"New value: +"Sub-agency breakdown within this toptier agency (one page)"

addedOutput schema / properties / sub_agency_page

Added value: +{
+  "description": "Current sub-agency page returned",
+  "type": "number"
+}

addedOutput schema / properties / sub_agency_page_metadata

Added value: +{
+  "additionalProperties": false,
+  "description": "Pagination metadata for the sub-agency breakdown",
+  "properties": {
+    "has_next": {
+      "description": "Whether more sub-agency pages are available",
+      "type": "boolean"
+    },
+    "limit": {
+      "description": "Sub-agencies per page",
+      "type": "number"
+    },
+    "page": {
+      "description": "Current sub-agency page number",
+      "type": "number"
+    },
+    "total": {
+      "description": "Total sub-agencies across all pages",
+      "type": "number"
+    }
+  },
+  "required": [
+    "page",
+    "has_next",
+    "limit"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / sub_agency_total

Added value: +{
+  "description": "Total sub-agencies across all pages (when available)",
+  "type": "number"
+}

removedOutput schema / properties / transactions_count

Removed value: -{
-  "description": "Total transaction count",
-  "type": "number"
-}

addedOutput schema / required

Added value: +[
+  "sub_agency_page",
+  "has_more_sub_agencies"
+]

First observedMay 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent/closed-world annotations by disclosing fallback semantics (sub-agency year defaults to the current fiscal year when no budget year is available within 5 seconds), the sub_agency_fiscal_year field that names which year is returned, and graceful degradation via unavailable_sections with per-section reasons. The 5-second timeout and partial-failure behavior are exactly the kind of operational context annotations cannot convey.

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?

Front-loads what is returned, then moves to input identification, then to failure behavior — a sensible order with no filler sentences. It is dense to the point of being a single long paragraph, and the zero-padding detail is repeated from the schema, so it is not maximally tight.

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 shape need not be explained, yet the description still explains the non-obvious pieces: which fiscal year the two sections cover and how missing sections are surfaced. For a three-parameter, read-only overview tool this leaves no operational question an agent would need answered before calling it.

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 the exactly-one-of constraint between toptier_code and agency_slug that the schema does not enforce (no oneOf/anyOf), plus a concrete zero-padding rule and real code examples. Page semantics are left entirely to the schema, keeping this just below a 5.

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?

States a specific verb and resource ('Fetch an agency's fiscal-year overview') and enumerates the contents: mission, budgetary resources, obligation/outlay totals, sub-agency count, DEF codes, and a paginated sub-agency breakdown. This is clearly distinguishable from the sibling usaspending_list_agencies, which is referenced only as a source of codes.

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?

Explains input selection ('exactly one directory toptier_code ... or an agency_slug') and points to usaspending_list_agencies and award search results as where those identifiers come from, which implicitly routes list-level discovery to the sibling. It does not explicitly say when NOT to use this tool or name an alternative for the same data, so it falls short of a 5.

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.