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 hexadecimal 8-4-4-4-12 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.

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": {
      "recipient_id": "<recipient_id>"
    },
    "name": "usaspending_get_recipient"
  }
}

Input 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 hexadecimal 8-4-4-4-12 hash with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P — from usaspending_search_recipients or usaspending_get_award

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

Changed1 schema field changedNov 3, 2026

changedInput schema / properties / recipient_id / description

Previous value: -"Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award"New value: +"Recipient hexadecimal 8-4-4-4-12 hash with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P — from usaspending_search_recipients or usaspending_get_award"

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.1/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 description is not burdened with safety disclosure. It still adds real behavioral context the annotations lack: the default aggregation window (trailing 12 months) versus a fiscal-year scope, and that a period name labels the window. It does not discuss pagination or error cases, but the output schema covers return shape.

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?

Four sentences, each carrying information: contents, ID sourcing, time-window semantics, and an alternative tool. It is front-loaded with the payload description, though the ID format sentence partially duplicates the schema and could be trimmed.

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?

For a two-parameter read of a single entity with annotations and an output schema, the description supplies everything needed to call it correctly: valid ID provenance, default time window, fiscal-year override, and the sibling to use for award-type breakdowns. Only marginal items like cross-referencing semantics of UEI/DUNS remain thin.

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 description coverage is 100%, so both parameters are already documented, including the hash format and the fiscal-year example. The description restates the ID format and the trailing-12-month default rather than adding new meaning, apart from noting UEI and DUNS can be cross-referenced with SAM.gov and SEC EDGAR, which is marginal value. 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?

The description opens with a concrete verb and resource ('Fetch a recipient's full profile') and enumerates the returned contents — address, business type codes, parent organization, alternate names, total transaction and loan amounts. It is clearly distinguishable from usaspending_search_recipients (which supplies IDs) and usaspending_spending_over_time (which handles award-type breakdowns).

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?

It tells the agent where recipient IDs come from (usaspending_search_recipients or usaspending_get_award) and explicitly routes a related need — totals by award type — to usaspending_spending_over_time with the relevant filter fields. It does not state exclusions such as when to prefer usaspending_get_award instead, so it stops short of full when/when-not guidance.

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.