usaspending-mcp-server

Get Recipient Profile

usaspending_get_recipient

Read-onlyIdempotent

Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are UUID hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Totals cover the trailing 12 months unless fiscal_year selects one fiscal year, and period names the window. For a recipient's totals by award type, use usaspending_spending_over_time with filters.recipient_id and award_type_codes. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fiscal_year`	No	Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months.
`recipient_id`	Yes	Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award

Output Schema

TableJSON Schema

Name	Required	Description
`uei`	No	Unique Entity Identifier (SAM.gov)
`duns`	No	DUNS number (legacy)
`name`	No	Recipient legal business name
`error`	No	Present when the call failed. Absent on success.
`period`	No	Window the totals cover: FY<year> when fiscal_year was given, otherwise "trailing 12 months"
`location`	No	Recipient address
`parent_uei`	No	Parent organization UEI
`parent_name`	No	Parent organization name
`recipient_id`	No	Recipient hash ID
`business_types`	No	Business type codes
`alternate_names`	No	Alternate business names
`recipient_level`	No	Hierarchy level: P = parent, C = child, R = standalone
`total_transactions`	No	Total number of award transactions over period
`total_transaction_amount`	No	Total transaction (award) amount in USD over period, across all award types
`total_face_value_loan_amount`	No	Total face value of loans in USD over period
`total_face_value_loan_transactions`	No	Number of face-value loan transactions over period

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 13, 2026

removedInput schema / properties / award_type

Removed value: -{
-  "description": "Award type category to scope award totals",
-  "enum": [
-    "contracts",
-    "grants",
-    "direct_payments",
-    "loans",
-    "other_financial_assistance"
-  ],
-  "type": "string"
-}

changedInput schema / properties / fiscal_year / description

Previous value: -"Fiscal year to scope award totals (e.g., 2024)"New value: +"Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months."

changedOutput schema / anyOf

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

addedOutput schema / properties / period

Added value: +{
+  "description": "Window the totals cover: FY<year> when fiscal_year was given, otherwise \"trailing 12 months\"",
+  "type": "string"
+}

changedOutput schema / properties / total_face_value_loan_amount / description

Previous value: -"Total face value of loans in USD"New value: +"Total face value of loans in USD over period"

changedOutput schema / properties / total_face_value_loan_transactions / description

Previous value: -"Number of face-value loan transactions"New value: +"Number of face-value loan transactions over period"

changedOutput schema / properties / total_transaction_amount / description

Previous value: -"Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided"New value: +"Total transaction (award) amount in USD over period, across all award types"

changedOutput schema / properties / total_transactions / description

Previous value: -"Total number of award transactions"New value: +"Total number of award transactions over period"

Changed5 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": [
+      "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: `recipient_not_found`: No recipient found for the given recipient ID. `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": [
+            "recipient_not_found",
+            "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"
+}

Changed9 schema fields changedJul 17, 2026

removedOutput schema / properties / business_types_description

Removed value: -{
-  "description": "Human-readable business type descriptions",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

addedOutput schema / properties / location / properties / zip

Added value: +{
+  "description": "ZIP code",
+  "type": "string"
+}

addedOutput schema / properties / location / properties / zip4

Added value: +{
+  "description": "ZIP+4 extension",
+  "type": "string"
+}

removedOutput schema / properties / location / properties / zip5

Removed value: -{
-  "description": "5-digit ZIP code",
-  "type": "string"
-}

removedOutput schema / properties / total

Removed value: -{
-  "additionalProperties": false,
-  "description": "Total award amounts by type",
-  "properties": {
-    "contracts": {
-      "description": "Total contracts amount in USD",
-      "type": "number"
-    },
-    "direct_payments": {
-      "description": "Total direct payments amount in USD",
-      "type": "number"
-    },
-    "grants": {
-      "description": "Total grants amount in USD",
-      "type": "number"
-    },
-    "loans": {
-      "description": "Total loans amount in USD",
-      "type": "number"
-    },
-    "other": {
-      "description": "Total other financial assistance amount in USD",
-      "type": "number"
-    }
-  },
-  "type": "object"
-}

addedOutput schema / properties / total_face_value_loan_amount

Added value: +{
+  "description": "Total face value of loans in USD",
+  "type": "number"
+}

addedOutput schema / properties / total_face_value_loan_transactions

Added value: +{
+  "description": "Number of face-value loan transactions",
+  "type": "number"
+}

addedOutput schema / properties / total_transaction_amount

Added value: +{
+  "description": "Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided",
+  "type": "number"
+}

addedOutput schema / properties / total_transactions

Added value: +{
+  "description": "Total number of award transactions",
+  "type": "number"
+}

First observedMay 29, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: totals default to the trailing 12 months unless fiscal_year is set, period names the window, and the UUID level-suffix semantics (-P/-C/-R) explain ID structure.

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 core purpose and return contents, then parameters, then the alternative tool. Dense but every clause carries information; the SAM.gov/SEC EDGAR note is a slight extension beyond what's needed to invoke the tool.

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?

With an output schema present, return values need not be explained, and the description still summarizes the profile contents. It covers ID provenance, defaults, and alternatives. Adequate for a single-required-param read tool, though it could say nothing is mutated by the fetch.

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% and the fiscal_year semantics are already in the schema, so the baseline would be 3. The description adds meaning beyond the schema by decoding the recipient_id level suffix (-P parent, -C child, -R standalone) and noting that UEI/DUNS values can cross-reference external sources.

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 ('Fetch') and resource ('recipient's full profile') and enumerates what the profile contains (address, business type codes, parent org, alternate names, totals). It also differentiates itself from siblings by naming usaspending_search_recipients, usaspending_get_award, and usaspending_spending_over_time.

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?

Explicitly routes the agent to usaspending_spending_over_time when the goal is totals by award type, and indicates the ID originates from search_recipients or get_award. It stops short of stating when-not to use this tool, but the alternative routing is concrete.

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.