usaspending-mcp-server

List Federal Agencies

usaspending_list_agencies

Read-onlyIdempotent

List top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the latest reported period. Returns the full directory unless limit is supplied; optional pagination slices the provider-sorted directory. Use this as the entry point for agency navigation — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based filters on spending analysis tools.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "usaspending_list_agencies"
  }
}

Input Schema

Name	Required	Description	Default
`page`	No	Page number when limit is supplied (defaults to page 1); ignored without limit.
`sort`	No	Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount	agency_name
`limit`	No	Agencies per page; omitted returns the full directory. No maximum.
`order`	No	Sort direction: asc or desc	asc

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`total`	No	Total number of agencies in the full directory before pagination
`results`	No	List of top-tier federal agencies with budget and obligation data
`has_next`	No	Whether another page exists; present only when limit is supplied
`totalCount`	No	Total number of agencies in the full directory before pagination
`agency_count`	No	Total number of top-tier federal agencies returned

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

changedOutput schema / properties / results / items / properties / toptier_code / description

Previous value: -"Three-digit toptier agency code (e.g., 097 for DoD) — required by usaspending_get_agency"New value: +"Directory toptier agency code (e.g., 097 for DoD, 1601 for Labor); three or four digits — accepted by usaspending_get_agency and search_federal_accounts agency_identifier"

Changed11 schema fields changedOct 24, 2026

addedInput schema / properties / limit

Added value: +{
+  "description": "Agencies per page; omitted returns the full directory. No maximum.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / page

Added value: +{
+  "description": "Page number when limit is supplied (defaults to page 1); ignored without limit.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "results",
-      "total",
-      "agency_count"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results",
+      "total",
+      "agency_count",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / has_next

Added value: +{
+  "description": "Whether another page exists; present only when limit is supplied",
+  "type": "boolean"
+}

changedOutput schema / properties / results / items / properties / budget_authority_amount / description

Previous value: -"Total budget authority amount in USD for the current fiscal year"New value: +"Total budget authority amount in USD for the latest reported period"

addedOutput schema / properties / results / items / properties / fiscal_quarter

Added value: +{
+  "description": "Provider reporting fiscal quarter for the latest reported period",
+  "type": "number"
+}

addedOutput schema / properties / results / items / properties / fiscal_year

Added value: +{
+  "description": "Provider reporting fiscal year for the latest reported period",
+  "type": "number"
+}

changedOutput schema / properties / results / items / properties / obligated_amount / description

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

changedOutput schema / properties / results / items / properties / outlay_amount / description

Previous value: -"Total outlay amount in USD for the current fiscal year"New value: +"Total outlay amount in USD for the latest reported period"

changedOutput schema / properties / total / description

Previous value: -"Total number of agencies returned"New value: +"Total number of agencies in the full directory before pagination"

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total number of agencies in the full directory before pagination",
+  "type": "number"
+}

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": [
+      "results",
+      "total",
+      "agency_count"
+    ]
+  },
+  {
+    "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: -[
-  "results",
-  "total",
-  "agency_count"
-]

Changed2 schema fields changedMay 30, 2026

addedOutput schema / properties / agency_count

Added value: +{
+  "description": "Total number of top-tier federal agencies returned",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "results",
-  "total"
-]New value: +[
+  "results",
+  "total",
+  "agency_count"
+]

First observedMay 29, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already establish read-only, idempotent, closed-world behavior, so the description only needs to add operational context, and it does: full directory by default, pagination only meaningful when limit is supplied, and a provider-sorted ordering. It stops short of describing result size or whether the full directory is large enough to warrant paging, which would complete the picture.

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 compact sentences ordered by importance: what it returns, how paging behaves, then why to call it. No filler, no restatement of the title, and the routing advice lands last where it is actionable.

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 zero-required-parameter read tool with a full output schema, the description covers everything an agent needs: scope of the directory, default versus paginated behavior, and its role as a prerequisite for sibling tools. Return-value detail is correctly delegated to the output schema.

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 every parameter already documents itself, so the description is only required to avoid contradicting it. The default-behavior restatement (full directory without limit) is useful, but the phrase "provider-sorted directory" sits awkwardly against the explicit sort/order parameters and could momentarily confuse an agent about whether it controls ordering.

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 ("List top-tier federal agencies") and names exactly what the records carry: toptier codes, agency slugs, budget authority amounts, obligation totals for the latest reported period. That inventory cleanly separates it from usaspending_get_agency, which takes a single agency as input.

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?

Explicitly frames itself as "the entry point for agency navigation" and states the downstream condition — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based spending filters. An agent knows both when to call this and what to do with the output.

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.