usaspending-mcp-server

Get Award Details

usaspending_get_award

Read-onlyIdempotent

Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient identity (UEI, parent organization, business categories), agency hierarchy, period of performance, place of performance, Assistance Listings with the obligation under each, loan face value and subsidy cost for loans, funding account linkages (account_obligations_by_defc), parent IDV information, and subaward count. Use generated_internal_id values from usaspending_search_awards as input. Recipient and parent recipient hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters, and Assistance Listing numbers in its assistance_listings filter. For IDV-category awards (category="idv"), use usaspending_get_idv_awards to list the child contracts and task/delivery orders placed under them.

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": {
      "award_id": "<award_id>"
    },
    "name": "usaspending_get_award"
  }
}

Input Schema

Name	Required	Description	Default
`award_id`	Yes	Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards

Output Schema

Name	Required	Description
`fain`	No	Federal Award Identification Number (for assistance)
`piid`	No	Procurement Instrument Identifier (for contracts)
`type`	No	Award type code
`error`	No	Present when the call failed. Absent on success.
`naics`	No	NAICS code (contracts)
`category`	No	Award category: contract, idv, grant, loans, direct payment, insurance, or other
`recipient`	No	Recipient details
`date_signed`	No	Date award was signed (YYYY-MM-DD)
`description`	No	Award description
`parent_award`	No	Parent IDV information (contracts only)
`total_outlays`	No	Total outlay amount in USD
`funding_agency`	No	Funding agency hierarchy
`subaward_count`	No	Number of subawards; use with usaspending_get_award_subawards
`awarding_agency`	No	Awarding agency hierarchy
`total_loan_value`	No	Face value of the loan in USD (category "loans" only). A loan reports its value here, not in total_obligation, which is often 0.
`total_obligation`	No	Total obligation amount in USD
`type_description`	No	Human-readable award type
`total_subsidy_cost`	No	Estimated cost to the government of the loan subsidy in USD (category "loans" only)
`assistance_listings`	No	Every Assistance Listing (CFDA program) funding the award, in upstream order; absent for contracts and IDVs
`place_of_performance`	No	Place of performance; absent when upstream reports no location fields
`total_account_outlay`	No	Total federal-account outlay in USD
`period_of_performance`	No	Period of performance dates
`base_exercised_options`	No	Base and exercised options value in USD when reported for contracts or IDVs
`account_outlays_by_defc`	No	Federal-account outlays by Disaster/Emergency Funding code in upstream order
`product_or_service_code`	No	Product or service code (contracts)
`total_account_obligation`	No	Total federal-account obligation in USD
`generated_unique_award_id`	No	Generated unique award ID
`base_and_all_options_value`	No	Base and all options value in USD (contracts)
`account_obligations_by_defc`	No	Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 24, 2026

addedOutput schema / properties / account_outlays_by_defc

