Skip to main content
Glama

usaspending-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

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 of a 3-digit toptier_code (e.g., 097 for DoD, 012 for Agriculture) 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

TableJSON Schema
NameRequiredDescriptionDefault
pageNoSub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.
agency_slugNoURL-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_codeNo3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoAgency full name
errorNoPresent when the call failed. Absent on success.
noticeNoHow 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.
missionNoAgency mission statement
websiteNoAgency website URL
agency_idNoInternal agency ID
def_codesNoDisaster/Emergency Funding (DEF) codes applicable to this agency
fiscal_yearNoFiscal 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)
abbreviationNoAgency abbreviation
sub_agenciesNoSub-agency breakdown within this toptier agency (one page)
toptier_codeNo3-digit toptier agency code
outlay_amountNoTotal outlays in USD for the fiscal year
sub_agency_pageNoCurrent sub-agency page returned. Absent when the sub-agency request failed.
obligated_amountNoTotal amount obligated in USD for the fiscal year
sub_agency_totalNoTotal sub-agencies across all pages (when available)
subtier_agency_countNoNumber of sub-agencies within this toptier agency
unavailable_sectionsNoSections omitted because their request failed while the agency overview loaded. Absent when every section loaded.
has_more_sub_agenciesNoWhether more sub-agency pages are available. Absent when the sub-agency request failed, since pagination is then unknown.
sub_agency_fiscal_yearNoFiscal 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_metadataNoPagination metadata for the sub-agency breakdown
budgetary_resources_amountNoTotal budgetary resources in USD for the fiscal year

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • 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"
+}
  2. Changed6 schema fields changed
    • 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"
-]
  3. Changed14 schema fields changed
    • 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"
+]
  4. First observed

TDQS

A4.4/5.0
Behavior5/5

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

With readOnlyHint/idempotentHint already covering the safety profile, the description adds genuinely new behavior: the budget totals come from the most recent fiscal year with reported data, the sub-agency list falls back to the current fiscal year after a 5-second timeout, and partial failures still return the overview with unavailable_sections naming what is missing. That is exactly the non-obvious runtime behavior an agent cannot infer from annotations.

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?

Purpose and return contents are front-loaded in the first sentence, and every subsequent sentence carries distinct information (year selection, identifier options, failure semantics). It is dense with nested parentheticals, which costs some readability, but nothing is padding.

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 read-only, output-schema-backed tool the description covers the remaining unknowns an agent needs: which fiscal year the numbers reflect, how paging works, which identifier forms are acceptable, and how partial failures surface. Nothing required to call it correctly is missing.

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 coverage is 100% and the schema descriptions already carry the examples (097, 012, department-of-defense), the pagination semantics, and the 'use either ... not both' rule. The description largely restates this, adding only mild emphasis that exactly one identifier is required, so baseline 3 applies.

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?

Names a specific verb (fetch) and resource (an agency's fiscal-year overview) and enumerates exactly what comes back: mission, budgetary resources, obligations, outlays, sub-agency count, DEF codes, plus a paginated sub-agency breakdown. It also distinguishes itself from usaspending_list_agencies by positioning that sibling as the source of the identifiers rather than a competitor.

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?

Gives clear invocation conditions: accepts exactly one of toptier_code or agency_slug, and tells the agent where both appear (usaspending_list_agencies results and award search results). It does not explicitly say when to prefer this over the sibling detail tools, so it stops short of full when/when-not routing.

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 toolsInspect
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.

Resources