Skip to main content
Glama

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
award_idYesGenerated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
fainNoFederal Award Identification Number (for assistance)
piidNoProcurement Instrument Identifier (for contracts)
typeNoAward type code
errorNoPresent when the call failed. Absent on success.
naicsNoNAICS code (contracts)
categoryNoAward category: contract, idv, grant, loans, direct payment, insurance, or other
recipientNoRecipient details
date_signedNoDate award was signed (YYYY-MM-DD)
descriptionNoAward description
parent_awardNoParent IDV information (contracts only)
total_outlaysNoTotal outlay amount in USD
funding_agencyNoFunding agency hierarchy
subaward_countNoNumber of subawards; use with usaspending_get_award_subawards
awarding_agencyNoAwarding agency hierarchy
total_loan_valueNoFace value of the loan in USD (category "loans" only). A loan reports its value here, not in total_obligation, which is often 0.
total_obligationNoTotal obligation amount in USD
type_descriptionNoHuman-readable award type
total_subsidy_costNoEstimated cost to the government of the loan subsidy in USD (category "loans" only)
assistance_listingsNoEvery Assistance Listing (CFDA program) funding the award, in upstream order; absent for contracts and IDVs
place_of_performanceNoPlace of performance; absent when upstream reports no location fields
period_of_performanceNoPeriod of performance dates
product_or_service_codeNoProduct or service code (contracts)
generated_unique_award_idNoGenerated unique award ID
base_and_all_options_valueNoBase and all options value in USD (contracts)
account_obligations_by_defcNoFunding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • 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"
      +}
  2. Changed5 schema fields changed
    • 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"
      +}
  3. Changed3 schema fields changed
    • 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)"
  4. Changed1 schema field changed
    • removedOutput schema / properties / transactions_count
      Removed value: -{
      -  "description": "Number of transactions; use with usaspending_get_award_transactions",
      -  "type": "number"
      -}
  5. First observed

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety and idempotency profile is covered. The description's added behavioral content is mostly a restatement of the return payload (loan face value, subaward count, funding account linkages), which is already captured by the output schema, and it says nothing about auth requirements, rate limits, or error behavior.

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 is front-loaded in the first sentence and the routing guidance is useful and non-redundant. The middle sentence is a very long enumeration of returned fields that partly duplicates the output schema, which costs some efficiency, but the overall ordering (what it does → input source → related tools) is well structured.

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-parameter read tool with a full output schema and complete annotations, the description supplies everything an agent needs: the exact input source, the special-case branch for IDV-category awards, and the downstream tools for the IDs it returns. 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?

Schema description coverage is 100% for the single award_id parameter, including the example ID format and the generated_internal_id provenance. The description's input guidance largely repeats that schema text, so it adds little beyond the documented baseline.

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 what 'full details' means via an enumeration of the returned data. It is clearly distinguishable from siblings like usaspending_get_award_transactions or usaspending_get_award_subawards, which each return a subset.

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?

Gives an explicit input source ('Use generated_internal_id values from usaspending_search_awards'), plus concrete routing rules: recipient hashes go to usaspending_get_recipient, NAICS codes and Assistance Listing numbers back into usaspending_search_awards, and IDV-category awards must use usaspending_get_idv_awards instead. Both when-to-use and when-not-to-use are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.