Added value: +{
+  "description": "Federal-account outlays by Disaster/Emergency Funding code in upstream order",
+  "items": {
+    "additionalProperties": false,
+    "description": "DEF code entry with code and outlay amount",
+    "properties": {
+      "amount": {
+        "description": "Outlay amount in USD for this DEF code",
+        "type": "number"
+      },
+      "code": {
+        "description": "DEF code identifying the emergency supplemental",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / base_exercised_options

Added value: +{
+  "description": "Base and exercised options value in USD when reported for contracts or IDVs",
+  "type": "number"
+}

addedOutput schema / properties / place_of_performance / properties / congressional_code

Added value: +{
+  "description": "Congressional district of performance, preserving leading zeros",
+  "type": "string"
+}

addedOutput schema / properties / place_of_performance / properties / county_name

Added value: +{
+  "description": "County of performance",
+  "type": "string"
+}

addedOutput schema / properties / recipient / properties / location / properties / congressional_code

Added value: +{
+  "description": "Recipient congressional district, preserving leading zeros",
+  "type": "string"
+}

addedOutput schema / properties / recipient / properties / location / properties / county_name
```
Added value: +{
+  "description": "Recipient county",
+  "type": "string"
+}
```

addedOutput schema / properties / recipient / properties / location / properties / zip5

Added value: +{
+  "description": "Recipient ZIP code, preserving leading zeros",
+  "type": "string"
+}

addedOutput schema / properties / total_account_obligation

Added value: +{
+  "description": "Total federal-account obligation in USD",
+  "type": "number"
+}

addedOutput schema / properties / total_account_outlay

Added value: +{
+  "description": "Total federal-account outlay in USD",
+  "type": "number"
+}

Changed14 schema fields changedOct 13, 2026

addedOutput schema / properties / assistance_listings

Added value: +{
+  "description": "Every Assistance Listing (CFDA program) funding the award, in upstream order; absent for contracts and IDVs",
+  "items": {
+    "additionalProperties": false,
+    "description": "One Assistance Listing funding the award",
+    "properties": {
+      "number": {
+        "description": "Assistance Listing (CFDA) number, e.g. 93.855 — usable in usaspending_search_awards assistance_listings",
+        "type": "string"
+      },
+      "obligation": {
+        "description": "Federal obligation in USD made under this listing",
+        "type": "number"
+      },
+      "title": {
+        "description": "Assistance Listing program title",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / category / description

Previous value: -"Award category (contract, grant, direct_payment, loan, idv, other)"New value: +"Award category: contract, idv, grant, loans, direct payment, insurance, or other"

removedOutput schema / properties / cfda

Removed value: -{
-  "additionalProperties": false,
-  "description": "CFDA program (grants/assistance)",
-  "properties": {
-    "number": {
-      "description": "CFDA/Assistance Listing number",
-      "type": "string"
-    },
-    "title": {
-      "description": "CFDA program title",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}

changedOutput schema / properties / place_of_performance / description

Previous value: -"Place of performance"New value: +"Place of performance; absent when upstream reports no location fields"

changedOutput schema / properties / place_of_performance / properties / country_code / description

Previous value: -"Country code of performance"New value: +"Three-letter country code of performance (e.g. USA)"

addedOutput schema / properties / recipient / properties / business_categories

Added value: +{
+  "description": "Recipient business category names (e.g. \"Higher Education\", \"U.S. Local Government\") — not the codes usaspending_get_recipient returns as business_types",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

removedOutput schema / properties / recipient / properties / business_types

Removed value: -{
-  "description": "Recipient business type codes",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

changedOutput schema / properties / recipient / properties / location / description

Previous value: -"Recipient address"New value: +"Recipient address; absent when upstream reports no location fields"

changedOutput schema / properties / recipient / properties / location / properties / country_code / description
```
Previous value: -"Recipient country code"New value: +"Recipient three-letter country code (e.g. USA)"
```

addedOutput schema / properties / recipient / properties / parent_recipient_id

Added value: +{
+  "description": "Parent recipient hash ID (ends in -P) — pass to usaspending_get_recipient for the parent organization profile",
+  "type": "string"
+}

addedOutput schema / properties / recipient / properties / parent_uei

Added value: +{
+  "description": "Parent organization Unique Entity Identifier",
+  "type": "string"
+}

changedOutput schema / properties / recipient / properties / uei / description

Previous value: -"Unique Entity Identifier"New value: +"Recipient Unique Entity Identifier"

addedOutput schema / properties / total_loan_value

Added value: +{
+  "description": "Face value of the loan in USD (category \"loans\" only). A loan reports its value here, not in total_obligation, which is often 0.",
+  "type": "number"
+}

addedOutput schema / properties / total_subsidy_cost

Added value: +{
+  "description": "Estimated cost to the government of the loan subsidy in USD (category \"loans\" only)",
+  "type": "number"
+}

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: `award_not_found`: No award exists for the given award 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": [
+            "award_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"
+}

Changed3 schema fields changedJul 27, 2026
- changedOutput schema / properties / period_of_performance / properties / end_date / description
```
Previous value: -"Performance end date"New value: +"Performance end date (YYYY-MM-DD)"
```
- changedOutput schema / properties / period_of_performance / properties / potential_end_date / description
```
Previous value: -"Potential end date including options"New value: +"Potential end date including options (YYYY-MM-DD)"
```
- changedOutput schema / properties / period_of_performance / properties / start_date / description
```
Previous value: -"Performance start date"New value: +"Performance start date (YYYY-MM-DD)"
```

Changed1 schema field changedJul 17, 2026

removedOutput schema / properties / transactions_count

Removed value: -{
-  "description": "Number of transactions; use with usaspending_get_award_transactions",
-  "type": "number"
-}

First observedMay 29, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly=true, idempotent=true, openWorld=false, so the safety profile is covered. The description adds substantive behavioral detail about scope (loan face value/subsidy, funding account linkages, subaward count) that helps an agent judge whether this call answers its question, though it says nothing about payload size or error behavior for an invalid ID.

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 input source are front-loaded, and every sentence routes the agent somewhere useful. The long enumerations of returned fields are dense but mostly earn their place, though they overlap with the existing output schema.

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 single-ID read tool with full annotation coverage and an output schema, the description covers what an agent needs: input provenance, the IDV exception, and where to send the hashes/NAICS it receives. Nothing required for correct invocation 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?

Only one parameter and schema description coverage is 100%, so the schema already explains award_id and its format. The description reinforces the provenance rule (use generated_internal_id from search_awards) but adds little beyond what the schema states, making the baseline 3 correct.

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 ('Fetch full details of a federal award by its generated unique award ID') and immediately scopes the return content. It distinguishes itself from usaspending_search_awards and explicitly carves out IDV-category awards for usaspending_get_idv_awards.

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 tells the agent to use generated_internal_id values from usaspending_search_awards as input, and gives the exact when-to-use-alternative rule: for category="idv" use usaspending_get_idv_awards. It also names downstream tools (get_recipient, search_awards) for follow-up data.

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.