Server definition
- Hash
- sha256:8bd729d7419cfdd71e780cf59929e8be0cb7cd60c52293c21bed636ae6d477e4
- What it is
- What a remote MCP server returned when asked what it offers: 18 tools
The blob, as servednamed by its sha256
{
"instructions": "USAspending.gov MCP server — federal award, recipient, agency, and spending data from the US Treasury DATA Act platform.\n- Start with usaspending_list_agencies or usaspending_autocomplete_filters to discover agency codes, NAICS/PSC codes, and Assistance Listing numbers\n- Use usaspending_search_awards to find awards, then usaspending_get_award for full details\n- Chain recipient_id from usaspending_get_award into usaspending_get_recipient for entity profiles\n- Search window: 2007-10-01 onward. DoD contracts have a 90-day publication lag.",
"tools": [
{
"description": "Look up valid code values for filter fields by searching free-text descriptions. Use the type parameter to select the lookup table: naics (NAICS industry codes), psc (product/service codes), cfda (CFDA/Assistance Listing program numbers), awarding_agency (agency names and IDs), or recipient (recipient names with UEI/DUNS). Call this before filtering awards when you know a description but not the exact code. Returns matching codes and names for use in other tool filters.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"limit": {
"default": 10,
"description": "Maximum number of results to return (1–500), enforced client-side. The recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x this value, so its results are capped to this limit before returning — the cap keeps them in bucket order, so name matches fill the page first and identifier matches appear only in whatever room is left. To resolve a specific UEI or DUNS, pass the identifier itself as search_text. naics/psc/cfda/awarding_agency honor this limit exactly.",
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"search_text": {
"description": "Free-text search string — use a description, keyword, or partial code to find matches",
"minLength": 1,
"type": "string"
},
"type": {
"description": "Lookup table to search: naics (industry codes), psc (product/service codes), cfda (Assistance Listing program numbers, for usaspending_search_awards assistance_listings), awarding_agency (agency names), recipient (recipient names)",
"enum": [
"naics",
"psc",
"cfda",
"awarding_agency",
"recipient"
],
"type": "string"
}
},
"required": [
"type",
"search_text"
],
"type": "object"
},
"name": "usaspending_autocomplete_filters",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"type",
"search_text",
"results",
"total",
"lookup_type",
"query",
"result_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that was applied.",
"type": "number"
},
"error": {
"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: `no_match`: No codes or names matched the search text. `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": [
"no_match",
"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"
},
"lookup_type": {
"description": "Lookup table that was searched",
"type": "string"
},
"query": {
"description": "Search text sent to the autocomplete API",
"type": "string"
},
"result_count": {
"description": "Number of matching results returned",
"type": "number"
},
"results": {
"description": "Matching codes and names",
"items": {
"additionalProperties": false,
"description": "Matched entry — code/name for code lookups, name plus optional UEI/DUNS for recipients",
"properties": {
"code": {
"description": "Code value (NAICS code, PSC code, Assistance Listing/CFDA number, or agency code); use this in filter parameters — an Assistance Listing number goes in usaspending_search_awards assistance_listings",
"type": "string"
},
"duns": {
"description": "DUNS number (legacy) — recipient type only; populated when the search text matches a DUNS",
"type": "string"
},
"id": {
"description": "Numeric or string ID (for the awarding_agency type)",
"type": "string"
},
"name": {
"description": "Human-readable name or description",
"type": "string"
},
"uei": {
"description": "Unique Entity Identifier (SAM.gov) — recipient type only; populated when the search text matches a UEI",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"search_text": {
"description": "Search text used",
"type": "string"
},
"shown": {
"description": "Number of results returned.",
"type": "number"
},
"total": {
"description": "Number of results returned",
"type": "number"
},
"truncated": {
"description": "True when results were capped at the limit.",
"type": "boolean"
},
"type": {
"description": "Lookup table searched",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.) broken down by agency, CFDA assistance program, recipient, or geography. Use the dimension parameter to select the breakdown axis: overview (top-level totals), agency, cfda, recipient, or geography. Filter by DEF codes (Disaster/Emergency Funding codes) to isolate a specific emergency appropriation. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"dimension": {
"description": "Breakdown axis: overview (top-level totals and DEF code funding), agency (by awarding agency), cfda (by assistance program), recipient (by recipient), geography (by state/county)",
"enum": [
"overview",
"agency",
"cfda",
"recipient",
"geography"
],
"type": "string"
},
"filters": {
"description": "Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)",
"properties": {
"award_type_codes": {
"description": "Award type code filters",
"items": {
"type": "string"
},
"type": "array"
},
"def_codes": {
"description": "DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Required for all dimensions except overview — the upstream API returns HTTP 422 when omitted for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields.",
"items": {
"type": "string"
},
"type": "array"
},
"geo_layer": {
"description": "Geographic layer for geography dimension (state or county)",
"enum": [
"state",
"county"
],
"type": "string"
}
},
"type": "object"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"spending_type": {
"default": "award",
"description": "Data type for the agency dimension: award (award-level obligations and outlays) or total (includes direct non-award spending, plus total budgetary resources). Ignored for cfda, recipient, and overview, which report award-level amounts either way; the geography dimension is not user-controllable and always reports obligation-based amounts.",
"enum": [
"award",
"total"
],
"type": "string"
}
},
"required": [
"dimension"
],
"type": "object"
},
"name": "usaspending_disaster_spending",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dimension",
"spending_type",
"results",
"applied_dimension"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"applied_dimension": {
"description": "Breakdown dimension applied",
"type": "string"
},
"cap": {
"description": "The result-set ceiling the upstream applied.",
"type": "number"
},
"current_page": {
"description": "Current page (non-overview dimensions)",
"type": "number"
},
"dimension": {
"description": "Breakdown dimension returned",
"type": "string"
},
"error": {
"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"
},
"has_next_page": {
"description": "Whether there are more pages",
"type": "boolean"
},
"notice": {
"description": "Caveat explaining a capped total and how to bring the set under the cap.",
"type": "string"
},
"overview": {
"additionalProperties": false,
"description": "Top-level overview totals (dimension=overview only)",
"properties": {
"award_obligations": {
"description": "Total award obligations in USD",
"type": "number"
},
"award_outlays": {
"description": "Total award outlays in USD",
"type": "number"
},
"face_value_of_loans": {
"description": "Face value of loan guarantees in USD",
"type": "number"
},
"funding_by_def_code": {
"description": "Funding amounts broken down by DEF code (emergency appropriation)",
"items": {
"additionalProperties": false,
"description": "DEF code funding entry with amount and public law reference",
"properties": {
"amount": {
"description": "Funding amount in USD for this DEF code",
"type": "number"
},
"def_code": {
"description": "DEF code",
"type": "string"
},
"label": {
"description": "DEF code label or title",
"type": "string"
},
"public_law": {
"description": "Public law number",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"total_budget_authority": {
"description": "Total budget authority in USD across all emergency supplementals",
"type": "number"
},
"total_obligations": {
"description": "Total obligations in USD",
"type": "number"
},
"total_outlays": {
"description": "Total outlays in USD",
"type": "number"
},
"unobligated_balance": {
"description": "Unobligated balance in USD",
"type": "number"
}
},
"type": "object"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata (non-overview dimensions)",
"properties": {
"has_next": {
"description": "Whether there are more pages",
"type": "boolean"
},
"limit": {
"description": "Items per page",
"type": "number"
},
"page": {
"description": "Current page",
"type": "number"
},
"total": {
"description": "Total items",
"type": "number"
}
},
"required": [
"has_next",
"page",
"limit"
],
"type": "object"
},
"results": {
"description": "Breakdown results (empty for overview dimension)",
"items": {
"additionalProperties": false,
"description": "Disaster spending breakdown entry by dimension (agency, CFDA, recipient, or geography)",
"properties": {
"aggregated_amount": {
"description": "Obligation-based spending amount in USD (geography dimension)",
"type": "number"
},
"award_count": {
"description": "Number of awards",
"type": "number"
},
"code": {
"description": "Code (agency code, CFDA number, DEF code, etc.)",
"type": "string"
},
"display_name": {
"description": "Geographic display name (geography dimension)",
"type": "string"
},
"face_value_of_loan": {
"description": "Face value of loan guarantees in USD (loans spending_type)",
"type": "number"
},
"id": {
"description": "Item ID. On the recipient dimension, a recipient hash ID for usaspending_get_recipient — the recipient-level (-R) ID when the recipient has several.",
"type": "string"
},
"name": {
"description": "Item name or description",
"type": "string"
},
"obligation": {
"description": "Obligation amount in USD",
"type": "number"
},
"outlay": {
"description": "Outlay amount in USD",
"type": "number"
},
"per_capita": {
"description": "Obligation-based spending per capita in USD (geography dimension)",
"type": "number"
},
"population": {
"description": "Population of the geographic area (geography dimension)",
"type": "number"
},
"shape_code": {
"description": "Geographic code (geography dimension)",
"type": "string"
},
"total_budgetary_resources": {
"description": "Total budgetary resources in USD for this row (agency dimension with spending_type total)",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of results returned on this page.",
"type": "number"
},
"spending_type": {
"description": "Data type returned — award/total for agency; the requested value echoed for cfda and recipient, whose amounts do not vary with it; obligation for geography; spending for overview",
"type": "string"
},
"totalCount": {
"description": "Total items for paginated dimensions (when available)",
"type": "number"
},
"totals": {
"additionalProperties": false,
"description": "Totals across every matching row, as reported upstream — not a sum of this page. Present for the agency, cfda, and recipient dimensions; the members depend on dimension and spending_type. Absent for overview and geography.",
"properties": {
"award_count": {
"description": "Number of awards across the result set (award-level breakdowns)",
"type": "number"
},
"obligation": {
"description": "Obligations in USD across the whole matching result set",
"type": "number"
},
"outlay": {
"description": "Outlays in USD across the whole matching result set",
"type": "number"
},
"total_budgetary_resources": {
"description": "Total budgetary resources in USD across the result set (agency dimension with spending_type total)",
"type": "number"
}
},
"type": "object"
},
"truncated": {
"description": "True when the upstream capped the reachable result set rather than counting it.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Fetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdown with obligation and transaction counts. Accepts either a 3-digit toptier_code (e.g., 097 for DoD, 012 for Agriculture) or an agency_slug (e.g., department-of-defense) — both appear in usaspending_list_agencies results and award search results.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"agency_slug": {
"description": "URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both.",
"type": "string"
},
"page": {
"default": 1,
"description": "Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"toptier_code": {
"description": "3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both.",
"type": "string"
}
},
"type": "object"
},
"name": "usaspending_get_agency",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"sub_agency_page",
"has_more_sub_agencies"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"abbreviation": {
"description": "Agency abbreviation",
"type": "string"
},
"agency_id": {
"description": "Internal agency ID",
"type": "number"
},
"budgetary_resources_amount": {
"description": "Total budgetary resources in USD for the fiscal year",
"type": "number"
},
"def_codes": {
"description": "Disaster/Emergency Funding (DEF) codes applicable to this agency",
"items": {
"additionalProperties": false,
"description": "DEF code entry with public law and title",
"properties": {
"code": {
"description": "DEF code identifying an emergency supplemental",
"type": "string"
},
"public_law": {
"description": "Public law number",
"type": "string"
},
"title": {
"description": "Emergency or disaster title",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"error": {
"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: `agency_not_found`: No agency found for the given toptier_code or agency_slug. `missing_input`: Neither toptier_code nor agency_slug was provided. `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": [
"agency_not_found",
"missing_input",
"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"
},
"fiscal_year": {
"description": "Fiscal year the budgetary totals below reflect (most recent available)",
"type": "number"
},
"has_more_sub_agencies": {
"description": "Whether more sub-agency pages are available",
"type": "boolean"
},
"mission": {
"description": "Agency mission statement",
"type": "string"
},
"name": {
"description": "Agency full name",
"type": "string"
},
"notice": {
"description": "Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown.",
"type": "string"
},
"obligated_amount": {
"description": "Total amount obligated in USD for the fiscal year",
"type": "number"
},
"outlay_amount": {
"description": "Total outlays in USD for the fiscal year",
"type": "number"
},
"sub_agencies": {
"description": "Sub-agency breakdown within this toptier agency (one page)",
"items": {
"additionalProperties": false,
"description": "Sub-agency entry with obligations and transaction counts",
"properties": {
"abbreviation": {
"description": "Sub-agency abbreviation",
"type": "string"
},
"name": {
"description": "Sub-agency name",
"type": "string"
},
"new_award_count": {
"description": "New awards count",
"type": "number"
},
"total_obligations": {
"description": "Sub-agency obligation total in USD",
"type": "number"
},
"transaction_count": {
"description": "Sub-agency transaction count",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"sub_agency_page": {
"description": "Current sub-agency page returned",
"type": "number"
},
"sub_agency_page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata for the sub-agency breakdown",
"properties": {
"has_next": {
"description": "Whether more sub-agency pages are available",
"type": "boolean"
},
"limit": {
"description": "Sub-agencies per page",
"type": "number"
},
"page": {
"description": "Current sub-agency page number",
"type": "number"
},
"total": {
"description": "Total sub-agencies across all pages",
"type": "number"
}
},
"required": [
"page",
"has_next",
"limit"
],
"type": "object"
},
"sub_agency_total": {
"description": "Total sub-agencies across all pages (when available)",
"type": "number"
},
"subtier_agency_count": {
"description": "Number of sub-agencies within this toptier agency",
"type": "number"
},
"toptier_code": {
"description": "3-digit toptier agency code",
"type": "string"
},
"website": {
"description": "Agency website URL",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient info, agency hierarchy, period of performance, place of performance, 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 hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters. For IDV-category awards (category=\"idv\"), use usaspending_get_idv_awards to list the child contracts and task/delivery orders placed under them.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_id": {
"description": "Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards",
"minLength": 1,
"type": "string"
}
},
"required": [
"award_id"
],
"type": "object"
},
"name": "usaspending_get_award",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"properties": {
"account_obligations_by_defc": {
"description": "Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations",
"items": {
"additionalProperties": false,
"description": "DEF code entry with code and obligation amount",
"properties": {
"amount": {
"description": "Obligation amount in USD for this DEF code",
"type": "number"
},
"code": {
"description": "DEF code identifying the emergency supplemental",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"awarding_agency": {
"additionalProperties": false,
"description": "Awarding agency hierarchy",
"properties": {
"subtier_name": {
"description": "Sub-tier agency name",
"type": "string"
},
"toptier_code": {
"description": "Top-tier agency code",
"type": "string"
},
"toptier_name": {
"description": "Top-tier agency name",
"type": "string"
},
"toptier_slug": {
"description": "Top-tier agency slug",
"type": "string"
}
},
"type": "object"
},
"base_and_all_options_value": {
"description": "Base and all options value in USD (contracts)",
"type": "number"
},
"category": {
"description": "Award category (contract, grant, direct_payment, loan, idv, other)",
"type": "string"
},
"cfda": {
"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"
},
"date_signed": {
"description": "Date award was signed (YYYY-MM-DD)",
"type": "string"
},
"description": {
"description": "Award description",
"type": "string"
},
"error": {
"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"
},
"fain": {
"description": "Federal Award Identification Number (for assistance)",
"type": "string"
},
"funding_agency": {
"additionalProperties": false,
"description": "Funding agency hierarchy",
"properties": {
"subtier_name": {
"description": "Sub-tier funding agency name",
"type": "string"
},
"toptier_code": {
"description": "Top-tier funding agency code",
"type": "string"
},
"toptier_name": {
"description": "Top-tier funding agency name",
"type": "string"
}
},
"type": "object"
},
"generated_unique_award_id": {
"description": "Generated unique award ID",
"type": "string"
},
"naics": {
"additionalProperties": false,
"description": "NAICS code (contracts)",
"properties": {
"code": {
"description": "NAICS industry code",
"type": "string"
},
"description": {
"description": "NAICS industry description",
"type": "string"
}
},
"type": "object"
},
"parent_award": {
"additionalProperties": false,
"description": "Parent IDV information (contracts only)",
"properties": {
"agency_name": {
"description": "Parent award agency name",
"type": "string"
},
"award_id": {
"description": "Parent award display ID",
"type": "string"
},
"generated_unique_award_id": {
"description": "Parent award chaining ID — pass to usaspending_get_award for parent IDV details",
"type": "string"
},
"type_description": {
"description": "Parent award type description",
"type": "string"
}
},
"type": "object"
},
"period_of_performance": {
"additionalProperties": false,
"description": "Period of performance dates",
"properties": {
"end_date": {
"description": "Performance end date (YYYY-MM-DD)",
"type": "string"
},
"potential_end_date": {
"description": "Potential end date including options (YYYY-MM-DD)",
"type": "string"
},
"start_date": {
"description": "Performance start date (YYYY-MM-DD)",
"type": "string"
}
},
"type": "object"
},
"piid": {
"description": "Procurement Instrument Identifier (for contracts)",
"type": "string"
},
"place_of_performance": {
"additionalProperties": false,
"description": "Place of performance",
"properties": {
"city_name": {
"description": "City of performance",
"type": "string"
},
"country_code": {
"description": "Country code of performance",
"type": "string"
},
"state_code": {
"description": "State code of performance",
"type": "string"
},
"zip5": {
"description": "ZIP code of performance",
"type": "string"
}
},
"type": "object"
},
"product_or_service_code": {
"additionalProperties": false,
"description": "Product or service code (contracts)",
"properties": {
"code": {
"description": "PSC product or service code",
"type": "string"
},
"description": {
"description": "PSC description",
"type": "string"
}
},
"type": "object"
},
"recipient": {
"additionalProperties": false,
"description": "Recipient details",
"properties": {
"business_types": {
"description": "Recipient business type codes",
"items": {
"type": "string"
},
"type": "array"
},
"location": {
"additionalProperties": false,
"description": "Recipient address",
"properties": {
"city_name": {
"description": "Recipient city",
"type": "string"
},
"country_code": {
"description": "Recipient country code",
"type": "string"
},
"state_code": {
"description": "Recipient state code",
"type": "string"
}
},
"type": "object"
},
"parent_recipient_name": {
"description": "Parent organization name",
"type": "string"
},
"recipient_id": {
"description": "Recipient hash ID — pass to usaspending_get_recipient for full profile",
"type": "string"
},
"recipient_name": {
"description": "Recipient legal business name",
"type": "string"
},
"uei": {
"description": "Unique Entity Identifier",
"type": "string"
}
},
"type": "object"
},
"subaward_count": {
"description": "Number of subawards; use with usaspending_get_award_subawards",
"type": "number"
},
"total_obligation": {
"description": "Total obligation amount in USD",
"type": "number"
},
"total_outlays": {
"description": "Total outlay amount in USD",
"type": "number"
},
"type": {
"description": "Award type code",
"type": "string"
},
"type_description": {
"description": "Human-readable award type",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it. This is the award → appropriation link: each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) to chain into usaspending_get_federal_account for the account budget detail. The award_id must be a generated_unique_award_id — from usaspending_search_awards (generated_internal_id field) or usaspending_get_award. Distinct from usaspending_get_award account_obligations_by_defc, which breaks funding down by Disaster/Emergency Funding code rather than by account. An award_id that does not exist returns an empty list rather than an error.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_id": {
"description": "Award generated_unique_award_id (e.g., CONT_AWD_GSFC0198106DNAS526555_8000_-NONE-_-NONE-) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"award_id"
],
"type": "object"
},
"name": "usaspending_get_award_federal_accounts",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"award_id": {
"description": "Award ID queried",
"type": "string"
},
"current_page": {
"description": "Current page returned",
"type": "number"
},
"error": {
"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"
},
"has_next_page": {
"description": "Whether there are more pages of funding accounts",
"type": "boolean"
},
"notice": {
"description": "Recovery hint when results are empty — the award_id may not exist or may have no account linkage. Absent when results are present.",
"type": "string"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata",
"properties": {
"count": {
"description": "Total funding accounts across all pages",
"type": "number"
},
"has_next": {
"description": "Whether there are more pages of results",
"type": "boolean"
},
"has_previous": {
"description": "Whether there are previous pages",
"type": "boolean"
},
"limit": {
"description": "Results per page",
"type": "number"
},
"page": {
"description": "Current page number",
"type": "number"
}
},
"required": [
"page",
"has_next",
"has_previous",
"limit"
],
"type": "object"
},
"results": {
"description": "Federal accounts funding this award",
"items": {
"additionalProperties": false,
"description": "Federal account that funded this award, with obligation and funding agency",
"properties": {
"account_title": {
"description": "Full federal account title",
"type": "string"
},
"federal_account": {
"description": "Federal account code in AGENCY-MAIN format (e.g., 080-0120) — pass to usaspending_get_federal_account as account_code for the account budget detail",
"type": "string"
},
"funding_agency_abbreviation": {
"description": "Abbreviation of the funding agency (e.g., \"NASA\")",
"type": "string"
},
"funding_agency_id": {
"description": "Internal USAspending database ID of the funding agency — not the toptier code accepted by usaspending_get_agency",
"type": "number"
},
"funding_agency_name": {
"description": "Name of the funding agency",
"type": "string"
},
"funding_agency_slug": {
"description": "Funding agency slug (e.g., \"national-aeronautics-and-space-administration\") — pass to usaspending_get_agency as agency_slug",
"type": "string"
},
"funding_toptier_agency_id": {
"description": "Internal USAspending database ID of the funding toptier agency — not the 3-digit toptier code accepted by usaspending_get_agency",
"type": "number"
},
"total_transaction_obligated_amount": {
"description": "Amount obligated to this award from this federal account in USD",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of funding accounts across all pages (when available)",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List subaward contracts or grants under a prime federal award. Reveals the sub-contractor or sub-grantee layer — the organizations that actually perform the work. Each row shows the subaward number, amount, description, action date, and recipient. Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_id": {
"description": "Generated unique award ID (generated_internal_id from usaspending_search_awards)",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum subawards per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"order": {
"default": "desc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"sort": {
"default": "action_date",
"description": "Sort field for subawards",
"enum": [
"subaward_number",
"description",
"action_date",
"amount",
"recipient_name"
],
"type": "string"
}
},
"required": [
"award_id"
],
"type": "object"
},
"name": "usaspending_get_award_subawards",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"prime_award_id",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"award_id": {
"description": "Prime award ID queried",
"type": "string"
},
"current_page": {
"description": "Current page returned",
"type": "number"
},
"error": {
"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"
},
"has_next_page": {
"description": "Whether there are more pages of subawards",
"type": "boolean"
},
"notice": {
"description": "Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present.",
"type": "string"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata",
"properties": {
"has_next": {
"description": "Whether there are more pages",
"type": "boolean"
},
"limit": {
"description": "Subawards per page",
"type": "number"
},
"page": {
"description": "Current page",
"type": "number"
},
"total": {
"description": "Total subaward count",
"type": "number"
}
},
"required": [
"has_next",
"page",
"limit"
],
"type": "object"
},
"prime_award_id": {
"description": "Prime award ID whose subawards were listed",
"type": "string"
},
"results": {
"description": "List of subawards under this prime award",
"items": {
"additionalProperties": false,
"description": "Subaward record with amount, recipient, and location",
"properties": {
"action_date": {
"description": "Subaward action date (YYYY-MM-DD)",
"type": "string"
},
"amount": {
"description": "Subaward amount in USD",
"type": "number"
},
"description": {
"description": "Subaward description",
"type": "string"
},
"id": {
"description": "Subaward internal ID",
"type": "number"
},
"place_of_performance": {
"additionalProperties": false,
"description": "Subaward place of performance",
"properties": {
"city": {
"description": "City of performance",
"type": "string"
},
"country": {
"description": "Country code",
"type": "string"
},
"state": {
"description": "State code",
"type": "string"
}
},
"type": "object"
},
"recipient_name": {
"description": "Subcontractor or sub-grantee name",
"type": "string"
},
"recipient_uei": {
"description": "Sub-recipient Unique Entity Identifier",
"type": "string"
},
"subaward_number": {
"description": "Subaward number or identifier",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total subaward count across all pages (when available)",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List individual transactions (contract modifications, grant amendments) on a federal award. Each transaction represents a change event — obligation modifications, performance period extensions, scope changes, etc. Use this to trace the spending history and obligation changes over the life of an award. Award IDs come from usaspending_search_awards (generated_internal_id field).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_id": {
"description": "Generated unique award ID (generated_internal_id from usaspending_search_awards)",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum transactions per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"order": {
"default": "desc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"sort": {
"default": "action_date",
"description": "Sort field for transactions",
"enum": [
"action_date",
"federal_action_obligation",
"modification_number"
],
"type": "string"
}
},
"required": [
"award_id"
],
"type": "object"
},
"name": "usaspending_get_award_transactions",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"queried_award_id",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"award_id": {
"description": "Award ID queried",
"type": "string"
},
"current_page": {
"description": "Current page returned",
"type": "number"
},
"error": {
"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"
},
"has_next_page": {
"description": "Whether there are more pages of transactions",
"type": "boolean"
},
"notice": {
"description": "Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present.",
"type": "string"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata",
"properties": {
"has_next": {
"description": "Whether there are more pages",
"type": "boolean"
},
"limit": {
"description": "Transactions per page",
"type": "number"
},
"page": {
"description": "Current page",
"type": "number"
},
"total": {
"description": "Total transaction count",
"type": "number"
}
},
"required": [
"has_next",
"page",
"limit"
],
"type": "object"
},
"queried_award_id": {
"description": "Award ID whose transactions were listed",
"type": "string"
},
"results": {
"description": "List of transactions for this award",
"items": {
"additionalProperties": false,
"description": "Transaction record with modification details and obligation change",
"properties": {
"action_date": {
"description": "Transaction action date (YYYY-MM-DD)",
"type": "string"
},
"action_type": {
"description": "Action type code",
"type": "string"
},
"action_type_description": {
"description": "Action type description",
"type": "string"
},
"awarding_agency_name": {
"description": "Awarding agency name",
"type": "string"
},
"description": {
"description": "Transaction description",
"type": "string"
},
"federal_action_obligation": {
"description": "Obligation change in USD for this transaction (positive = increase, negative = deobligation)",
"type": "number"
},
"id": {
"description": "Transaction internal ID",
"type": "number"
},
"modification_number": {
"description": "Modification number or amendment",
"type": "string"
},
"recipient_name": {
"description": "Recipient name at time of transaction",
"type": "string"
},
"type": {
"description": "Transaction type code",
"type": "string"
},
"type_description": {
"description": "Transaction type description",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total transaction count across all pages (when available)",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Fetch a federal account's budget data: total obligations, gross outlays, and budgetary resources, plus the per-Treasury-Account-Symbol (TAS) component breakdown in children. Federal accounts connect appropriations law to actual agency spending. Account codes come from usaspending_search_federal_accounts (its account_number output field) or usaspending_get_award_federal_accounts (its federal_account field), and are formatted as AGENCY-MAIN (e.g., 097-0100 for DoD Operation and Maintenance). For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"account_code": {
"description": "Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.",
"minLength": 1,
"type": "string"
}
},
"required": [
"account_code"
],
"type": "object"
},
"name": "usaspending_get_federal_account",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"properties": {
"account_title": {
"description": "Full account title",
"type": "string"
},
"agency_identifier": {
"description": "Agency identifier code",
"type": "string"
},
"bureau_name": {
"description": "Bureau name within the agency",
"type": "string"
},
"children": {
"description": "Treasury Account Symbol (TAS) components that make up this federal account, each with its own obligated, outlay, and budgetary-resource amounts. Omitted when the upstream returns none.",
"items": {
"additionalProperties": false,
"description": "Treasury Account Symbol component with its own financial amounts",
"properties": {
"budgetary_resources_amount": {
"description": "Budgetary resources in USD for this Treasury Account Symbol",
"type": "number"
},
"code": {
"description": "Full Treasury Account Symbol (e.g., 080-2020/2021-0120-000) — the availability-period-scoped component of this federal account, not an account_code accepted by this tool",
"type": "string"
},
"gross_outlay_amount": {
"description": "Gross outlay amount in USD for this Treasury Account Symbol",
"type": "number"
},
"name": {
"description": "Treasury Account Symbol title",
"type": "string"
},
"obligated_amount": {
"description": "Obligated amount in USD for this Treasury Account Symbol",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"error": {
"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: `account_not_found`: No federal account found for the given account code. `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": [
"account_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"
},
"federal_account_code": {
"description": "Federal account code",
"type": "string"
},
"fiscal_year": {
"description": "Fiscal year of the financial data",
"type": "number"
},
"main_account_code": {
"description": "Main account code",
"type": "string"
},
"parent_agency_name": {
"description": "Managing parent agency name",
"type": "string"
},
"total_budgetary_resources": {
"description": "Total budgetary resources in USD",
"type": "number"
},
"total_gross_outlay_amount": {
"description": "Total gross outlay amount in USD",
"type": "number"
},
"total_obligated_amount": {
"description": "Total obligated amount in USD",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Fetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. Account codes are AGENCY-MAIN format and come from usaspending_search_federal_accounts (its account_number output field), usaspending_get_award_federal_accounts (its federal_account field), or usaspending_get_federal_account. Paginated with an honest total count. For the account's own metadata and top-level totals, use usaspending_get_federal_account.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"account_code": {
"description": "Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.",
"minLength": 1,
"type": "string"
},
"dimension": {
"description": "Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased)",
"enum": [
"program_activity",
"object_class"
],
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"account_code",
"dimension"
],
"type": "object"
},
"name": "usaspending_get_federal_account_breakdown",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"account_code",
"dimension",
"results",
"page_metadata",
"applied_dimension",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"account_code": {
"description": "Federal account code queried",
"type": "string"
},
"applied_dimension": {
"description": "Breakdown dimension applied",
"type": "string"
},
"current_page": {
"description": "Current page returned",
"type": "number"
},
"dimension": {
"description": "Breakdown dimension returned",
"type": "string"
},
"error": {
"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"
},
"has_next_page": {
"description": "Whether there are more pages of breakdown rows",
"type": "boolean"
},
"notice": {
"description": "Recovery hint when results are empty — the account code may not exist or may have no obligations on this axis. Absent when results are present.",
"type": "string"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata",
"properties": {
"has_next": {
"description": "Whether there are more pages of results",
"type": "boolean"
},
"has_previous": {
"description": "Whether there are previous pages",
"type": "boolean"
},
"limit": {
"description": "Results per page",
"type": "number"
},
"page": {
"description": "Current page number",
"type": "number"
},
"total": {
"description": "Total rows across all pages",
"type": "number"
}
},
"required": [
"page",
"has_next",
"has_previous",
"limit"
],
"type": "object"
},
"results": {
"description": "Breakdown rows for the requested dimension",
"items": {
"additionalProperties": false,
"description": "Breakdown row with code, name, and obligated amount",
"properties": {
"code": {
"description": "Program activity code or object class code (e.g., \"0001\", \"25.2\")",
"type": "string"
},
"name": {
"description": "Program activity name or object class name",
"type": "string"
},
"obligations": {
"description": "Obligated amount in USD",
"type": "number"
},
"type": {
"description": "Program activity code system, returned only for the program_activity dimension: \"PAC/PAN\" (legacy program activity code/name) or \"PARK\" (Program Activity Reporting Key). Both can appear for the same account. Absent for object_class rows.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of breakdown rows across all pages (when available)",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "List child contracts and task/delivery orders placed under an IDV (Indefinite Delivery Vehicle) award. Each row includes the generated_unique_award_id to chain into usaspending_get_award for full detail. The award_id must be the generated_unique_award_id of the parent IDV — obtainable from usaspending_search_awards (generated_internal_id field) or from usaspending_get_award. IDV category awards returned by usaspending_get_award have child orders accessible via this tool.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_id": {
"description": "Parent IDV generated_unique_award_id (e.g., CONT_IDV_NNK14MA74C_8000) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"order": {
"default": "desc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"sort": {
"default": "obligated_amount",
"description": "Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date)",
"type": "string"
},
"type": {
"default": "child_awards",
"description": "Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVs",
"enum": [
"child_awards",
"child_idvs",
"grandchild_awards"
],
"type": "string"
}
},
"required": [
"award_id"
],
"type": "object"
},
"name": "usaspending_get_idv_awards",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"award_id",
"results",
"page_metadata",
"parent_award_id",
"current_page",
"has_next_page"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"award_id": {
"description": "Parent IDV award ID queried",
"type": "string"
},
"cap": {
"description": "The per-page limit that was applied.",
"type": "number"
},
"current_page": {
"description": "Current page returned",
"type": "number"
},
"error": {
"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"
},
"has_next_page": {
"description": "Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none.",
"type": "boolean"
},
"notice": {
"description": "Recovery hint when results are empty — the award may have no children of the requested type. Absent when results are present.",
"type": "string"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata (no total count available from this endpoint)",
"properties": {
"has_next": {
"description": "Whether more child awards may remain — true on a full page even when the upstream flag reports none (this endpoint returns no total). A short or empty page marks the end.",
"type": "boolean"
},
"has_previous": {
"description": "Whether there are previous pages",
"type": "boolean"
},
"limit": {
"description": "Results per page",
"type": "number"
},
"page": {
"description": "Current page number",
"type": "number"
}
},
"required": [
"has_next",
"has_previous",
"page",
"limit"
],
"type": "object"
},
"parent_award_id": {
"description": "Parent IDV award ID whose children were listed",
"type": "string"
},
"results": {
"description": "Child awards placed under this IDV",
"items": {
"additionalProperties": false,
"description": "Child award record with ID, amounts, agencies, and performance dates",
"properties": {
"award_type": {
"description": "Award type (e.g., \"DELIVERY ORDER\")",
"type": "string"
},
"awarding_agency": {
"description": "Name of the awarding agency",
"type": "string"
},
"description": {
"description": "Award description",
"type": "string"
},
"funding_agency": {
"description": "Name of the funding agency",
"type": "string"
},
"generated_unique_award_id": {
"description": "Generated unique award ID for this child award — pass to usaspending_get_award to fetch full details",
"type": "string"
},
"last_date_to_order": {
"description": "Last date to place orders against this IDV (YYYY-MM-DD, nullable)",
"type": "string"
},
"obligated_amount": {
"description": "Total obligated amount in USD",
"type": "number"
},
"period_of_performance_current_end_date": {
"description": "Performance current end date (YYYY-MM-DD)",
"type": "string"
},
"period_of_performance_start_date": {
"description": "Performance start date (YYYY-MM-DD)",
"type": "string"
},
"piid": {
"description": "Procurement Instrument Identifier",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of child awards returned on this page.",
"type": "number"
},
"truncated": {
"description": "True when this page was full and more child awards may remain beyond it.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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. Optionally scope the totals to a specific fiscal year and award type. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_type": {
"description": "Award type category to scope award totals",
"enum": [
"contracts",
"grants",
"direct_payments",
"loans",
"other_financial_assistance"
],
"type": "string"
},
"fiscal_year": {
"description": "Fiscal year to scope award totals (e.g., 2024)",
"maximum": 2030,
"minimum": 2001,
"type": "integer"
},
"recipient_id": {
"description": "Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award",
"minLength": 1,
"type": "string"
}
},
"required": [
"recipient_id"
],
"type": "object"
},
"name": "usaspending_get_recipient",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
]
}
],
"properties": {
"alternate_names": {
"description": "Alternate business names",
"items": {
"type": "string"
},
"type": "array"
},
"business_types": {
"description": "Business type codes",
"items": {
"type": "string"
},
"type": "array"
},
"duns": {
"description": "DUNS number (legacy)",
"type": "string"
},
"error": {
"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"
},
"location": {
"additionalProperties": false,
"description": "Recipient address",
"properties": {
"address_line1": {
"description": "Street address line 1",
"type": "string"
},
"address_line2": {
"description": "Street address line 2",
"type": "string"
},
"city_name": {
"description": "City",
"type": "string"
},
"country_code": {
"description": "Country code",
"type": "string"
},
"state_code": {
"description": "State code",
"type": "string"
},
"zip": {
"description": "ZIP code",
"type": "string"
},
"zip4": {
"description": "ZIP+4 extension",
"type": "string"
}
},
"type": "object"
},
"name": {
"description": "Recipient legal business name",
"type": "string"
},
"parent_name": {
"description": "Parent organization name",
"type": "string"
},
"parent_uei": {
"description": "Parent organization UEI",
"type": "string"
},
"recipient_id": {
"description": "Recipient hash ID",
"type": "string"
},
"recipient_level": {
"description": "Hierarchy level: P = parent, C = child, R = standalone",
"type": "string"
},
"total_face_value_loan_amount": {
"description": "Total face value of loans in USD",
"type": "number"
},
"total_face_value_loan_transactions": {
"description": "Number of face-value loan transactions",
"type": "number"
},
"total_transaction_amount": {
"description": "Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided",
"type": "number"
},
"total_transactions": {
"description": "Total number of award transactions",
"type": "number"
},
"uei": {
"description": "Unique Entity Identifier (SAM.gov)",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "List all top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the current fiscal year. 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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"order": {
"default": "asc",
"description": "Sort direction: asc or desc",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"sort": {
"default": "agency_name",
"description": "Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount",
"enum": [
"agency_name",
"budget_authority_amount",
"obligated_amount",
"outlay_amount"
],
"type": "string"
}
},
"type": "object"
},
"name": "usaspending_list_agencies",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"total",
"agency_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"agency_count": {
"description": "Total number of top-tier federal agencies returned",
"type": "number"
},
"error": {
"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"
},
"results": {
"description": "List of top-tier federal agencies with budget and obligation data",
"items": {
"additionalProperties": false,
"description": "Agency entry with codes, slugs, and fiscal year budget data",
"properties": {
"abbreviation": {
"description": "Agency abbreviation or acronym",
"type": "string"
},
"agency_name": {
"description": "Full agency name",
"type": "string"
},
"agency_slug": {
"description": "URL-friendly agency slug (e.g., department-of-defense) — accepted by usaspending_get_agency",
"type": "string"
},
"budget_authority_amount": {
"description": "Total budget authority amount in USD for the current fiscal year",
"type": "number"
},
"obligated_amount": {
"description": "Total obligated amount in USD for the current fiscal year",
"type": "number"
},
"outlay_amount": {
"description": "Total outlay amount in USD for the current fiscal year",
"type": "number"
},
"toptier_code": {
"description": "Three-digit toptier agency code (e.g., 097 for DoD) — required by usaspending_get_agency",
"type": "string"
}
},
"required": [
"agency_name",
"toptier_code"
],
"type": "object"
},
"type": "array"
},
"total": {
"description": "Total number of agencies returned",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search federal awards by keyword, recipient, agency, award type, NAICS code, assistance listing (CFDA) number, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usaspending_get_award; loan rows carry loan value, subsidy cost, and issue date in place of award amount and dates. Award types: A/B/C/D = contracts, IDV_A–IDV_E = IDVs, 02/03/04/05/F001/F002 = grants, 06/10/F006/F007 = direct payments, 07/08/F003/F004 = loans, 09/11/-1/F005/F008/F009/F010 = other assistance. Dates must be ISO 8601 (YYYY-MM-DD). Earliest data: 2007-10-01 via search API. DoD contracts have a 90-day publication lag.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"agency_name": {
"description": "Filter to a specific awarding agency by name (e.g., \"Department of Defense\"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names.",
"type": "string"
},
"assistance_listings": {
"description": "Filter by Assistance Listing (CFDA) program numbers, e.g. [\"93.866\"]: two digits, a dot, then three digits or capital letters (11.67A). Matches an award when any of its listings equals one of these exactly; several values match any of them. A row's primary listing can differ from the one requested, and its amount is the whole award, not that listing's share. Assistance award types only — set award_type_codes to grants, direct payments, loans, or other assistance; contracts and IDVs carry no listings, so pairing them (including the default award_type_codes) is rejected. Use usaspending_autocomplete_filters type=cfda to look up numbers.",
"items": {
"description": "Assistance Listing number, e.g. 93.866",
"pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
"type": "string"
},
"type": "array"
},
"award_type_codes": {
"default": [
"A",
"B",
"C",
"D"
],
"description": "Filter by award type codes. All codes must belong to a single group: A/B/C/D (contracts), IDV_A/IDV_B/IDV_B_A/IDV_B_B/IDV_B_C/IDV_C/IDV_D/IDV_E (IDVs), 02/03/04/05/F001/F002 (grants), 06/10/F006/F007 (direct payments), 07/08/F003/F004 (loans), 09/11/-1/F005/F008/F009/F010 (other assistance). Defaults to contracts. Mixing groups causes a 422 error. The group decides which sort values apply.",
"items": {
"type": "string"
},
"minItems": 1,
"type": "array"
},
"filters": {
"description": "Optional analytics-style filter object mirroring the shape the spending analytics tools accept, for reusing one filter set across tools. When both this object and the equivalent top-level flat filters are given, this object wins per-field. recipient_id is intentionally not accepted — this endpoint silently ignores it; filter by recipient via recipient_name.",
"properties": {
"agency_name": {
"description": "Awarding agency name (toptier), e.g., \"Department of Defense\"",
"type": "string"
},
"award_type_codes": {
"description": "Award type codes; all must belong to one group (A/B/C/D contracts, IDV_A–IDV_E IDVs, 02/03/04/05/F001/F002 grants, 06/10/F006/F007 direct payments, 07/08/F003/F004 loans, 09/11/-1/F005/F008/F009/F010 other assistance). When non-empty, overrides the top-level award_type_codes and decides which sort values apply; an empty array falls back to the top-level value.",
"items": {
"type": "string"
},
"type": "array"
},
"keywords": {
"description": "Full-text search terms across award descriptions, recipient names, and places",
"items": {
"type": "string"
},
"type": "array"
},
"naics_codes": {
"description": "NAICS industry codes to require, e.g., [\"541512\"]",
"items": {
"type": "string"
},
"type": "array"
},
"recipient_name": {
"description": "Recipient name search (partial match); maps to recipient_search_text. Use instead of recipient_id, which this endpoint ignores.",
"type": "string"
},
"time_period_end": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "End date (YYYY-MM-DD). Given alone, the range starts at 2007-10-01, the earliest searchable date."
},
"time_period_start": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "Start date (YYYY-MM-DD); earliest valid 2007-10-01. Given alone, the range runs through today (UTC)."
}
},
"type": "object"
},
"keyword": {
"description": "Full-text search across award descriptions, recipient names, and place names",
"type": "string"
},
"last_record_sort_value": {
"description": "Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap. The upstream stops emitting the pair once page × limit reaches 10,000, so take it from a page below that offset. When both cursor fields are supplied, page is ignored.",
"type": "string"
},
"last_record_unique_id": {
"description": "Keyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"location_filter": {
"description": "Filter by place of performance location. Uses FIPS codes and 2-letter state abbreviations, not place names — use a geocoding server to resolve names to codes first.",
"properties": {
"city": {
"description": "City name",
"type": "string"
},
"country": {
"description": "ISO 3166-1 alpha-3 country code (e.g., USA)",
"type": "string"
},
"county": {
"description": "FIPS county code (e.g., 06037 for Los Angeles County)",
"type": "string"
},
"state": {
"description": "Two-letter US state abbreviation (e.g., CA)",
"type": "string"
}
},
"type": "object"
},
"naics_codes": {
"description": "Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete_filters type=naics to look up codes.",
"items": {
"type": "string"
},
"type": "array"
},
"order": {
"default": "desc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"page": {
"default": 1,
"description": "Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit), but the keyset cursor below is only returned while the offset stays under 10,000 — capture the cursor pair before paging past that, or the only way forward is page numbers.",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"recipient_name": {
"description": "Filter by recipient name (partial match); maps to this endpoint's recipient_search_text. This endpoint has no recipient_id filter — use usaspending_search_recipients to look up a recipient by name.",
"type": "string"
},
"sort": {
"description": "Sort field for results. Loans (07/08/F003/F004) sort by Loan Value, Subsidy Cost, Issued Date, Recipient Name, or Awarding Agency, defaulting to Loan Value. Every other group sorts by Award Amount, Total Outlays, Start Date, End Date, Recipient Name, or Awarding Agency, defaulting to Award Amount — except IDVs, which have no End Date. A sort the group does not support is rejected before the search runs.",
"enum": [
"Award Amount",
"Total Outlays",
"Start Date",
"End Date",
"Loan Value",
"Subsidy Cost",
"Issued Date",
"Recipient Name",
"Awarding Agency"
],
"type": "string"
},
"time_period": {
"description": "Filter awards by date range (action date). Both blank means no date filter; one blank end is filled and named in the notice.",
"properties": {
"end_date": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "End date in ISO 8601 format (YYYY-MM-DD). Blank (\"\") leaves the end open, filled with today (UTC)."
},
"start_date": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "Start date in ISO 8601 format (YYYY-MM-DD); earliest valid: 2007-10-01. Blank (\"\") leaves the start open, filled with 2007-10-01."
}
},
"required": [
"start_date",
"end_date"
],
"type": "object"
}
},
"type": "object"
},
"name": "usaspending_search_awards",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"page_metadata",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"applied_agency_name": {
"description": "Awarding agency name filter applied",
"type": "string"
},
"applied_assistance_listings": {
"description": "Assistance Listing numbers filter applied (comma-separated)",
"type": "string"
},
"applied_keyword": {
"description": "Keyword filter applied to this search",
"type": "string"
},
"applied_naics_codes": {
"description": "NAICS codes filter applied (comma-separated)",
"type": "string"
},
"applied_time_period_end": {
"description": "End of the date range sent (YYYY-MM-DD), including a filled-in end",
"type": "string"
},
"applied_time_period_start": {
"description": "Start of the date range sent (YYYY-MM-DD), including a filled-in start",
"type": "string"
},
"cap": {
"description": "Per-page cap (limit) applied to this page.",
"type": "number"
},
"error": {
"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. `pagination_limit_exceeded`: page multiplied by limit exceeds the endpoint 50,000-result page window and no cursor was supplied. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. `date_range_inverted`: Both ends of the date range were supplied and the start date falls after the end date. `unsupported_sort`: The sort value is not one the award type group supports. `assistance_listings_type_mismatch`: assistance_listings was given while the award type codes include contract or IDV codes, or were left at the contract default. Other values are possible when a failure originates below the handler.",
"examples": [
"api_unavailable",
"api_timeout",
"pagination_limit_exceeded",
"date_before_earliest",
"date_range_inverted",
"unsupported_sort",
"assistance_listings_type_mismatch"
],
"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"
},
"has_next": {
"description": "Whether more results may remain — set on a full page even when the upstream flag reports none.",
"type": "boolean"
},
"notice": {
"description": "How to page on when more results may remain, which date bound was filled in when only the other was supplied, and — when results are empty — the applied filters with how to broaden. Absent when none applies.",
"type": "string"
},
"page": {
"description": "Current page number returned",
"type": "number"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page.",
"properties": {
"has_next": {
"description": "Whether more results may remain — true on a full page even when the upstream flag reports none, since this endpoint under-reports continuation on a final full page and on every page past a 10,000-result offset. A short or empty page marks the end.",
"type": "boolean"
},
"last_record_sort_value": {
"description": "Keyset-pagination cursor for the next page — pass back as last_record_sort_value to continue past the 50,000-result page limit. Absent once page × limit reaches 10,000, where the upstream stops emitting the pair.",
"type": "string"
},
"last_record_unique_id": {
"description": "Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value. Absent on the same pages that omit last_record_sort_value.",
"type": "number"
},
"limit": {
"description": "Results per page",
"type": "number"
},
"page": {
"description": "Current page number",
"type": "number"
}
},
"required": [
"has_next",
"page",
"limit"
],
"type": "object"
},
"results": {
"description": "Matching award summaries",
"items": {
"additionalProperties": false,
"description": "Award summary with amounts, agencies, and chaining IDs",
"properties": {
"agency_slug": {
"description": "URL-friendly awarding-agency slug (e.g., national-aeronautics-and-space-administration) — pass to usaspending_get_agency as agency_slug. Absent when the agency has no profile page.",
"type": "string"
},
"award_amount": {
"description": "Total award amount in USD",
"type": "number"
},
"award_id": {
"description": "Display award ID (piid, fain, or uri) — NOT the chaining ID",
"type": "string"
},
"award_type": {
"description": "Award type description",
"type": "string"
},
"awarding_agency": {
"description": "Name of the awarding agency",
"type": "string"
},
"awarding_sub_agency": {
"description": "Name of the awarding sub-agency",
"type": "string"
},
"description": {
"description": "Award description",
"type": "string"
},
"end_date": {
"description": "Award end date (YYYY-MM-DD)",
"type": "string"
},
"funding_agency": {
"description": "Name of the funding agency",
"type": "string"
},
"generated_internal_id": {
"description": "Generated unique award ID — pass to usaspending_get_award to fetch full details",
"type": "string"
},
"issued_date": {
"description": "Date the loan was issued (YYYY-MM-DD; loans only — they carry no start or end date)",
"type": "string"
},
"loan_value": {
"description": "Face value of the loan in USD (loans only — they carry no award_amount)",
"type": "number"
},
"place_of_performance": {
"additionalProperties": false,
"description": "Place of performance location",
"properties": {
"city": {
"description": "City of performance",
"type": "string"
},
"country": {
"description": "Country code of performance",
"type": "string"
},
"state": {
"description": "State code of performance",
"type": "string"
}
},
"type": "object"
},
"recipient_name": {
"description": "Name of the award recipient",
"type": "string"
},
"start_date": {
"description": "Award start date (YYYY-MM-DD)",
"type": "string"
},
"subsidy_cost": {
"description": "Original subsidy cost of the loan in USD — the estimated long-term cost to the government (loans only)",
"type": "number"
},
"total_outlays": {
"description": "Total outlays in USD",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of awards returned on this page.",
"type": "number"
},
"truncated": {
"description": "True when this page was capped at `limit` and more results may remain (continue via page or the cursor).",
"type": "boolean"
},
"upstream_messages": {
"description": "Notices the USAspending API returned with this response — e.g. a supplied filter it ignored because this endpoint does not support it. Every successful response also carries a standing advisory that search covers 2007-10-01 onward; that advisory is boilerplate, not a verdict on the dates requested. Present whenever the API returns any messages.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "List and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. Use account_number from results as input to usaspending_get_federal_account for full budget detail. Use usaspending_list_agencies to look up agency_identifier codes (3-digit strings, e.g. \"097\" for DoD).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"agency_identifier": {
"description": "3-digit agency identifier code (e.g., \"097\" for Department of Defense). Use usaspending_list_agencies to look up codes.",
"type": "string"
},
"keyword": {
"description": "Filter accounts by name or title keyword (e.g., \"defense\", \"transportation\")",
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
},
"sort_direction": {
"default": "desc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"sort_field": {
"default": "budgetary_resources",
"description": "Field to sort results by",
"enum": [
"account_name",
"account_number",
"budgetary_resources",
"managing_agency"
],
"type": "string"
}
},
"type": "object"
},
"name": "usaspending_search_federal_accounts",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"page_metadata",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"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"
},
"has_next": {
"description": "Whether there are more pages of results",
"type": "boolean"
},
"notice": {
"description": "Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present.",
"type": "string"
},
"page": {
"description": "Current page number returned",
"type": "number"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata",
"properties": {
"count": {
"description": "Total matching accounts across all pages",
"type": "number"
},
"has_next": {
"description": "Whether there are more pages of results",
"type": "boolean"
},
"limit": {
"description": "Results per page",
"type": "number"
},
"page": {
"description": "Current page number",
"type": "number"
}
},
"required": [
"page",
"has_next",
"limit"
],
"type": "object"
},
"results": {
"description": "Matching federal accounts",
"items": {
"additionalProperties": false,
"description": "Federal account record with code, name, agency, and budget",
"properties": {
"account_name": {
"description": "Full federal account title",
"type": "string"
},
"account_number": {
"description": "Federal account code (e.g., \"097-8097\") — pass to usaspending_get_federal_account for full detail",
"type": "string"
},
"agency_identifier": {
"description": "3-digit agency identifier code for this account",
"type": "string"
},
"budgetary_resources": {
"description": "Total budgetary resources for this account in USD",
"type": "number"
},
"managing_agency": {
"description": "Name of the managing agency",
"type": "string"
},
"managing_agency_acronym": {
"description": "Acronym of the managing agency (e.g., \"DOD\")",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of matching accounts across all pages (when available)",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Search for organizations or individuals receiving federal funds by name, UEI (Unique Entity Identifier), or DUNS. Returns recipient hash IDs, UEI/DUNS identifiers, total award amounts, and hierarchy level. Results are paginated — use page to retrieve matches beyond the first page; page_metadata.total reports the full match count. Recipient hash IDs from this tool can be passed to usaspending_get_recipient for full profiles. Recipient level: P = parent organization, C = child entity, R = standalone.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"award_type": {
"description": "Filter by award type category to scope the total amounts returned",
"enum": [
"contracts",
"grants",
"direct_payments",
"loans",
"other_financial_assistance"
],
"type": "string"
},
"keyword": {
"description": "Name, UEI, DUNS, or keyword to search for — partial matches are supported",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum results per page (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Page number (1-based) — request the next page to retrieve matches beyond the first",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"keyword"
],
"type": "object"
},
"name": "usaspending_search_recipients",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"results",
"page_metadata",
"recipient_count",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"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"
},
"has_next": {
"description": "Whether there are more pages of results",
"type": "boolean"
},
"notice": {
"description": "Recovery hint — how to continue to the next page when more results exist, or how to broaden the search when empty. Absent when the full match set fits on this page.",
"type": "string"
},
"page": {
"description": "Current page number returned",
"type": "number"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata — page through with the page input to reach later matches",
"properties": {
"has_next": {
"description": "Whether there are more pages of results",
"type": "boolean"
},
"limit": {
"description": "Results per page",
"type": "number"
},
"page": {
"description": "Current page number",
"type": "number"
},
"total": {
"description": "Total matching recipients across all pages",
"type": "number"
}
},
"required": [
"page",
"has_next",
"limit"
],
"type": "object"
},
"recipient_count": {
"description": "Number of matching recipients returned on this page",
"type": "number"
},
"results": {
"description": "Matching recipients",
"items": {
"additionalProperties": false,
"description": "Recipient entry with ID, name, and award totals",
"properties": {
"amount": {
"description": "Total award amount in USD for the selected award type",
"type": "number"
},
"duns": {
"description": "DUNS number (legacy, being phased out)",
"type": "string"
},
"id": {
"description": "Recipient hash ID (UUID format with level suffix: -P parent, -C child, -R standalone) — pass to usaspending_get_recipient for full profile",
"type": "string"
},
"name": {
"description": "Recipient legal business name",
"type": "string"
},
"recipient_level": {
"description": "Hierarchy level: P = parent, C = child, R = standalone",
"type": "string"
},
"uei": {
"description": "Unique Entity Identifier (SAM.gov)",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total matching recipients across all pages",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Aggregate federal spending grouped by a specific dimension: NAICS industry code, PSC product/service code, awarding agency, funding agency, CFDA assistance program, or recipient. Returns top items with obligation amounts — useful for trend and breakdown analysis. Chain NAICS codes into usaspending_search_awards filters or usaspending_autocomplete_filters lookups.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"category": {
"description": "Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), recipient_duns, or recipient_parent_duns",
"enum": [
"naics",
"psc",
"awarding_agency",
"awarding_subagency",
"funding_agency",
"funding_subagency",
"cfda",
"recipient_duns",
"recipient_parent_duns"
],
"type": "string"
},
"filters": {
"description": "Optional filters to scope the aggregation",
"properties": {
"agency_name": {
"description": "Awarding agency name filter",
"type": "string"
},
"award_type_codes": {
"description": "Award type code filters (A/B/C/D, 02–05, etc.)",
"items": {
"type": "string"
},
"type": "array"
},
"keywords": {
"description": "Full-text keyword filters",
"items": {
"type": "string"
},
"type": "array"
},
"naics_codes": {
"description": "NAICS code filters",
"items": {
"type": "string"
},
"type": "array"
},
"recipient_id": {
"description": "Exact recipient hash ID filter",
"type": "string"
},
"time_period_end": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "End date (YYYY-MM-DD). Given alone, the window starts at 2007-10-01, the earliest searchable date."
},
"time_period_start": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "Start date (YYYY-MM-DD), 2007-10-01 or later. Given alone, the window runs through today (UTC)."
}
},
"type": "object"
},
"limit": {
"default": 10,
"description": "Maximum items to return (1–100)",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"page": {
"default": 1,
"description": "Page number (1-based)",
"maximum": 9007199254740991,
"minimum": 1,
"type": "integer"
}
},
"required": [
"category"
],
"type": "object"
},
"name": "usaspending_spending_by_category",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"category",
"results",
"page_metadata",
"page",
"has_next"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"applied_agency_name": {
"description": "Awarding agency name filter applied",
"type": "string"
},
"applied_keywords": {
"description": "Keyword filters applied (comma-separated)",
"type": "string"
},
"applied_naics_codes": {
"description": "NAICS code filters applied (comma-separated)",
"type": "string"
},
"applied_time_period_end": {
"description": "End date sent (YYYY-MM-DD), including a filled-in end",
"type": "string"
},
"applied_time_period_start": {
"description": "Start date sent (YYYY-MM-DD), including a filled-in start",
"type": "string"
},
"category": {
"description": "Breakdown dimension used",
"type": "string"
},
"error": {
"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. `date_range_inverted`: Both filters.time_period_start and filters.time_period_end were supplied and the start falls after the end. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. Other values are possible when a failure originates below the handler.",
"examples": [
"api_unavailable",
"api_timeout",
"date_range_inverted",
"date_before_earliest"
],
"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"
},
"has_next": {
"description": "Whether there are more pages",
"type": "boolean"
},
"notice": {
"description": "Names a date bound that was filled in because only the other was supplied, and suggests how to broaden filters when results are empty. Absent when neither applies.",
"type": "string"
},
"page": {
"description": "Current page returned",
"type": "number"
},
"page_metadata": {
"additionalProperties": false,
"description": "Pagination metadata",
"properties": {
"has_next": {
"description": "Whether there are more pages",
"type": "boolean"
},
"limit": {
"description": "Items per page",
"type": "number"
},
"page": {
"description": "Current page",
"type": "number"
},
"total": {
"description": "Total items",
"type": "number"
}
},
"required": [
"has_next",
"page",
"limit"
],
"type": "object"
},
"results": {
"description": "Top items in this category by obligation amount",
"items": {
"additionalProperties": false,
"description": "Category item with code, name, and obligation amount",
"properties": {
"amount": {
"description": "Total obligation amount in USD",
"type": "number"
},
"code": {
"description": "Code value (NAICS, PSC, CFDA number, etc.)",
"type": "string"
},
"id": {
"description": "Item identifier (varies by category)",
"type": "string"
},
"name": {
"description": "Item name or description",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total number of items in this category (when available)",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Geographic filters accept FIPS codes and 2-letter state abbreviations — NOT place names. Resolve place names to FIPS codes using a geocoding server (Census or OpenStreetMap) before applying location filters. Chain per-capita results with Census population data for meaningful comparisons.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"filters": {
"description": "Optional filters to scope the spending aggregation",
"properties": {
"agency_name": {
"description": "Awarding agency name filter",
"type": "string"
},
"award_type_codes": {
"description": "Award type codes: A/B/C/D (contracts), IDV_A–IDV_E (IDVs), 02–05 (grants), 06/10 (direct payments), 07/08 (loans), 09/11 (insurance and other assistance), -1 (unspecified). Groups may be mixed here. Omit to aggregate every type.",
"items": {
"type": "string"
},
"type": "array"
},
"keywords": {
"description": "Full-text keyword filter (e.g., [\"cybersecurity\", \"cloud\"])",
"items": {
"type": "string"
},
"type": "array"
},
"naics_codes": {
"description": "NAICS industry codes to include",
"items": {
"type": "string"
},
"type": "array"
},
"recipient_id": {
"description": "Exact recipient hash ID to filter awards",
"type": "string"
},
"time_period_end": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "End of time period (YYYY-MM-DD). Given alone, the period starts at 2007-10-01, the earliest searchable date."
},
"time_period_start": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "Start of time period (YYYY-MM-DD), 2007-10-01 or later. Given alone, the period runs through today (UTC)."
}
},
"type": "object"
},
"geo_layer": {
"description": "Geographic granularity: state (50 states), county (county-level), or district (congressional district)",
"enum": [
"state",
"county",
"district"
],
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-side. A nationwide county query matches over 3,000 areas.",
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"scope": {
"description": "Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based)",
"enum": [
"place_of_performance",
"recipient_location"
],
"type": "string"
},
"subawards": {
"default": false,
"description": "Include subaward data instead of prime award data",
"type": "boolean"
}
},
"required": [
"scope",
"geo_layer"
],
"type": "object"
},
"name": "usaspending_spending_by_geography",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"scope",
"geo_layer",
"results",
"total",
"total_areas_available",
"applied_scope",
"applied_geo_layer",
"area_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"applied_agency_name": {
"description": "Awarding agency name filter applied",
"type": "string"
},
"applied_award_type_default": {
"description": "Disclosure that no filters were supplied, so award_type_codes defaulted to the complete set. Absent when the caller supplied at least one filter.",
"type": "string"
},
"applied_geo_layer": {
"description": "Geographic granularity applied: state, county, or district",
"type": "string"
},
"applied_keywords": {
"description": "Keyword filters applied (comma-separated)",
"type": "string"
},
"applied_naics_codes": {
"description": "NAICS code filters applied (comma-separated)",
"type": "string"
},
"applied_scope": {
"description": "Location scope applied: place_of_performance or recipient_location",
"type": "string"
},
"applied_time_period_end": {
"description": "End of the time period sent (YYYY-MM-DD), including a filled-in end",
"type": "string"
},
"applied_time_period_start": {
"description": "Start of the time period sent (YYYY-MM-DD), including a filled-in start",
"type": "string"
},
"area_count": {
"description": "Number of geographic areas returned",
"type": "number"
},
"cap": {
"description": "The limit that was applied.",
"type": "number"
},
"error": {
"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. `date_range_inverted`: Both filters.time_period_start and filters.time_period_end were supplied and the start falls after the end. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. Other values are possible when a failure originates below the handler.",
"examples": [
"api_unavailable",
"api_timeout",
"date_range_inverted",
"date_before_earliest"
],
"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"
},
"geo_layer": {
"description": "Geographic granularity used",
"type": "string"
},
"notice": {
"description": "How to reach areas omitted by limit, which time-period bound was filled in when only the other was supplied, and how to broaden filters when results are empty. Absent when none applies.",
"type": "string"
},
"results": {
"description": "Spending totals by geographic area",
"items": {
"additionalProperties": false,
"description": "Geographic area with spending totals and optional per-capita data",
"properties": {
"aggregated_amount": {
"description": "Total obligation amount in USD for this geographic area",
"type": "number"
},
"award_count": {
"description": "Number of awards in this area",
"type": "number"
},
"display_name": {
"description": "Human-readable name for the geographic area",
"type": "string"
},
"per_capita": {
"description": "Per-capita obligation amount in USD (aggregated_amount / population)",
"type": "number"
},
"population": {
"description": "Population of the geographic area (when available)",
"type": "number"
},
"shape_code": {
"description": "Geographic identifier (FIPS state code, county FIPS, or district code)",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"scope": {
"description": "Location scope used for aggregation",
"type": "string"
},
"shown": {
"description": "Number of geographic areas returned.",
"type": "number"
},
"total": {
"description": "Number of geographic areas returned",
"type": "number"
},
"total_areas_available": {
"description": "Number of geographic areas the filters matched, before limit was applied",
"type": "number"
},
"truncated": {
"description": "True when the area list was capped at limit.",
"type": "boolean"
},
"truncationCeiling": {
"description": "Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Fetch aggregated federal obligation amounts grouped by fiscal year, fiscal quarter, or fiscal month. All grouping is relative to the US government fiscal year (Oct–Sep), so fiscal month 1 is October, not January. Filter by award type, agency, recipient, keyword, or NAICS code to trace spending trends in a specific area. Returns per-period totals and optional breakdowns by award category (contracts, grants, direct payments, IDVs, loans, other).",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"filters": {
"description": "Filters to scope the time-series aggregation. Defaults to contract awards when omitted.",
"properties": {
"agency_name": {
"description": "Awarding agency name filter",
"type": "string"
},
"award_type_codes": {
"description": "Award type code filters (A/B/C/D, 02–05, etc.). All codes must belong to a single group. When omitted, defaults to contracts (A, B, C, D).",
"items": {
"type": "string"
},
"type": "array"
},
"keywords": {
"description": "Full-text keyword filters",
"items": {
"type": "string"
},
"type": "array"
},
"naics_codes": {
"description": "NAICS code filters",
"items": {
"type": "string"
},
"type": "array"
},
"recipient_id": {
"description": "Exact recipient hash ID filter",
"type": "string"
},
"time_period_end": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "End of the time window (YYYY-MM-DD). Given alone, the window starts at 2007-10-01, the earliest searchable date."
},
"time_period_start": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "Date as YYYY-MM-DD; month and day may be unpadded",
"pattern": "^\\d{4}-\\d{1,2}-\\d{1,2}$",
"type": "string"
}
],
"description": "Start of the time window (YYYY-MM-DD), 2007-10-01 or later. Given alone, the window runs through today (UTC)."
}
},
"type": "object"
},
"group": {
"description": "Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (fiscal month — an ordinal within the fiscal year, where 1 = October)",
"enum": [
"fiscal_year",
"quarter",
"month"
],
"type": "string"
},
"subawards": {
"default": false,
"description": "Aggregate subaward data instead of prime award data",
"type": "boolean"
}
},
"required": [
"group"
],
"type": "object"
},
"name": "usaspending_spending_over_time",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"group",
"results",
"total_periods",
"time_group",
"period_count"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"applied_agency_name": {
"description": "Awarding agency name filter applied",
"type": "string"
},
"applied_keywords": {
"description": "Keyword filters applied (comma-separated)",
"type": "string"
},
"applied_naics_codes": {
"description": "NAICS code filters applied (comma-separated)",
"type": "string"
},
"applied_time_period_end": {
"description": "End of the time window sent (YYYY-MM-DD), including a filled-in end",
"type": "string"
},
"applied_time_period_start": {
"description": "Start of the time window sent (YYYY-MM-DD), including a filled-in start",
"type": "string"
},
"error": {
"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. `date_range_inverted`: Both filters.time_period_start and filters.time_period_end were supplied and the start falls after the end. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. Other values are possible when a failure originates below the handler.",
"examples": [
"api_unavailable",
"api_timeout",
"date_range_inverted",
"date_before_earliest"
],
"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"
},
"group": {
"description": "Time grouping used",
"type": "string"
},
"notice": {
"description": "Names a time-window bound that was filled in because only the other was supplied, and suggests broadening filters when no periods are returned. Absent when neither applies.",
"type": "string"
},
"period_count": {
"description": "Number of time periods returned",
"type": "number"
},
"results": {
"description": "Time-series of obligation totals",
"items": {
"additionalProperties": false,
"description": "Time period row with total obligations and optional award-type breakdowns",
"properties": {
"aggregated_amount": {
"description": "Total obligation amount in USD for this period",
"type": "number"
},
"contracts": {
"description": "Contract obligation amount in USD for this period",
"type": "number"
},
"direct_payments": {
"description": "Direct payment obligation amount in USD for this period",
"type": "number"
},
"grants": {
"description": "Grant obligation amount in USD for this period",
"type": "number"
},
"idvs": {
"description": "IDV (Indefinite Delivery Vehicle) obligation amount in USD for this period",
"type": "number"
},
"loans": {
"description": "Loan obligation amount in USD for this period",
"type": "number"
},
"other": {
"description": "Other financial assistance obligation amount in USD for this period",
"type": "number"
},
"time_period": {
"additionalProperties": false,
"description": "Time period for this row. Populated per the requested grouping: fiscal_year alone, fiscal_year + quarter, or fiscal_year + month.",
"properties": {
"fiscal_year": {
"description": "Fiscal year (e.g., 2024)",
"type": "string"
},
"month": {
"description": "Fiscal month: an ordinal within fiscal_year, 1–12, where 1 = October and 12 = September. Fiscal month 1 of FY2025 is October 2024 — not January.",
"type": "string"
},
"quarter": {
"description": "Fiscal quarter (1–4)",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"time_period"
],
"type": "object"
},
"type": "array"
},
"time_group": {
"description": "Time grouping applied: fiscal_year, quarter, or month",
"type": "string"
},
"total_periods": {
"description": "Number of time periods returned",
"type": "number"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:8bd729d7419cfdd71e780cf59929e8be0cb7cd60c52293c21bed636ae6d477e4 | sha256sum