usaspending-mcp-server

Get Federal Account Breakdown

usaspending_get_federal_account_breakdown

Read-onlyIdempotent

Fetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. fiscal_year scopes financial reporting periods to the full October–September year, not award action dates; omit it for all available periods. Account codes are AGENCY-MAIN format and come from usaspending_search_federal_accounts (its account_number output field), usaspending_get_award_federal_accounts (its federal_account field), or usaspending_get_federal_account. Paginated with an honest total count. For the account's own metadata and top-level totals, use usaspending_get_federal_account.

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": {
      "account_code": "<account_code>",
      "dimension": "<dimension>"
    },
    "name": "usaspending_get_federal_account_breakdown"
  }
}

Input Schema

Name	Required	Description
`page`	No	Page number (1-based)
`limit`	No	Maximum results per page (1–100)
`dimension`	Yes	Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased)
`fiscal_year`	No	Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default.
`account_code`	Yes	Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Recovery for an empty page, distinguished from a known zero total; absent when results are present.
`period`	No	FY<year> for a selected year, otherwise all available periods
`results`	No	Breakdown rows for the requested dimension
`dimension`	No	Breakdown dimension returned
`totalCount`	No	Total number of breakdown rows across all pages (when available)
`fiscal_year`	No	Fiscal year selected by the caller; omitted for all available periods
`time_period`	No	Full fiscal-year range applied to financial reporting periods, not award action dates; omitted for all available periods
`account_code`	No	Federal account code queried
`current_page`	No	Current page returned
`has_next_page`	No	Whether there are more pages of breakdown rows
`page_metadata`	No	Pagination metadata
`applied_dimension`	No	Breakdown dimension applied

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 24, 2026

addedInput schema / properties / fiscal_year

Added value: +{
+  "anyOf": [
+    {
+      "description": "Integer federal fiscal year from 2001 through the current federal fiscal year",
+      "maximum": 9007199254740991,
+      "minimum": 2001,
+      "type": "integer"
+    },
+    {
+      "description": "Blank form value; leaves the fiscal year unset",
+      "maxLength": 0,
+      "minLength": 0,
+      "type": "string"
+    }
+  ],
+  "description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "account_code",
-      "dimension",
-      "results",
-      "page_metadata",
-      "applied_dimension",
-      "current_page",
-      "has_next_page"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "period",
+      "account_code",
+      "dimension",
+      "results",
+      "page_metadata",
+      "applied_dimension",
+      "current_page",
+      "has_next_page"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / fiscal_year

Added value: +{
+  "description": "Fiscal year selected by the caller; omitted for all available periods",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedOutput schema / properties / period

Added value: +{
+  "description": "FY<year> for a selected year, otherwise all available periods",
+  "type": "string"
+}

addedOutput schema / properties / time_period

Added value: +{
+  "additionalProperties": false,
+  "description": "Full fiscal-year range applied to financial reporting periods, not award action dates; omitted for all available periods",
+  "properties": {
+    "end_date": {
+      "description": "Inclusive financial reporting period end date (YYYY-MM-DD)",
+      "type": "string"
+    },
+    "start_date": {
+      "description": "Inclusive financial reporting period start date (YYYY-MM-DD)",
+      "type": "string"
+    }
+  },
+  "required": [
+    "start_date",
+    "end_date"
+  ],
+  "type": "object"
+}

Changed1 schema field changedOct 24, 2026

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when results are empty — the account code may not exist or may have no obligations on this axis. Absent when results are present."New value: +"Recovery for an empty page, distinguished from a known zero total; absent when results are present."

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": [
+      "account_code",
+      "dimension",
+      "results",
+      "page_metadata",
+      "applied_dimension",
+      "current_page",
+      "has_next_page"
+    ]
+  },
+  {
+    "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: -[
-  "account_code",
-  "dimension",
-  "results",
-  "page_metadata",
-  "applied_dimension",
-  "current_page",
-  "has_next_page"
-]

AddedJul 17, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds behavior beyond them: pagination with a meaningful total count, and the important caveat that fiscal_year follows the October–September federal year rather than award action dates. That date-semantics warning is exactly the kind of non-obvious trait an agent cannot infer from annotations or schema.

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-loaded with the verb and resource, then prerequisites, then the sibling hand-off — no wasted sentences. Slight redundancy with the schema on the dimension axis keeps it from being 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?

With an output schema, full annotation coverage, and complete parameter documentation, the description supplies everything else an agent needs: axis choice, fiscal-year semantics, code format and origin, pagination, and the alternative tool. Nothing material is missing.

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; the description earns more by explaining that fiscal_year is a reporting period (Oct–Sep) distinct from award action dates and by stating the AGENCY-MAIN format and provenance of account_code. The dimension explanation largely restates the enum documentation, so it stops short of 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?

Specific verb+resource: fetches a federal account's obligations broken down by program activity or object class, with both axes named. It explicitly distinguishes itself from usaspending_get_federal_account (metadata and top-level totals) and implies its difference from category/geography spending tools by scoping to a single account.

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

Usage Guidelines5/5

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

States when to use each axis, when to omit fiscal_year, and names the exact sibling to use instead for account metadata and totals. It also tells the agent where account codes must come from (search_federal_accounts account_number, get_award_federal_accounts federal_account, or get_federal_account), closing the main prerequisite gap.

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.