Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Scored across 18 tools
Each tool targets a distinct resource or aggregation axis: search/get for awards, agencies, recipients, and federal accounts; specialized tools for subawards, transactions, IDVs, and disaster spending; and separate aggregate dimensions for category, geography, and time. The only conceptual overlap is between disaster_spending and the general spending aggregators, but its DEF-code focus and overview dimension keep its purpose clear.
All 18 tools share the usaspending_ prefix and follow a predictable verb_or_concept_noun structure such as search_awards, get_award, and spending_by_category. No mixed casing or vague names; the vocabulary is consistent across resources.
18 tools is above the ideal 3-15 range but appropriate for the broad USAspending domain, which spans awards, agencies, recipients, federal accounts, and multiple spending aggregations. No tool appears redundant or trivial; each covers a distinct operation or resource.
The surface covers the full read-only analytical lifecycle: search and detail for awards, agencies, recipients, and federal accounts; sub-resource exploration for transactions, subawards, IDV children, and award funding; and aggregate spending by category, geography, time, and disaster/emergency funding. Minor gaps such as global subaward search are workaroundable via award-level tools.
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 and sub-agency names, each with its tier and top-tier parent — the agency_name filters take the top-tier name), 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.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Lookup table to search: naics (industry codes), psc (product/service codes, for the psc_codes filter), cfda (Assistance Listing program numbers, for the assistance_listings filter), awarding_agency (agency and sub-agency names), recipient (recipient names). Both filters are taken by usaspending_search_awards and by the filters object of usaspending_spending_by_category, usaspending_spending_by_geography, and usaspending_spending_over_time. | |
| limit | No | 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. | |
| search_text | Yes | Free-text search string — use a description, keyword, or partial code to find matches |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit that was applied, when truncated. |
| type | No | Lookup table searched |
| error | No | Present when the call failed. Absent on success. |
| query | No | Search text sent to the autocomplete API |
| shown | No | Number of results returned, when truncated. |
| total | No | Number of results returned |
| notice | No | How to reach the matches left out when truncated, or — when limit is 500 and all 500 slots filled — that the upstream maximum was reached and more matches may exist. Absent otherwise. |
| results | No | Matching codes and names |
| truncated | No | True when more matches exist beyond the limit and were left out. Absent when every match was returned. |
| lookup_type | No | Lookup table that was searched |
| search_text | No | Search text used |
| result_count | No | Number of matching results returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld, so the safety bar is met structurally. The description still adds non-obvious behavior: that awarding_agency rows carry tier and top-tier parent info and that the agency_name filters consume the top-tier name specifically. Return content is briefly stated, with the output schema carrying the rest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, then the enum walkthrough, then the 'call this before filtering' guidance. Dense but nearly every clause carries information; the type enumeration is slightly long but earns its place by disambiguating five tables.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, 100% parameter coverage, and annotations covering the safety profile, the description supplies everything else an agent needs: the purpose, the selection mechanism, the pre-filter workflow, and downstream consumption of results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description genuinely extends the schema for the required `type` enum by spelling out what each table contains and connecting awarding_agency to the top-tier agency_name filter. It adds no comparable detail for `limit` or `search_text`, which the schema already documents well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('look up valid code values for filter fields by searching free-text descriptions') and enumerates the five lookup tables it resolves. An agent can immediately distinguish it from sibling retrieval tools like usaspending_get_recipient or usaspending_search_awards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit condition for use: 'Call this before filtering awards when you know a description but not the exact code.' That clearly positions it as a pre-filter resolution step, though it never states when not to use it or names an alternative for a given lookup (e.g. usaspending_search_recipients).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100). Applies to the agency, cfda, recipient, and geography dimensions; geography pages through its areas ranked by aggregated_amount, highest first. Ignored for overview. | |
| filters | No | Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography) | |
| dimension | Yes | 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) | |
| spending_type | No | 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. | award |
| Name | Required | Description |
|---|---|---|
| cap | No | recipient: the result-set ceiling the upstream applied. geography: the page size (limit). |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results returned on this page. |
| notice | No | recipient: why the total is a cap and how to bring the set under it. geography: how many areas rank below this page and how to reach them. |
| totals | No | 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. |
| results | No | Breakdown results (empty for overview dimension) |
| overview | No | Top-level overview totals (dimension=overview only) |
| dimension | No | Breakdown dimension returned |
| truncated | No | recipient: true when the upstream capped the reachable result set rather than counting it. geography: true when more areas rank below this page. |
| totalCount | No | Total items for paginated dimensions (when available) |
| current_page | No | Current page (non-overview dimensions) |
| has_next_page | No | Whether there are more pages |
| page_metadata | No | Pagination metadata (non-overview dimensions) |
| spending_type | No | 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 |
| applied_dimension | No | Breakdown dimension applied |
| truncationCeiling | No | geography: the lowest aggregated_amount on this page — no area on a later page has a higher one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, openWorldHint). The description goes beyond them by disclosing that def_codes is required for non-overview dimensions and that the upstream API returns HTTP 422 when omitted, plus where DEF codes can be discovered (get_award account_obligations_by_defc, get_agency def_codes).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences with no filler; the dimension-selection guidance comes before the DEF-code mechanics. It is dense but every sentence carries actionable information, with only minor redundancy between the description and the schema's def_codes note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. The description covers axis selection, the required-filter rule, and the geographic constraint, which is everything needed to invoke this five-parameter tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: the five dimension values are explained in prose, def_codes is tied to a concrete source field in sibling tools, and the DEF-code example for COVID-19 aids selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.)') and enumerates the breakdown axes. It is clearly distinguishable from siblings like usaspending_spending_by_category and usaspending_spending_by_geography because it is scoped to DEF-code disaster funding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states how to pick a breakdown ('Use the dimension parameter to select the breakdown axis') and when DEF codes are needed to isolate an emergency appropriation. It stops short of explicitly naming an alternative tool to use instead when the caller does not want disaster-scoped spending.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year with reported budget data), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdown with obligation and transaction counts for the same fiscal year as the budget totals (the current fiscal year when no budget year is available within 5 seconds); sub_agency_fiscal_year names the year it covers. Accepts exactly one of 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. When the budget or sub-agency request fails, the overview is still returned and unavailable_sections names each missing section with its reason.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list. | |
| agency_slug | No | 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. | |
| toptier_code | No | 3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both. |
| Name | Required | Description |
|---|---|---|
| name | No | Agency full name |
| error | No | Present when the call failed. Absent on success. |
| notice | No | How to page for more sub-agencies when the breakdown is truncated, and which sections failed to load and whether a retry may recover them. Absent when neither applies. |
| mission | No | Agency mission statement |
| website | No | Agency website URL |
| agency_id | No | Internal agency ID |
| def_codes | No | Disaster/Emergency Funding (DEF) codes applicable to this agency |
| fiscal_year | No | Fiscal year the budgetary totals below reflect: the most recent year with reported budget data, which can trail the current fiscal year (a new year has no amounts until the agency first reports in it) |
| abbreviation | No | Agency abbreviation |
| sub_agencies | No | Sub-agency breakdown within this toptier agency (one page) |
| toptier_code | No | 3-digit toptier agency code |
| outlay_amount | No | Total outlays in USD for the fiscal year |
| sub_agency_page | No | Current sub-agency page returned. Absent when the sub-agency request failed. |
| obligated_amount | No | Total amount obligated in USD for the fiscal year |
| sub_agency_total | No | Total sub-agencies across all pages (when available) |
| subtier_agency_count | No | Number of sub-agencies within this toptier agency |
| unavailable_sections | No | Sections omitted because their request failed while the agency overview loaded. Absent when every section loaded. |
| has_more_sub_agencies | No | Whether more sub-agency pages are available. Absent when the sub-agency request failed, since pagination is then unknown. |
| sub_agency_fiscal_year | No | Fiscal year the sub-agency breakdown covers, as upstream reports it: the same year as fiscal_year, or the current fiscal year when no budget year was available within 5 seconds — so it can differ from fiscal_year even when both are present. Absent when the sub-agency request failed, or when upstream reports no year for a breakdown requested without one. |
| sub_agency_page_metadata | No | Pagination metadata for the sub-agency breakdown |
| budgetary_resources_amount | No | Total budgetary resources in USD for the fiscal year |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/idempotentHint already covering the safety profile, the description adds genuinely new behavior: the budget totals come from the most recent fiscal year with reported data, the sub-agency list falls back to the current fiscal year after a 5-second timeout, and partial failures still return the overview with unavailable_sections naming what is missing. That is exactly the non-obvious runtime behavior an agent cannot infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and return contents are front-loaded in the first sentence, and every subsequent sentence carries distinct information (year selection, identifier options, failure semantics). It is dense with nested parentheticals, which costs some readability, but nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, output-schema-backed tool the description covers the remaining unknowns an agent needs: which fiscal year the numbers reflect, how paging works, which identifier forms are acceptable, and how partial failures surface. Nothing required to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions already carry the examples (097, 012, department-of-defense), the pagination semantics, and the 'use either ... not both' rule. The description largely restates this, adding only mild emphasis that exactly one identifier is required, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (fetch) and resource (an agency's fiscal-year overview) and enumerates exactly what comes back: mission, budgetary resources, obligations, outlays, sub-agency count, DEF codes, plus a paginated sub-agency breakdown. It also distinguishes itself from usaspending_list_agencies by positioning that sibling as the source of the identifiers rather than a competitor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear invocation conditions: accepts exactly one of toptier_code or agency_slug, and tells the agent where both appear (usaspending_list_agencies results and award search results). It does not explicitly say when to prefer this over the sibling detail tools, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient identity (UEI, parent organization, business categories), agency hierarchy, period of performance, place of performance, Assistance Listings with the obligation under each, loan face value and subsidy cost for loans, funding account linkages (account_obligations_by_defc), parent IDV information, and subaward count. Use generated_internal_id values from usaspending_search_awards as input. Recipient and parent recipient hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters, and Assistance Listing numbers in its assistance_listings filter. For IDV-category awards (category="idv"), use usaspending_get_idv_awards to list the child contracts and task/delivery orders placed under them.
| Name | Required | Description | Default |
|---|---|---|---|
| award_id | Yes | Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards |
| Name | Required | Description |
|---|---|---|
| fain | No | Federal Award Identification Number (for assistance) |
| piid | No | Procurement Instrument Identifier (for contracts) |
| type | No | Award type code |
| error | No | Present when the call failed. Absent on success. |
| naics | No | NAICS code (contracts) |
| category | No | Award category: contract, idv, grant, loans, direct payment, insurance, or other |
| recipient | No | Recipient details |
| date_signed | No | Date award was signed (YYYY-MM-DD) |
| description | No | Award description |
| parent_award | No | Parent IDV information (contracts only) |
| total_outlays | No | Total outlay amount in USD |
| funding_agency | No | Funding agency hierarchy |
| subaward_count | No | Number of subawards; use with usaspending_get_award_subawards |
| awarding_agency | No | Awarding agency hierarchy |
| total_loan_value | No | Face value of the loan in USD (category "loans" only). A loan reports its value here, not in total_obligation, which is often 0. |
| total_obligation | No | Total obligation amount in USD |
| type_description | No | Human-readable award type |
| total_subsidy_cost | No | Estimated cost to the government of the loan subsidy in USD (category "loans" only) |
| assistance_listings | No | Every Assistance Listing (CFDA program) funding the award, in upstream order; absent for contracts and IDVs |
| place_of_performance | No | Place of performance; absent when upstream reports no location fields |
| period_of_performance | No | Period of performance dates |
| product_or_service_code | No | Product or service code (contracts) |
| generated_unique_award_id | No | Generated unique award ID |
| base_and_all_options_value | No | Base and all options value in USD (contracts) |
| account_obligations_by_defc | No | Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety and idempotency profile is covered. The description's added behavioral content is mostly a restatement of the return payload (loan face value, subaward count, funding account linkages), which is already captured by the output schema, and it says nothing about auth requirements, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence and the routing guidance is useful and non-redundant. The middle sentence is a very long enumeration of returned fields that partly duplicates the output schema, which costs some efficiency, but the overall ordering (what it does → input source → related tools) is well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with a full output schema and complete annotations, the description supplies everything an agent needs: the exact input source, the special-case branch for IDV-category awards, and the downstream tools for the IDs it returns. Nothing required for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single award_id parameter, including the example ID format and the generated_internal_id provenance. The description's input guidance largely repeats that schema text, so it adds little beyond the documented baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch full details of a federal award by its generated unique award ID') and immediately scopes what 'full details' means via an enumeration of the returned data. It is clearly distinguishable from siblings like usaspending_get_award_transactions or usaspending_get_award_subawards, which each return a subset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit input source ('Use generated_internal_id values from usaspending_search_awards'), plus concrete routing rules: recipient hashes go to usaspending_get_recipient, NAICS codes and Assistance Listing numbers back into usaspending_search_awards, and IDV-category awards must use usaspending_get_idv_awards instead. Both when-to-use and when-not-to-use are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100) | |
| award_id | Yes | 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 |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — the award_id may not exist or may have no account linkage. Absent when results are present. |
| results | No | Federal accounts funding this award |
| award_id | No | Award ID queried |
| totalCount | No | Total number of funding accounts across all pages (when available) |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of funding accounts |
| page_metadata | No | Pagination metadata |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses a specific edge case: 'An award_id that does not exist returns an empty list rather than an error.' It also details the output format (federal_account in AGENCY-MAIN format), which is behavior not captured by annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet dense with information. Each sentence serves a purpose: purpose, output format, ID requirement, differentiation from sibling, and edge-case behavior. There is no filler, and key details are front-loaded (the core function appears first).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema and annotations, the description covers all essential aspects: what it returns, how to source the parameter, how it differs from a sibling, and error behavior. It also explains the chaining use case. Nothing critical is missing for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for award_id by specifying it must be a generated_unique_award_id and providing sources (generated_internal_id from search or generated_unique_award_id from get_award). This goes beyond the schema's example, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource pair: 'List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it.' It further distinguishes itself from the sibling usaspending_get_award's account_obligations_by_defc by noting the different breakdown (by account vs. by DEFC), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use and when-not guidance is provided: the description names an alternative (usaspending_get_award account_obligations_by_defc) and explains the key difference. It also instructs on how to obtain the required award_id (from usaspending_search_awards or usaspending_get_award) and suggests chaining the output to usaspending_get_federal_account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| sort | No | Sort field for subawards | action_date |
| limit | No | Maximum subawards per page (1–100) | |
| order | No | Sort direction | desc |
| award_id | Yes | Generated unique award ID (generated_internal_id from usaspending_search_awards) |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present. |
| results | No | List of subawards under this prime award |
| award_id | No | Prime award ID queried |
| totalCount | No | Total subaward count across all pages (when available) |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of subawards |
| page_metadata | No | Pagination metadata |
| prime_award_id | No | Prime award ID whose subawards were listed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. The description adds meaningful behavioral context: it clarifies that the tool returns a list of subawards, reveals the sub-contractor layer, and highlights the need to check subaward_count first. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence front-loads the core purpose and output contents; the second adds a practical usage note. Structure is clean and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, an output schema, and strong annotations, the description covers purpose, usage precondition, and expected row fields. It does not explicitly mention pagination, but the schema's page/limit parameters handle that. The check-subaward_count hint adds operational completeness. Adequate for an idempotent read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters already have clear descriptions. The description adds only marginal parameter-related value: it implies award_id refers to a 'prime federal award' and mentions row fields that map to sort options, but does not enhance understanding beyond the schema's parameter documentation. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and a specific resource ('subaward contracts or grants under a prime federal award'). It goes further to explain the purpose ('Reveals the sub-contractor or sub-grantee layer') and enumerates the fields returned per row. This distinguishes it from sibling tools like usaspending_get_award (prime award details) and usaspending_get_award_transactions (transaction layer).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage precondition: 'Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.' This names the exact sibling tool to use and the condition that gates this tool. It does not compare with other award tools like transactions, but the purpose clause already narrows the use case sufficiently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| sort | No | Sort field for transactions | action_date |
| limit | No | Maximum transactions per page (1–100) | |
| order | No | Sort direction | desc |
| award_id | Yes | Generated unique award ID (generated_internal_id from usaspending_search_awards) |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present. |
| results | No | List of transactions for this award |
| award_id | No | Award ID queried |
| totalCount | No | Total transaction count across all pages (when available) |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of transactions |
| page_metadata | No | Pagination metadata |
| queried_award_id | No | Award ID whose transactions were listed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating operation. The description adds value by explaining what a transaction represents and why it's useful for tracing award history, which is behavior beyond mere read-only status. It does not contradict the annotations and provides semantic context without repeating the hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Only three sentences, with the core purpose stated in the first sentence. Every sentence contributes: the first defines the operation, the second explains what a transaction is, the third gives the use case and ID source. No word wasted, and the most critical information (what and why) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a straightforward list operation, the description is complete. The output schema is present (context signal) so return structure is handled elsewhere. The description covers the conceptual model (what a transaction is), the use case, and the provenance of the required ID. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — all five parameters have descriptions in the schema, including the source of award_id. The description reinforces the award_id source but does not add meaningful new information beyond what the schema already provides. With full schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('transactions on a federal award'), and the nature of those transactions ('change events — obligation modifications, performance period extensions, scope changes'). This distinguishes it from sibling tools like get_award or get_award_subawards, which target different award-related data. The mention of tracing spending history further clarifies the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case ('trace the spending history and obligation changes over the life of an award') and specifies the source of the required parameter ('Award IDs come from usaspending_search_awards'). It does not explicitly state when NOT to use this tool or mention alternatives, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| account_code | Yes | 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. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| children | No | 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. |
| bureau_name | No | Bureau name within the agency |
| fiscal_year | No | Fiscal year of the financial data |
| account_title | No | Full account title |
| agency_identifier | No | Agency identifier code |
| main_account_code | No | Main account code |
| parent_agency_name | No | Managing parent agency name |
| federal_account_code | No | Federal account code |
| total_obligated_amount | No | Total obligated amount in USD |
| total_budgetary_resources | No | Total budgetary resources in USD |
| total_gross_outlay_amount | No | Total gross outlay amount in USD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds behavioral context by detailing the returned data structure (total obligations, gross outlays, budgetary resources, and per-TAS breakdown in children). It does not contradict annotations and enriches the agent's understanding of what the tool returns beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficient. It leads with the core purpose, adds a brief domain context sentence, then provides input sourcing/format, and ends with a clear routing to an alternative. No fluff, every sentence earns its place, and it's well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (has output schema: true) and a single well-documented parameter, the description is complete. It explains the input format, how to obtain it, what data comes back, the domain significance, and the alternative for more granular breakdowns. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter account_code, so the baseline is 3. The description adds extra value by explicitly stating the format (AGENCY-MAIN, e.g., 097-0100) and pointing to the source tools that return this value, which is beyond the schema's description. This helps the agent form the correct input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action – 'Fetch a federal account's budget data' – and enumerates the exact data types: total obligations, gross outlays, budgetary resources, and per-TAS breakdown in children. It also distinguishes itself from the sibling tool usaspending_get_federal_account_breakdown by noting the alternative for obligations by program activity/object class. This clearly separates it from other federal-account tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent where to obtain account codes: from usaspending_search_federal_accounts (via account_number) or usaspending_get_award_federal_accounts (via federal_account). It also provides an alternative condition: 'For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.' This is clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100) | |
| dimension | Yes | Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased) | |
| account_code | Yes | 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. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | 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. |
| results | No | Breakdown rows for the requested dimension |
| dimension | No | Breakdown dimension returned |
| totalCount | No | Total number of breakdown rows across all pages (when available) |
| account_code | No | Federal account code queried |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of breakdown rows |
| page_metadata | No | Pagination metadata |
| applied_dimension | No | Breakdown dimension applied |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: pagination with an 'honest total count' and the axis options. This exceeds the minimal bar set by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences of dense, front-loaded content. The purpose comes first, alternatives are embedded, and no filler exists. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a complete schema (100% coverage), an output schema for return shape, and annotations covering safety, the description covers the remaining context: pagination behavior, total count, and routing to the correct sibling tool. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the distinction between the two dimension values and mentions the account_code format and source tools, but this information is largely duplicated in the schema's property descriptions. No new semantic detail is added beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Fetch a federal account's obligations') and immediately defines the two breakdown axes, distinguishing this from siblings. It also names the alternative tool for metadata/totals, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (for breakdown by dimension) and when not to ('For the account's own metadata and top-level totals, use usaspending_get_federal_account'). It also tells the agent exactly where to obtain account codes from three sibling tools, leaving no ambiguity about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| sort | No | Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date) | obligated_amount |
| type | No | Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVs | child_awards |
| limit | No | Maximum results per page (1–100) | |
| order | No | Sort direction | desc |
| award_id | Yes | 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 |
| Name | Required | Description |
|---|---|---|
| cap | No | The per-page limit that was applied, when truncated. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of child awards returned on this page, when truncated. |
| notice | No | How to continue when truncated, or a recovery hint when results are empty — the award may have no children of the requested type. Absent otherwise. |
| results | No | Child awards placed under this IDV |
| award_id | No | Parent IDV award ID queried |
| truncated | No | True when the upstream reports more child awards beyond this page. Absent on a full page the upstream marks as last — has_next_page still says whether to request another. |
| current_page | No | Current page returned |
| has_next_page | No | Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none. |
| page_metadata | No | Pagination metadata (no total count available from this endpoint) |
| parent_award_id | No | Parent IDV award ID whose children were listed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and closed-world behavior, so safety is covered. The description adds genuinely useful workflow context — the chaining relationship to usaspending_get_award and the requirement that award_id be the parent IDV's generated_unique_award_id — which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose first, then the chaining/return-value guidance, then the parameter sourcing. No filler and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists and the annotations cover safety, so the description's burden is workflow context, which it fully addresses: how to source the required ID and where results lead. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying that award_id must be the generated_unique_award_id of the parent IDV, its example format, and both source tools — useful disambiguation the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('child contracts and task/delivery orders placed under an IDV'), and even clarifies the semantic hierarchy (parent IDV vs children). This is clearly distinguishable from siblings like usaspending_get_award, which returns full detail rather than children.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives strong context: explains where to obtain the award_id (usaspending_search_awards or usaspending_get_award) and where each returned row chains to (usaspending_get_award). It also notes that IDV category awards from get_award have children accessible here. It stops short of explicitly stating when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are UUID hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Totals cover the trailing 12 months unless fiscal_year selects one fiscal year, and period names the window. For a recipient's totals by award type, use usaspending_spending_over_time with filters.recipient_id and award_type_codes. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.
| Name | Required | Description | Default |
|---|---|---|---|
| fiscal_year | No | Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months. | |
| recipient_id | Yes | Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award |
| Name | Required | Description |
|---|---|---|
| uei | No | Unique Entity Identifier (SAM.gov) |
| duns | No | DUNS number (legacy) |
| name | No | Recipient legal business name |
| error | No | Present when the call failed. Absent on success. |
| period | No | Window the totals cover: FY<year> when fiscal_year was given, otherwise "trailing 12 months" |
| location | No | Recipient address |
| parent_uei | No | Parent organization UEI |
| parent_name | No | Parent organization name |
| recipient_id | No | Recipient hash ID |
| business_types | No | Business type codes |
| alternate_names | No | Alternate business names |
| recipient_level | No | Hierarchy level: P = parent, C = child, R = standalone |
| total_transactions | No | Total number of award transactions over period |
| total_transaction_amount | No | Total transaction (award) amount in USD over period, across all award types |
| total_face_value_loan_amount | No | Total face value of loans in USD over period |
| total_face_value_loan_transactions | No | Number of face-value loan transactions over period |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: totals default to the trailing 12 months unless fiscal_year is set, period names the window, and the UUID level-suffix semantics (-P/-C/-R) explain ID structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and return contents, then parameters, then the alternative tool. Dense but every clause carries information; the SAM.gov/SEC EDGAR note is a slight extension beyond what's needed to invoke the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained, and the description still summarizes the profile contents. It covers ID provenance, defaults, and alternatives. Adequate for a single-required-param read tool, though it could say nothing is mutated by the fetch.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the fiscal_year semantics are already in the schema, so the baseline would be 3. The description adds meaning beyond the schema by decoding the recipient_id level suffix (-P parent, -C child, -R standalone) and noting that UEI/DUNS values can cross-reference external sources.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Fetch') and resource ('recipient's full profile') and enumerates what the profile contains (address, business type codes, parent org, alternate names, totals). It also differentiates itself from siblings by naming usaspending_search_recipients, usaspending_get_award, and usaspending_spending_over_time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent to usaspending_spending_over_time when the goal is totals by award type, and indicates the ID originates from search_recipients or get_award. It stops short of stating when-not to use this tool, but the alternative routing is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount | agency_name |
| order | No | Sort direction: asc or desc | asc |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| total | No | Total number of agencies returned |
| results | No | List of top-tier federal agencies with budget and obligation data |
| agency_count | No | Total number of top-tier federal agencies returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context: it returns data for the current fiscal year only, lists the specific data elements, and frames the tool as the initial navigation step. This goes beyond merely restating the read-only nature, though it does not mention pagination or limits—minor given the output schema likely describes the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the core purpose and output content; the second provides critical usage context by naming downstream tools. Every sentence earns its keep.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional sort parameters and an output schema, the description is complete. It tells the agent exactly what will be returned, scopes the data to the current fiscal year, and explains how it fits into the broader toolchain. Required parameters are none, so no input gaps exist. The output schema covers return structure, so the description doesn't need to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'sort' and 'order' parameters have clear enum values, defaults, and descriptions in the schema. The tool description does not add any extra parameter semantics beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a precise resource ('all top-tier federal agencies'), and the exact fields returned (toptier codes, agency slugs, budget authority, obligation totals). It also explicitly distinguishes itself from usaspending_get_agency by positioning itself as the entry point for agency navigation, so an agent can clearly tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool as the entry point for agency navigation and notes that the toptier codes and agency slugs it returns are required inputs for usaspending_get_agency and agency-based filters. This gives clear when-to-use guidance and implies when not to use it (i.e., when you already have an agency identifier and need details).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search federal awards by keyword, recipient, agency, award type, NAICS code, assistance listing (CFDA) number, PSC, DEF code, 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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 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. | |
| sort | No | 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. | |
| limit | No | Maximum results per page (1–100) | |
| order | No | Sort direction | desc |
| filters | No | 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 rejected — this endpoint silently ignores it; filter by recipient via recipient_name. | |
| keyword | No | Full-text search across award descriptions, recipient names, and place names | |
| def_codes | No | Filter by Disaster Emergency Fund Codes (DEF), e.g. ["Z"], or ["L", "M", "N", "O", "P"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts. | |
| psc_codes | No | Filter by Product and Service Codes (PSC), e.g. ["Y1NE"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it ("Y1" covers "Y1NE"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes. | |
| agency_name | No | Filter to one awarding agency by its top-tier name (e.g., "Department of Defense"). Top-tier only: a sub-agency name matches no awards. Take the value from toptier_name in usaspending_autocomplete_filters type=awarding_agency — for a sub-agency that is its parent, so results cover the whole department. | |
| naics_codes | No | Filter by NAICS industry codes (e.g., ["541512"]). Use usaspending_autocomplete_filters type=naics to look up codes. | |
| time_period | No | Filter awards by date range (action date). Both blank means no date filter; one blank end is filled and named in the notice. | |
| recipient_name | No | 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. | |
| location_filter | No | Filter by place of performance. Takes codes, not place names — use a geocoding server to resolve names to codes first. Blank fields are ignored, and an all-blank object is no location filter. The location sent is echoed as applied_location. | |
| award_type_codes | No | 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. | |
| assistance_listings | No | Filter by Assistance Listing (CFDA) program numbers, e.g. ["15.507"]: 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 matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers. | |
| last_record_unique_id | No | Keyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value. | |
| last_record_sort_value | No | 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. |
| Name | Required | Description |
|---|---|---|
| cap | No | Per-page cap (limit) applied to this page, when truncated. |
| page | No | Current page number returned |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of awards returned on this page, when truncated. |
| notice | No | 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. |
| results | No | Matching award summaries |
| has_next | No | Whether more results may remain — set on a full page even when the upstream flag reports none. |
| truncated | No | True when the upstream reports more results beyond this page (continue via page or the cursor). Absent on a full page the upstream marks as last, including every page past a 10,000-result offset where the upstream stops reporting continuation — has_next still says whether to request another. |
| page_metadata | No | Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page. |
| applied_keyword | No | Keyword filter applied to this search |
| applied_location | No | Place of performance location sent, as normalized (e.g. country=USA, state=NM, county=049) |
| applied_def_codes | No | DEF codes sent, uppercased (comma-separated) |
| applied_psc_codes | No | PSC codes sent, uppercased (comma-separated) |
| upstream_messages | No | 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. |
| applied_agency_name | No | Awarding agency name filter applied |
| applied_naics_codes | No | NAICS codes filter applied (comma-separated) |
| applied_time_period_end | No | End of the date range sent (YYYY-MM-DD), including a filled-in end |
| applied_time_period_start | No | Start of the date range sent (YYYY-MM-DD), including a filled-in start |
| applied_assistance_listings | No | Assistance Listing numbers filter applied (comma-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered; the description adds genuinely non-obvious traits — ranked result ordering, loan rows substituting loan value/subsidy cost/issue date for award amount/dates, a 2007-10-01 earliest date, and a 90-day DoD contract publication lag. It stays silent on pagination/cursor behavior and rate limits, which is the main remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose, then return shape, then the code-group lookup table, then date/freshness rules — a logical scan order with no filler sentences. The award-type enumeration is dense and slightly list-like, but each clause carries information an agent needs to build a valid call.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with nested filter objects and an output schema, the description covers scope, return contents, code vocabularies, date formats, and data-freshness caveats. Sibling lookups (usaspending_autocomplete_filters) and pagination details are handled in the schema, so nothing essential to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter in depth; per the rubric this sets the baseline at 3. The description consolidates the valid award-type code groupings and restates the ISO 8601 date rule, but both already live in the schema, so it adds little semantic value beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Search federal awards') and enumerates the filterable dimensions (keyword, recipient, agency, award type, NAICS, CFDA, PSC, DEF, location, date), which is far more than the title conveys. It also distinguishes itself from siblings by naming usaspending_get_award as the follow-up for the generated award IDs it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as the entry-point search whose output feeds usaspending_get_award, giving an agent a usable workflow context. It does not, however, state exclusions such as when to prefer usaspending_get_idv_awards, usaspending_spending_by_category, or usaspending_search_recipients, so the routing to alternatives is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100) | |
| keyword | No | Filter accounts by name or title keyword (e.g., "defense", "transportation") | |
| sort_field | No | Field to sort results by | budgetary_resources |
| sort_direction | No | Sort direction | desc |
| agency_identifier | No | 3-digit agency identifier code (e.g., "097" for Department of Defense). Use usaspending_list_agencies to look up codes. |
| Name | Required | Description |
|---|---|---|
| page | No | Current page number returned |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present. |
| results | No | Matching federal accounts |
| has_next | No | Whether there are more pages of results |
| totalCount | No | Total number of matching accounts across all pages (when available) |
| page_metadata | No | Pagination metadata |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to restate those. It adds behavioral value by specifying the returned fields (account numbers, names, managing agencies, budgetary resources) and the intended chaining to get_federal_account. This gives the agent insight into the result shape and how to proceed, which is helpful beyond mere annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The primary purpose is front-loaded, followed by two directed usage notes for related tools. Every sentence earns its place, and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema and 6 optional parameters, the description covers the essential workflow: searching, retrieving results, and chaining to related tools. It doesn't explicitly address pagination or sorting, but the schema and defaults handle that. For a search tool, this description is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description reinforces the agency_identifier parameter by referencing usaspending_list_agencies for code lookup, which adds a hint about valid values. However, it does not add syntax or format details beyond what the schema provides, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists and keyword-searches federal accounts by agency identifier or title keyword, which is a specific verb+resource. It also distinguishes itself from the closely related usaspending_get_federal_account (which retrieves full details for a specific account) and usaspending_list_agencies (which returns agency identifiers). The purpose is unambiguous and separates it from other search tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to use usaspending_get_federal_account for full budget detail after obtaining an account_number, and to use usaspending_list_agencies to look up agency_identifier codes. While it does not explicitly state when not to use this tool (e.g., vs. searching awards), the context of federal accounts is clear. The guidance is practical and linked to the workflow, earning a strong score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) — request the next page to retrieve matches beyond the first | |
| limit | No | Maximum results per page (1–100) | |
| keyword | Yes | Name, UEI, DUNS, or keyword to search for — partial matches are supported | |
| award_type | No | Filter by award type category to scope the total amounts returned |
| Name | Required | Description |
|---|---|---|
| page | No | Current page number returned |
| error | No | Present when the call failed. Absent on success. |
| notice | No | 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. |
| results | No | Matching recipients |
| has_next | No | Whether there are more pages of results |
| totalCount | No | Total matching recipients across all pages |
| page_metadata | No | Pagination metadata — page through with the page input to reach later matches |
| recipient_count | No | Number of matching recipients returned on this page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and idempotentHint, so the safety profile is known. The description adds behavioral nuance beyond annotations: pagination mechanics (use page, page_metadata.total), return fields, and hierarchy level definitions (P, C, R). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. Each sentence serves a purpose: core search action, returned fields, pagination, and hierarchical level explanation. No wasted words; ideal length for an agent to quickly parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which covers return values), the description covers essential aspects: what to search, pagination behavior, and hierarchy codes. It also references the companion tool. Minor gaps like error handling or rate limits are not documented, but they are not required given the annotations and output schema. Complete for typical agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds marginal semantics (e.g., 'partial matches are supported' is already in schema; pagination note aligns with page parameter but is more behavioral). No new parameter-level meaning is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Search for organizations or individuals receiving federal funds' by name, UEI, or DUNS. It distinguishes itself from siblings like usaspending_get_recipient by explicitly noting returned hash IDs feed into that tool. Purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States clear context: search for recipients by identifier and that results are paginated. Mentions companion usaspending_get_recipient for full profiles, implying a follow-up path. However, it doesn't explicitly state when NOT to use this tool or compare with other search siblings (e.g., usaspending_search_awards), so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, or date range. Chain NAICS, PSC, and CFDA codes back into these filters, into usaspending_search_awards filters, or into usaspending_autocomplete_filters lookups. recipient_duns rows carry recipient_id, which opens the recipient profile in usaspending_get_recipient, and uei.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum items to return (1–100) | |
| filters | No | Optional filters to scope the aggregation | |
| category | Yes | Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), or recipient_duns (recipients) |
| Name | Required | Description |
|---|---|---|
| page | No | Current page returned |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Names a date bound that was filled in because only the other was supplied, and — when results are empty — names any Assistance Listing, PSC, or DEF codes sent and suggests how to broaden filters. Absent when neither applies. |
| results | No | Top items in this category by obligation amount |
| category | No | Breakdown dimension used |
| has_next | No | Whether there are more pages |
| totalCount | No | Total number of items in this category (when available) |
| page_metadata | No | Pagination metadata |
| applied_keywords | No | Keyword filters applied (comma-separated) |
| applied_def_codes | No | DEF codes sent, uppercased (comma-separated) |
| applied_psc_codes | No | PSC codes sent, uppercased (comma-separated) |
| applied_agency_name | No | Awarding agency name filter applied |
| applied_naics_codes | No | NAICS code filters applied (comma-separated) |
| applied_time_period_end | No | End date sent (YYYY-MM-DD), including a filled-in end |
| applied_time_period_start | No | Start date sent (YYYY-MM-DD), including a filled-in start |
| applied_assistance_listings | No | Assistance Listing numbers sent (comma-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld, so the bar is lower, and the description adds non-obvious behavior: results are "top items with obligation amounts" and recipient_duns rows carry recipient_id and uei. It does not mention pagination over the result set, but the schema covers page/limit defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose, then return shape, then filters, then chaining — a logical order with no filler sentences. The filter enumeration partially duplicates the schema, costing a little efficiency, but every sentence is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present the description needn't explain return values, and it correctly focuses on dimension choice, filtering, and cross-tool chaining. Only a note on result pagination/ordering is missing, which is a minor gap given the page/limit parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already carries field-level semantics; the description only restates the filterable categories and adds a cross-tool chaining note. No syntax or format detail beyond what the schema provides, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a specific verb+resource (aggregate federal spending) and enumerates the grouping dimensions, matching the category enum. It is clearly distinguishable from sibling aggregators like usaspending_spending_by_geography and usaspending_spending_over_time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the analytical use case ("useful for trend and breakdown analysis") and gives explicit routing guidance: chain NAICS/PSC/CFDA codes into these filters, into usaspending_search_awards, or into usaspending_autocomplete_filters, and recipient_duns output into usaspending_get_recipient. It does not state when NOT to use it versus the other spending_* aggregators, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Filter by keyword, award type, agency, recipient, NAICS code, Assistance Listing, PSC, DEF code, or date range. Areas are ranked by obligation and capped at limit; to retrieve specific areas, including ones ranked past the cap, list their codes in shape_codes — a 2-letter postal code for state, a 5-digit state + county FIPS code for county, or a 4-digit state FIPS + district number for district — NOT place names. Resolve place names to these codes using a geocoding server (Census or OpenStreetMap) first. Chain per-capita results with Census population data for meaningful comparisons.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 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; use shape_codes to retrieve one ranked past the cap. | |
| scope | Yes | Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based) | |
| filters | No | Optional filters to scope the spending aggregation | |
| geo_layer | Yes | Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district) | |
| subawards | No | Include subaward data instead of prime award data | |
| shape_codes | No | Return only these areas (1–500 codes), in the shape_code form this tool returns for geo_layer: 2-letter postal code for state ("NY"), 5-digit state + county FIPS for county ("36117" is Wayne County, NY), or 4-digit state FIPS + 2-digit district number for district ("3623" is NY-23, "5600" is Wyoming's at-large seat). Selection runs over every area the filters matched, so it reaches areas ranked past limit; selected areas stay ranked by aggregated_amount and capped at limit. A code that matches no area is named in the notice. |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit that was applied. |
| error | No | Present when the call failed. Absent on success. |
| scope | No | Location scope used for aggregation |
| shown | No | Number of geographic areas returned. |
| total | No | Number of geographic areas returned |
| notice | No | How to reach areas omitted by limit, which shape_codes matched no area, which time-period bound was filled in when only the other was supplied, and — when the filters matched no area — any Assistance Listing, PSC, or DEF codes sent and how to broaden filters. Absent when none applies. |
| results | No | Spending totals by geographic area |
| geo_layer | No | Geographic granularity used |
| truncated | No | True when the area list was capped at limit. |
| area_count | No | Number of geographic areas returned |
| applied_scope | No | Location scope applied: place_of_performance or recipient_location |
| applied_keywords | No | Keyword filters applied (comma-separated) |
| applied_def_codes | No | DEF codes sent, uppercased (comma-separated) |
| applied_geo_layer | No | Geographic granularity applied: state, county, or district |
| applied_psc_codes | No | PSC codes sent, uppercased (comma-separated) |
| truncationCeiling | No | Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones. |
| applied_agency_name | No | Awarding agency name filter applied |
| applied_naics_codes | No | NAICS code filters applied (comma-separated) |
| applied_shape_codes | No | Area codes listed in shape_codes, letters uppercased and duplicates removed (comma-separated) |
| total_areas_available | No | Number of geographic areas the filters matched, before shape_codes selection and limit were applied |
| applied_time_period_end | No | End of the time period sent (YYYY-MM-DD), including a filled-in end |
| applied_time_period_start | No | Start of the time period sent (YYYY-MM-DD), including a filled-in start |
| applied_award_type_default | No | Disclosure that no filters were supplied, so award_type_codes defaulted to the complete set. Absent when the caller supplied at least one filter. |
| applied_assistance_listings | No | Assistance Listing numbers sent (comma-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, open-world behavior, but the description adds genuinely new traits: results are ranked by obligation and capped, the upstream endpoint is unpaginated, areas ranked past the cap remain retrievable via shape_codes, and unmatched codes are surfaced in a notice. These are operational behaviors the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads purpose in the first sentence and orders the remaining detail logically (filters, ranking/cap, code formats, geocoding, chaining). Dense but every sentence carries actionable content; the multi-clause code-format sentence is the only slightly heavy spot.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-filter aggregation tool with an output schema already documenting return values, the description covers the non-obvious gaps: scope selection, ranking/cap behavior, code resolution, and how to reach results past the cap. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, and the description earns above that by clarifying shape_codes semantics (exact code formats per layer, 'NOT place names', geocoding prerequisite) and the limit/shape_codes interaction for reaching areas beyond the cap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Aggregate) and resource (federal spending) with explicit granularities (state, county, congressional district), which cleanly separates it from siblings like usaspending_spending_by_category and usaspending_spending_over_time.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear use cases (per-capita analysis, regional comparisons, mapping) and explains the crucial choice between relying on limit-ranked output versus passing explicit shape_codes, including the prerequisite of resolving place names via a geocoding server first. It never explicitly names a sibling alternative to route to, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, NAICS code, Assistance Listing, PSC, or DEF code to trace spending trends in a specific area; award types default to contracts. Returns per-period totals and optional breakdowns by award category (contracts, grants, direct payments, IDVs, loans, other).
| Name | Required | Description | Default |
|---|---|---|---|
| group | Yes | 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) | |
| filters | No | Filters to scope the time-series aggregation. Defaults to contract awards when omitted. | |
| subawards | No | Aggregate subaward data instead of prime award data |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| group | No | Time grouping used |
| notice | No | Names a time-window bound that was filled in because only the other was supplied, and — when no periods are returned — names any Assistance Listing, PSC, or DEF codes sent and suggests broadening filters. Absent when neither applies. |
| results | No | Time-series of obligation totals |
| time_group | No | Time grouping applied: fiscal_year, quarter, or month |
| period_count | No | Number of time periods returned |
| total_periods | No | Number of time periods returned |
| applied_keywords | No | Keyword filters applied (comma-separated) |
| applied_def_codes | No | DEF codes sent, uppercased (comma-separated) |
| applied_psc_codes | No | PSC codes sent, uppercased (comma-separated) |
| applied_agency_name | No | Awarding agency name filter applied |
| applied_naics_codes | No | NAICS code filters applied (comma-separated) |
| applied_time_period_end | No | End of the time window sent (YYYY-MM-DD), including a filled-in end |
| applied_time_period_start | No | Start of the time window sent (YYYY-MM-DD), including a filled-in start |
| applied_assistance_listings | No | Assistance Listing numbers sent (comma-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, openWorld), so the description's real value is the domain behavior it adds: fiscal-year alignment (Oct–Sep, fiscal month 1 = October), the default of contracts when award types are omitted, and the shape of the return (per-period totals plus optional award-category breakdowns). It stops short of mentioning the subawards=true aggregation mode that the schema exposes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core grouping operation and the fiscal-year caveat an agent could easily get wrong. No filler; each clause carries either scope, a non-obvious default, or return shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't explain return values, yet it still summarizes them usefully. The one real gap is that the boolean subawards toggle — which changes what is being aggregated — goes unmentioned in prose, though the schema documents it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds interpretive value on top: it stresses that all grouping is fiscal rather than calendar and that fiscal month 1 is October, and it restates the contract default for award_type_codes. The subawards parameter is not addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — aggregated federal obligation amounts grouped by fiscal_year, quarter, or month — and the time-grouping axis inherently separates it from sibling aggregations like spending_by_category and spending_by_geography. An agent can tell what this returns without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives the intended goal ('trace spending trends in a specific area') and enumerates the available filter dimensions, which implies when to reach for it, but never names or excludes an alternative sibling tool (e.g. spending_by_category for categorical splits). Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
usaspending_autocomplete_filters13 fields changedInput schema / properties / type / descriptionPrevious value: -"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)"New value: +"Lookup table to search: naics (industry codes), psc (product/service codes, for the psc_codes filter), cfda (Assistance Listing program numbers, for the assistance_listings filter), awarding_agency (agency and sub-agency names), recipient (recipient names). Both filters are taken by usaspending_search_awards and by the filters object of usaspending_spending_by_category, usaspending_spending_by_geography, and usaspending_spending_over_time."Output schema / properties / cap / descriptionPrevious value: -"The limit that was applied."New value: +"The limit that was applied, when truncated."Output schema / properties / noticeAdded value: +{
+ "description": "How to reach the matches left out when truncated, or — when limit is 500 and all 500 slots filled — that the upstream maximum was reached and more matches may exist. Absent otherwise.",
+ "type": "string"
+}Output schema / properties / results / items / descriptionPrevious value: -"Matched entry — code/name for code lookups, name plus optional UEI/DUNS for recipients"New value: +"Matched entry — code/name for code lookups, name with tier and top-tier parent for agencies, name plus optional UEI/DUNS for recipients"Output schema / properties / results / items / properties / abbreviationAdded value: +{
+ "description": "awarding_agency only: the matched agency's own abbreviation, when it has one",
+ "type": "string"
+}Output schema / properties / results / items / properties / code / descriptionPrevious value: -"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"New value: +"Code value (NAICS code, PSC code, or Assistance Listing/CFDA number); use this in filter parameters — an Assistance Listing number goes in usaspending_search_awards assistance_listings. Agency rows carry toptier_code instead."Output schema / properties / results / items / properties / idRemoved value: -{
- "description": "Numeric or string ID (for the awarding_agency type)",
- "type": "string"
-}Output schema / properties / results / items / properties / name / descriptionPrevious value: -"Human-readable name or description"New value: +"Human-readable name or description; for awarding_agency, the matched agency's own name, which for a sub-agency differs from toptier_name"Output schema / properties / results / items / properties / tierAdded value: +{
+ "description": "awarding_agency only: toptier for a department-level agency, subtier for a component under one",
+ "enum": [
+ "toptier",
+ "subtier"
+ ],
+ "type": "string"
+}Output schema / properties / results / items / properties / toptier_codeAdded value: +{
+ "description": "awarding_agency only: the 3-digit top-tier agency code, accepted by usaspending_get_agency",
+ "type": "string"
+}Output schema / properties / results / items / properties / toptier_nameAdded value: +{
+ "description": "awarding_agency only: the top-tier agency name — the value the agency_name filters on usaspending_search_awards, usaspending_spending_by_category, usaspending_spending_by_geography, and usaspending_spending_over_time take. Those filters are top-tier only, so a sub-agency filters at its parent and the results cover the whole department.",
+ "type": "string"
+}Output schema / properties / shown / descriptionPrevious value: -"Number of results returned."New value: +"Number of results returned, when truncated."Output schema / properties / truncated / descriptionPrevious value: -"True when results were capped at the limit."New value: +"True when more matches exist beyond the limit and were left out. Absent when every match was returned."usaspending_disaster_spending8 fields changedInput schema / properties / filters / additionalPropertiesAdded value: +falseInput schema / properties / limit / descriptionPrevious value: -"Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated."New value: +"Maximum results per page (1–100). Applies to the agency, cfda, recipient, and geography dimensions; geography pages through its areas ranked by aggregated_amount, highest first. Ignored for overview."Output schema / properties / cap / descriptionPrevious value: -"The result-set ceiling the upstream applied."New value: +"recipient: the result-set ceiling the upstream applied. geography: the page size (limit)."Output schema / properties / notice / descriptionPrevious value: -"Caveat explaining a capped total and how to bring the set under the cap."New value: +"recipient: why the total is a cap and how to bring the set under it. geography: how many areas rank below this page and how to reach them."Output schema / properties / results / items / properties / display_name / descriptionPrevious value: -"Geographic display name (geography dimension)"New value: +"Geographic display name (geography dimension); absent on the unattributed row"Output schema / properties / results / items / properties / shape_code / descriptionPrevious value: -"Geographic code (geography dimension)"New value: +"Geographic code (geography dimension). Absent on the unattributed row: spending with no recorded place of performance, which still ranks and counts as an area."Output schema / properties / truncated / descriptionPrevious value: -"True when the upstream capped the reachable result set rather than counting it."New value: +"recipient: true when the upstream capped the reachable result set rather than counting it. geography: true when more areas rank below this page."Output schema / properties / truncationCeilingAdded value: +{
+ "description": "geography: the lowest aggregated_amount on this page — no area on a later page has a higher one.",
+ "type": "number"
+}usaspending_get_agency9 fields changedOutput schema / anyOfPrevious value: -[
- {
- "not": {
- "required": [
- "error"
- ]
- },
- "required": [
- "sub_agency_page",
- "has_more_sub_agencies"
- ]
- },
- {
- "required": [
- "error"
- ]
- }
-]New value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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. `conflicting_input`: Both toptier_code and agency_slug were 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."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "agency_not_found",
- "missing_input",
- "api_unavailable",
- "api_timeout"
-]New value: +[
+ "agency_not_found",
+ "missing_input",
+ "conflicting_input",
+ "api_unavailable",
+ "api_timeout"
+]Output schema / properties / fiscal_year / descriptionPrevious value: -"Fiscal year the budgetary totals below reflect (most recent available)"New value: +"Fiscal year the budgetary totals below reflect: the most recent year with reported budget data, which can trail the current fiscal year (a new year has no amounts until the agency first reports in it)"Output schema / properties / has_more_sub_agencies / descriptionPrevious value: -"Whether more sub-agency pages are available"New value: +"Whether more sub-agency pages are available. Absent when the sub-agency request failed, since pagination is then unknown."Output schema / properties / notice / descriptionPrevious value: -"Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown."New value: +"How to page for more sub-agencies when the breakdown is truncated, and which sections failed to load and whether a retry may recover them. Absent when neither applies."Output schema / properties / sub_agency_fiscal_yearAdded value: +{
+ "description": "Fiscal year the sub-agency breakdown covers, as upstream reports it: the same year as fiscal_year, or the current fiscal year when no budget year was available within 5 seconds — so it can differ from fiscal_year even when both are present. Absent when the sub-agency request failed, or when upstream reports no year for a breakdown requested without one.",
+ "type": "number"
+}Output schema / properties / sub_agency_page / descriptionPrevious value: -"Current sub-agency page returned"New value: +"Current sub-agency page returned. Absent when the sub-agency request failed."Output schema / properties / unavailable_sectionsAdded value: +{
+ "description": "Sections omitted because their request failed while the agency overview loaded. Absent when every section loaded.",
+ "items": {
+ "additionalProperties": false,
+ "description": "A section omitted from the result because its request failed",
+ "properties": {
+ "message": {
+ "description": "The failure message for this section.",
+ "type": "string"
+ },
+ "reason": {
+ "description": "api_unavailable: USAspending was unreachable or answered with a server error. api_timeout: no answer before the request deadline. upstream_error: USAspending rejected the request.",
+ "enum": [
+ "api_unavailable",
+ "api_timeout",
+ "upstream_error"
+ ],
+ "type": "string"
+ },
+ "retryable": {
+ "description": "Whether retrying the call may load this section.",
+ "type": "boolean"
+ },
+ "section": {
+ "description": "budgetary_resources: fiscal_year and the budget, obligation, and outlay totals. sub_agencies: the sub-agency breakdown and its pagination.",
+ "enum": [
+ "budgetary_resources",
+ "sub_agencies"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "section",
+ "reason",
+ "retryable",
+ "message"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+}usaspending_get_award14 fields changedOutput schema / properties / assistance_listingsAdded value: +{
+ "description": "Every Assistance Listing (CFDA program) funding the award, in upstream order; absent for contracts and IDVs",
+ "items": {
+ "additionalProperties": false,
+ "description": "One Assistance Listing funding the award",
+ "properties": {
+ "number": {
+ "description": "Assistance Listing (CFDA) number, e.g. 93.855 — usable in usaspending_search_awards assistance_listings",
+ "type": "string"
+ },
+ "obligation": {
+ "description": "Federal obligation in USD made under this listing",
+ "type": "number"
+ },
+ "title": {
+ "description": "Assistance Listing program title",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / category / descriptionPrevious value: -"Award category (contract, grant, direct_payment, loan, idv, other)"New value: +"Award category: contract, idv, grant, loans, direct payment, insurance, or other"Output schema / properties / cfdaRemoved value: -{
- "additionalProperties": false,
- "description": "CFDA program (grants/assistance)",
- "properties": {
- "number": {
- "description": "CFDA/Assistance Listing number",
- "type": "string"
- },
- "title": {
- "description": "CFDA program title",
- "type": "string"
- }
- },
- "type": "object"
-}Output schema / properties / place_of_performance / descriptionPrevious value: -"Place of performance"New value: +"Place of performance; absent when upstream reports no location fields"Output schema / properties / place_of_performance / properties / country_code / descriptionPrevious value: -"Country code of performance"New value: +"Three-letter country code of performance (e.g. USA)"Output schema / properties / recipient / properties / business_categoriesAdded value: +{
+ "description": "Recipient business category names (e.g. \"Higher Education\", \"U.S. Local Government\") — not the codes usaspending_get_recipient returns as business_types",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / recipient / properties / business_typesRemoved value: -{
- "description": "Recipient business type codes",
- "items": {
- "type": "string"
- },
- "type": "array"
-}Output schema / properties / recipient / properties / location / descriptionPrevious value: -"Recipient address"New value: +"Recipient address; absent when upstream reports no location fields"Output schema / properties / recipient / properties / location / properties / country_code / descriptionPrevious value: -"Recipient country code"New value: +"Recipient three-letter country code (e.g. USA)"Output schema / properties / recipient / properties / parent_recipient_idAdded value: +{
+ "description": "Parent recipient hash ID (ends in -P) — pass to usaspending_get_recipient for the parent organization profile",
+ "type": "string"
+}Output schema / properties / recipient / properties / parent_ueiAdded value: +{
+ "description": "Parent organization Unique Entity Identifier",
+ "type": "string"
+}Output schema / properties / recipient / properties / uei / descriptionPrevious value: -"Unique Entity Identifier"New value: +"Recipient Unique Entity Identifier"Output schema / properties / total_loan_valueAdded value: +{
+ "description": "Face value of the loan in USD (category \"loans\" only). A loan reports its value here, not in total_obligation, which is often 0.",
+ "type": "number"
+}Output schema / properties / total_subsidy_costAdded value: +{
+ "description": "Estimated cost to the government of the loan subsidy in USD (category \"loans\" only)",
+ "type": "number"
+}usaspending_get_idv_awards4 fields changedOutput schema / properties / cap / descriptionPrevious value: -"The per-page limit that was applied."New value: +"The per-page limit that was applied, when truncated."Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — the award may have no children of the requested type. Absent when results are present."New value: +"How to continue when truncated, or a recovery hint when results are empty — the award may have no children of the requested type. Absent otherwise."Output schema / properties / shown / descriptionPrevious value: -"Number of child awards returned on this page."New value: +"Number of child awards returned on this page, when truncated."Output schema / properties / truncated / descriptionPrevious value: -"True when this page was full and more child awards may remain beyond it."New value: +"True when the upstream reports more child awards beyond this page. Absent on a full page the upstream marks as last — has_next_page still says whether to request another."usaspending_get_recipient8 fields changedInput schema / properties / award_typeRemoved value: -{
- "description": "Award type category to scope award totals",
- "enum": [
- "contracts",
- "grants",
- "direct_payments",
- "loans",
- "other_financial_assistance"
- ],
- "type": "string"
-}Input schema / properties / fiscal_year / descriptionPrevious value: -"Fiscal year to scope award totals (e.g., 2024)"New value: +"Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months."Output schema / anyOfPrevious value: -[
- {
- "not": {
- "required": [
- "error"
- ]
- }
- },
- {
- "required": [
- "error"
- ]
- }
-]New value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "period"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / periodAdded value: +{
+ "description": "Window the totals cover: FY<year> when fiscal_year was given, otherwise \"trailing 12 months\"",
+ "type": "string"
+}Output schema / properties / total_face_value_loan_amount / descriptionPrevious value: -"Total face value of loans in USD"New value: +"Total face value of loans in USD over period"Output schema / properties / total_face_value_loan_transactions / descriptionPrevious value: -"Number of face-value loan transactions"New value: +"Number of face-value loan transactions over period"Output schema / properties / total_transaction_amount / descriptionPrevious value: -"Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided"New value: +"Total transaction (award) amount in USD over period, across all award types"Output schema / properties / total_transactions / descriptionPrevious value: -"Total number of award transactions"New value: +"Total number of award transactions over period"usaspending_search_awards31 fields changedInput schema / properties / agency_name / descriptionPrevious value: -"Filter to a specific awarding agency by name (e.g., \"Department of Defense\"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names."New value: +"Filter to one awarding agency by its top-tier name (e.g., \"Department of Defense\"). Top-tier only: a sub-agency name matches no awards. Take the value from toptier_name in usaspending_autocomplete_filters type=awarding_agency — for a sub-agency that is its parent, so results cover the whole department."Input schema / properties / assistance_listings / descriptionPrevious value: -"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."New value: +"Filter by Assistance Listing (CFDA) program numbers, e.g. [\"15.507\"]: 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 matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers."Input schema / properties / assistance_listings / items / descriptionPrevious value: -"Assistance Listing number, e.g. 93.866"New value: +"Assistance Listing number, e.g. 15.507"Input schema / properties / def_codesAdded value: +{
+ "description": "Filter by Disaster Emergency Fund Codes (DEF), e.g. [\"Z\"], or [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts.",
+ "items": {
+ "description": "Disaster Emergency Fund Code, e.g. Z or L",
+ "pattern": "^[0-9A-Za-z]{1,3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / additionalPropertiesAdded value: +falseInput schema / properties / filters / descriptionPrevious value: -"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."New value: +"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 rejected — this endpoint silently ignores it; filter by recipient via recipient_name."Input schema / properties / filters / properties / agency_name / descriptionPrevious value: -"Awarding agency name (toptier), e.g., \"Department of Defense\""New value: +"Awarding agency name, top-tier only (e.g., \"Department of Defense\") — the toptier_name from usaspending_autocomplete_filters type=awarding_agency; a sub-agency name matches no awards"Input schema / properties / filters / properties / assistance_listingsAdded value: +{
+ "description": "Filter by Assistance Listing (CFDA) program numbers, e.g. [\"15.507\"]: 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 matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers.",
+ "items": {
+ "description": "Assistance Listing number, e.g. 15.507",
+ "pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / def_codesAdded value: +{
+ "description": "Filter by Disaster Emergency Fund Codes (DEF), e.g. [\"Z\"], or [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts.",
+ "items": {
+ "description": "Disaster Emergency Fund Code, e.g. Z or L",
+ "pattern": "^[0-9A-Za-z]{1,3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / psc_codesAdded value: +{
+ "description": "Filter by Product and Service Codes (PSC), e.g. [\"Y1NE\"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it (\"Y1\" covers \"Y1NE\"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes.",
+ "items": {
+ "description": "Product and Service Code or prefix, e.g. Y1NE or Y1",
+ "pattern": "^[0-9A-Za-z]{1,4}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / location_filter / additionalPropertiesAdded value: +falseInput schema / properties / location_filter / descriptionPrevious value: -"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."New value: +"Filter by place of performance. Takes codes, not place names — use a geocoding server to resolve names to codes first. Blank fields are ignored, and an all-blank object is no location filter. The location sent is echoed as applied_location."Input schema / properties / location_filter / properties / country / anyOfAdded value: +[
+ {
+ "const": "",
+ "type": "string"
+ },
+ {
+ "pattern": "^[A-Za-z]{3}$",
+ "type": "string"
+ }
+]Input schema / properties / location_filter / properties / country / descriptionPrevious value: -"ISO 3166-1 alpha-3 country code (e.g., USA)"New value: +"ISO 3166-1 alpha-3 country code (e.g., USA); USA when omitted. A US territory code — PRI, GUM, VIR, ASM, MNP — is sent as USA with the territory as state."Input schema / properties / location_filter / properties / country / typeRemoved value: -"string"Input schema / properties / location_filter / properties / county / anyOfAdded value: +[
+ {
+ "const": "",
+ "type": "string"
+ },
+ {
+ "pattern": "^(?:\\d{3}|\\d{5})$",
+ "type": "string"
+ }
+]Input schema / properties / location_filter / properties / county / descriptionPrevious value: -"FIPS county code (e.g., 06037 for Los Angeles County)"New value: +"US county FIPS code: 3 digits with state (049 with state NM), or the 5-digit state + county code (35049, Santa Fe County, NM), whose first two digits set the state — the form usaspending_spending_by_geography county rows carry as shape_code."Input schema / properties / location_filter / properties / county / typeRemoved value: -"string"Input schema / properties / location_filter / properties / state / anyOfAdded value: +[
+ {
+ "const": "",
+ "type": "string"
+ },
+ {
+ "pattern": "^(?:[A-Za-z]{2}|\\d{2})$",
+ "type": "string"
+ }
+]Input schema / properties / location_filter / properties / state / descriptionPrevious value: -"Two-letter US state abbreviation (e.g., CA)"New value: +"Under USA (the default): a US state, DC, territory, freely associated state, or armed-forces code as a 2-letter postal code (NM, PR, FM, AE) or 2-digit FIPS code (35). Under another country: that country's own 2-letter subdivision code (ON with CAN)."Input schema / properties / location_filter / properties / state / typeRemoved value: -"string"Input schema / properties / psc_codesAdded value: +{
+ "description": "Filter by Product and Service Codes (PSC), e.g. [\"Y1NE\"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it (\"Y1\" covers \"Y1NE\"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes.",
+ "items": {
+ "description": "Product and Service Code or prefix, e.g. Y1NE or Y1",
+ "pattern": "^[0-9A-Za-z]{1,4}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / time_period / additionalPropertiesAdded value: +falseOutput schema / properties / applied_def_codesAdded value: +{
+ "description": "DEF codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_locationAdded value: +{
+ "description": "Place of performance location sent, as normalized (e.g. country=USA, state=NM, county=049)",
+ "type": "string"
+}Output schema / properties / applied_psc_codesAdded value: +{
+ "description": "PSC codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / cap / descriptionPrevious value: -"Per-page cap (limit) applied to this page."New value: +"Per-page cap (limit) applied to this page, when truncated."Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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. `psc_codes_type_mismatch`: psc_codes was given while the award type codes include assistance codes. `invalid_location`: location_filter names an unknown US state, a county without a state or under an armed-forces code, a county or FIPS-number state under a non-USA country, or parts that place it in different states. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout",
- "pagination_limit_exceeded",
- "date_before_earliest",
- "date_range_inverted",
- "unsupported_sort",
- "assistance_listings_type_mismatch"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "pagination_limit_exceeded",
+ "date_before_earliest",
+ "date_range_inverted",
+ "unsupported_sort",
+ "assistance_listings_type_mismatch",
+ "psc_codes_type_mismatch",
+ "invalid_location"
+]Output schema / properties / shown / descriptionPrevious value: -"Number of awards returned on this page."New value: +"Number of awards returned on this page, when truncated."Output schema / properties / truncated / descriptionPrevious value: -"True when this page was capped at `limit` and more results may remain (continue via page or the cursor)."New value: +"True when the upstream reports more results beyond this page (continue via page or the cursor). Absent on a full page the upstream marks as last, including every page past a 10,000-result offset where the upstream stops reporting continuation — has_next still says whether to request another."usaspending_spending_by_category16 fields changedInput schema / properties / category / descriptionPrevious value: -"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"New value: +"Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), or recipient_duns (recipients)"Input schema / properties / category / enumPrevious value: -[
- "naics",
- "psc",
- "awarding_agency",
- "awarding_subagency",
- "funding_agency",
- "funding_subagency",
- "cfda",
- "recipient_duns",
- "recipient_parent_duns"
-]New value: +[
+ "naics",
+ "psc",
+ "awarding_agency",
+ "awarding_subagency",
+ "funding_agency",
+ "funding_subagency",
+ "cfda",
+ "recipient_duns"
+]Input schema / properties / filters / additionalPropertiesAdded value: +falseInput schema / properties / filters / properties / agency_name / descriptionPrevious value: -"Awarding agency name filter"New value: +"Awarding agency name filter, top-tier only (e.g., \"Department of Defense\") — the toptier_name from usaspending_autocomplete_filters type=awarding_agency; a sub-agency name matches nothing"Input schema / properties / filters / properties / assistance_listingsAdded value: +{
+ "description": "Filter by Assistance Listing (CFDA) program numbers, e.g. [\"15.507\"]: 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 matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers.",
+ "items": {
+ "description": "Assistance Listing number, e.g. 15.507",
+ "pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / def_codesAdded value: +{
+ "description": "Filter by Disaster Emergency Fund Codes (DEF), e.g. [\"Z\"], or [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts.",
+ "items": {
+ "description": "Disaster Emergency Fund Code, e.g. Z or L",
+ "pattern": "^[0-9A-Za-z]{1,3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / psc_codesAdded value: +{
+ "description": "Filter by Product and Service Codes (PSC), e.g. [\"Y1NE\"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it (\"Y1\" covers \"Y1NE\"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes.",
+ "items": {
+ "description": "Product and Service Code or prefix, e.g. Y1NE or Y1",
+ "pattern": "^[0-9A-Za-z]{1,4}$",
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / applied_assistance_listingsAdded value: +{
+ "description": "Assistance Listing numbers sent (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_def_codesAdded value: +{
+ "description": "DEF codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_psc_codesAdded value: +{
+ "description": "PSC codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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. `assistance_listings_type_mismatch`: filters.assistance_listings was given while every code in filters.award_type_codes is a contract or IDV code. `psc_codes_type_mismatch`: filters.psc_codes was given while every code in filters.award_type_codes is an assistance code. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout",
- "date_range_inverted",
- "date_before_earliest"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest",
+ "assistance_listings_type_mismatch",
+ "psc_codes_type_mismatch"
+]Output schema / properties / notice / descriptionPrevious value: -"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."New value: +"Names a date bound that was filled in because only the other was supplied, and — when results are empty — names any Assistance Listing, PSC, or DEF codes sent and suggests how to broaden filters. Absent when neither applies."Output schema / properties / results / items / properties / code / descriptionPrevious value: -"Code value (NAICS, PSC, CFDA number, etc.)"New value: +"Code value (NAICS, PSC, CFDA number, recipient DUNS, etc.)"Output schema / properties / results / items / properties / recipient_idAdded value: +{
+ "description": "Recipient hash ID (recipient_duns rows) — pass to usaspending_get_recipient for the profile. Absent when upstream has none.",
+ "type": "string"
+}Output schema / properties / results / items / properties / ueiAdded value: +{
+ "description": "Recipient Unique Entity Identifier (recipient_duns rows). Absent when upstream has none.",
+ "type": "string"
+}usaspending_spending_by_geography18 fields changedInput schema / properties / filters / additionalPropertiesAdded value: +falseInput schema / properties / filters / properties / agency_name / descriptionPrevious value: -"Awarding agency name filter"New value: +"Awarding agency name filter, top-tier only (e.g., \"Department of Defense\") — the toptier_name from usaspending_autocomplete_filters type=awarding_agency; a sub-agency name matches nothing"Input schema / properties / filters / properties / assistance_listingsAdded value: +{
+ "description": "Filter by Assistance Listing (CFDA) program numbers, e.g. [\"15.507\"]: 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 matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers.",
+ "items": {
+ "description": "Assistance Listing number, e.g. 15.507",
+ "pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / def_codesAdded value: +{
+ "description": "Filter by Disaster Emergency Fund Codes (DEF), e.g. [\"Z\"], or [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts.",
+ "items": {
+ "description": "Disaster Emergency Fund Code, e.g. Z or L",
+ "pattern": "^[0-9A-Za-z]{1,3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / psc_codesAdded value: +{
+ "description": "Filter by Product and Service Codes (PSC), e.g. [\"Y1NE\"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it (\"Y1\" covers \"Y1NE\"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes.",
+ "items": {
+ "description": "Product and Service Code or prefix, e.g. Y1NE or Y1",
+ "pattern": "^[0-9A-Za-z]{1,4}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / geo_layer / descriptionPrevious value: -"Geographic granularity: state (50 states), county (county-level), or district (congressional district)"New value: +"Geographic granularity: state (states, DC, and territories), county (county-level), or district (congressional district)"Input schema / properties / limit / descriptionPrevious value: -"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."New value: +"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; use shape_codes to retrieve one ranked past the cap."Input schema / properties / shape_codesAdded value: +{
+ "description": "Return only these areas (1–500 codes), in the shape_code form this tool returns for geo_layer: 2-letter postal code for state (\"NY\"), 5-digit state + county FIPS for county (\"36117\" is Wayne County, NY), or 4-digit state FIPS + 2-digit district number for district (\"3623\" is NY-23, \"5600\" is Wyoming's at-large seat). Selection runs over every area the filters matched, so it reaches areas ranked past limit; selected areas stay ranked by aggregated_amount and capped at limit. A code that matches no area is named in the notice.",
+ "items": {
+ "description": "One area code: 2-letter postal code (e.g. \"NY\"), 5-digit county FIPS (e.g. \"36117\"), or 4-digit district code (e.g. \"3623\")",
+ "pattern": "^(?:[A-Za-z]{2}|\\d{4,5})$",
+ "type": "string"
+ },
+ "maxItems": 500,
+ "minItems": 1,
+ "type": "array"
+}Output schema / properties / applied_assistance_listingsAdded value: +{
+ "description": "Assistance Listing numbers sent (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_def_codesAdded value: +{
+ "description": "DEF codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_psc_codesAdded value: +{
+ "description": "PSC codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_shape_codesAdded value: +{
+ "description": "Area codes listed in shape_codes, letters uppercased and duplicates removed (comma-separated)",
+ "type": "string"
+}Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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. `assistance_listings_type_mismatch`: filters.assistance_listings was given while every code in filters.award_type_codes is a contract or IDV code. `psc_codes_type_mismatch`: filters.psc_codes was given while every code in filters.award_type_codes is an assistance code. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout",
- "date_range_inverted",
- "date_before_earliest"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest",
+ "assistance_listings_type_mismatch",
+ "psc_codes_type_mismatch"
+]Output schema / properties / notice / descriptionPrevious value: -"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."New value: +"How to reach areas omitted by limit, which shape_codes matched no area, which time-period bound was filled in when only the other was supplied, and — when the filters matched no area — any Assistance Listing, PSC, or DEF codes sent and how to broaden filters. Absent when none applies."Output schema / properties / results / items / properties / award_countRemoved value: -{
- "description": "Number of awards in this area",
- "type": "number"
-}Output schema / properties / results / items / properties / shape_code / descriptionPrevious value: -"Geographic identifier (FIPS state code, county FIPS, or district code)"New value: +"Area code, the form shape_codes takes: 2-letter postal code (state), 5-digit state + county FIPS (county), or 4-digit state FIPS + district number (district). Absent on the row for spending with no recorded location."Output schema / properties / total_areas_available / descriptionPrevious value: -"Number of geographic areas the filters matched, before limit was applied"New value: +"Number of geographic areas the filters matched, before shape_codes selection and limit were applied"usaspending_spending_over_time12 fields changedInput schema / properties / filters / additionalPropertiesAdded value: +falseInput schema / properties / filters / properties / agency_name / descriptionPrevious value: -"Awarding agency name filter"New value: +"Awarding agency name filter, top-tier only (e.g., \"Department of Defense\") — the toptier_name from usaspending_autocomplete_filters type=awarding_agency; a sub-agency name matches nothing"Input schema / properties / filters / properties / assistance_listingsAdded value: +{
+ "description": "Filter by Assistance Listing (CFDA) program numbers, e.g. [\"15.507\"]: 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 matching award's primary listing can differ from the one requested, and amounts cover the whole award, not that listing's share. Only assistance awards (grants, direct payments, loans, other assistance) carry listings, so a call whose award types are all contracts or IDVs — including a contract default — is rejected as assistance_listings_type_mismatch. Use usaspending_autocomplete_filters type=cfda to look up numbers.",
+ "items": {
+ "description": "Assistance Listing number, e.g. 15.507",
+ "pattern": "^\\d{2}\\.[0-9A-Z]{3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / award_type_codes / descriptionPrevious value: -"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)."New value: +"Award type code filters (A/B/C/D, 02–05, etc.); groups may be mixed. When omitted, defaults to contracts (A, B, C, D)."Input schema / properties / filters / properties / def_codesAdded value: +{
+ "description": "Filter by Disaster Emergency Fund Codes (DEF), e.g. [\"Z\"], or [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19: 1–3 letters or digits, sent uppercased — the codes usaspending_disaster_spending takes and usaspending_get_agency lists. Matches awards of any type funded under any of these codes. Amounts cover the whole matching award, not the share funded by the code, and DEF-filtered totals can be negative. An unknown code is rejected with the list of codes USAspending accepts.",
+ "items": {
+ "description": "Disaster Emergency Fund Code, e.g. Z or L",
+ "pattern": "^[0-9A-Za-z]{1,3}$",
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filters / properties / psc_codesAdded value: +{
+ "description": "Filter by Product and Service Codes (PSC), e.g. [\"Y1NE\"]: 1–4 letters or digits, sent uppercased. A shorter code covers every code under it (\"Y1\" covers \"Y1NE\"); several values match any of them. Only contracts and IDVs carry a PSC, so a call whose award types are all assistance types is rejected as psc_codes_type_mismatch, and pairing psc_codes with assistance_listings matches nothing, since no award carries both. Use usaspending_autocomplete_filters type=psc to look up codes.",
+ "items": {
+ "description": "Product and Service Code or prefix, e.g. Y1NE or Y1",
+ "pattern": "^[0-9A-Za-z]{1,4}$",
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / applied_assistance_listingsAdded value: +{
+ "description": "Assistance Listing numbers sent (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_def_codesAdded value: +{
+ "description": "DEF codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_psc_codesAdded value: +{
+ "description": "PSC codes sent, uppercased (comma-separated)",
+ "type": "string"
+}Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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. `assistance_listings_type_mismatch`: filters.assistance_listings was given while every code in filters.award_type_codes is a contract or IDV code, or award_type_codes was left at its contract default. `psc_codes_type_mismatch`: filters.psc_codes was given while every code in filters.award_type_codes is an assistance code. Other values are possible when a failure originates below the handler."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout",
- "date_range_inverted",
- "date_before_earliest"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest",
+ "assistance_listings_type_mismatch",
+ "psc_codes_type_mismatch"
+]Output schema / properties / notice / descriptionPrevious value: -"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."New value: +"Names a time-window bound that was filled in because only the other was supplied, and — when no periods are returned — names any Assistance Listing, PSC, or DEF codes sent and suggests broadening filters. Absent when neither applies."usaspending_autocomplete_filters2 fields changedInput schema / properties / type / descriptionPrevious value: -"Lookup table to search: naics (industry codes), psc (product/service codes), cfda (assistance programs), awarding_agency (agency names), recipient (recipient names)"New value: +"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)"Output schema / properties / results / items / properties / code / descriptionPrevious value: -"Code value (NAICS code, PSC code, CFDA number, or agency code); use this in filter parameters"New value: +"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"usaspending_disaster_spending5 fields changedInput schema / properties / spending_type / descriptionPrevious value: -"Data type for the agency and recipient dimensions: award (award-level obligations and outlays) or total (includes direct non-award spending). Ignored for cfda and overview; the geography dimension is not user-controllable and always reports obligation-based amounts."New value: +"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."Output schema / properties / results / items / properties / id / descriptionPrevious value: -"Item ID"New value: +"Item ID. On the recipient dimension, a recipient hash ID for usaspending_get_recipient — the recipient-level (-R) ID when the recipient has several."Output schema / properties / results / items / properties / total_budgetary_resourcesAdded value: +{
+ "description": "Total budgetary resources in USD for this row (agency dimension with spending_type total)",
+ "type": "number"
+}Output schema / properties / spending_type / descriptionPrevious value: -"Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview"New value: +"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"Output schema / properties / totalsAdded value: +{
+ "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"
+}usaspending_search_awards29 fields changedInput schema / properties / assistance_listingsAdded value: +{
+ "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"
+}Input schema / properties / award_type_codes / descriptionPrevious value: -"Filter by award type codes. All codes must belong to a single group: A/B/C/D (contracts), 02/03/04/05 (grants), 06/10 (direct payments), 07/08 (loans), IDV_A–IDV_E (IDVs). Defaults to contracts. Mixing groups across categories causes a 422 error."New value: +"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."Input schema / properties / award_type_codes / minItemsAdded value: +1Input schema / properties / filters / properties / award_type_codes / descriptionPrevious value: -"Award type codes; all must belong to one group (A/B/C/D, 02/03/04/05, 06/10, 07/08, IDV_A–IDV_E)"New value: +"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."Input schema / properties / filters / properties / time_period_end / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_end / descriptionPrevious value: -"End date (YYYY-MM-DD). Requires time_period_start."New value: +"End date (YYYY-MM-DD). Given alone, the range starts at 2007-10-01, the earliest searchable date."Input schema / properties / filters / properties / time_period_end / typeRemoved value: -"string"Input schema / properties / filters / properties / time_period_start / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_start / descriptionPrevious value: -"Start date (YYYY-MM-DD); earliest valid 2007-10-01. Requires time_period_end."New value: +"Start date (YYYY-MM-DD); earliest valid 2007-10-01. Given alone, the range runs through today (UTC)."Input schema / properties / filters / properties / time_period_start / typeRemoved value: -"string"Input schema / properties / sort / defaultRemoved value: -"Award Amount"Input schema / properties / sort / descriptionPrevious value: -"Sort field for results"New value: +"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."Input schema / properties / sort / enumPrevious value: -[
- "Award Amount",
- "Total Outlays",
- "Start Date",
- "End Date",
- "Recipient Name",
- "Awarding Agency"
-]New value: +[
+ "Award Amount",
+ "Total Outlays",
+ "Start Date",
+ "End Date",
+ "Loan Value",
+ "Subsidy Cost",
+ "Issued Date",
+ "Recipient Name",
+ "Awarding Agency"
+]Input schema / properties / time_period / descriptionPrevious value: -"Filter awards by date range (action date)"New value: +"Filter awards by date range (action date). Both blank means no date filter; one blank end is filled and named in the notice."Input schema / properties / time_period / properties / end_date / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / time_period / properties / end_date / descriptionPrevious value: -"End date in ISO 8601 format (YYYY-MM-DD)"New value: +"End date in ISO 8601 format (YYYY-MM-DD). Blank (\"\") leaves the end open, filled with today (UTC)."Input schema / properties / time_period / properties / end_date / typeRemoved value: -"string"Input schema / properties / time_period / properties / start_date / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / time_period / properties / start_date / descriptionPrevious value: -"Start date in ISO 8601 format (YYYY-MM-DD); earliest valid: 2007-10-01"New value: +"Start date in ISO 8601 format (YYYY-MM-DD); earliest valid: 2007-10-01. Blank (\"\") leaves the start open, filled with 2007-10-01."Input schema / properties / time_period / properties / start_date / typeRemoved value: -"string"Output schema / properties / applied_assistance_listingsAdded value: +{
+ "description": "Assistance Listing numbers filter applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_end / descriptionPrevious value: -"End date filter applied (YYYY-MM-DD)"New value: +"End of the date range sent (YYYY-MM-DD), including a filled-in end"Output schema / properties / applied_time_period_start / descriptionPrevious value: -"Start date filter applied (YYYY-MM-DD)"New value: +"Start of the date range sent (YYYY-MM-DD), including a filled-in start"Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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. Other values are possible when a failure originates below the handler."New value: +"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."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout",
- "pagination_limit_exceeded",
- "date_before_earliest"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "pagination_limit_exceeded",
+ "date_before_earliest",
+ "date_range_inverted",
+ "unsupported_sort",
+ "assistance_listings_type_mismatch"
+]Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present."New value: +"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."Output schema / properties / results / items / properties / issued_dateAdded value: +{
+ "description": "Date the loan was issued (YYYY-MM-DD; loans only — they carry no start or end date)",
+ "type": "string"
+}Output schema / properties / results / items / properties / loan_valueAdded value: +{
+ "description": "Face value of the loan in USD (loans only — they carry no award_amount)",
+ "type": "number"
+}Output schema / properties / results / items / properties / subsidy_costAdded value: +{
+ "description": "Original subsidy cost of the loan in USD — the estimated long-term cost to the government (loans only)",
+ "type": "number"
+}usaspending_spending_by_category11 fields changedInput schema / properties / filters / properties / time_period_end / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_end / descriptionPrevious value: -"End date (YYYY-MM-DD)"New value: +"End date (YYYY-MM-DD). Given alone, the window starts at 2007-10-01, the earliest searchable date."Input schema / properties / filters / properties / time_period_end / typeRemoved value: -"string"Input schema / properties / filters / properties / time_period_start / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_start / descriptionPrevious value: -"Start date (YYYY-MM-DD)"New value: +"Start date (YYYY-MM-DD), 2007-10-01 or later. Given alone, the window runs through today (UTC)."Input schema / properties / filters / properties / time_period_start / typeRemoved value: -"string"Output schema / properties / applied_time_period_end / descriptionPrevious value: -"End date filter applied (YYYY-MM-DD)"New value: +"End date sent (YYYY-MM-DD), including a filled-in end"Output schema / properties / applied_time_period_start / descriptionPrevious value: -"Start date filter applied (YYYY-MM-DD)"New value: +"Start date sent (YYYY-MM-DD), including a filled-in start"Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest"
+]Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present."New value: +"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."usaspending_spending_by_geography11 fields changedInput schema / properties / filters / properties / time_period_end / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_end / descriptionPrevious value: -"End of time period in ISO 8601 format (YYYY-MM-DD)"New value: +"End of time period (YYYY-MM-DD). Given alone, the period starts at 2007-10-01, the earliest searchable date."Input schema / properties / filters / properties / time_period_end / typeRemoved value: -"string"Input schema / properties / filters / properties / time_period_start / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_start / descriptionPrevious value: -"Start of time period in ISO 8601 format (YYYY-MM-DD)"New value: +"Start of time period (YYYY-MM-DD), 2007-10-01 or later. Given alone, the period runs through today (UTC)."Input schema / properties / filters / properties / time_period_start / typeRemoved value: -"string"Output schema / properties / applied_time_period_end / descriptionPrevious value: -"End date filter applied (YYYY-MM-DD)"New value: +"End of the time period sent (YYYY-MM-DD), including a filled-in end"Output schema / properties / applied_time_period_start / descriptionPrevious value: -"Start date filter applied (YYYY-MM-DD)"New value: +"Start of the time period sent (YYYY-MM-DD), including a filled-in start"Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest"
+]Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present."New value: +"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."usaspending_spending_over_time11 fields changedInput schema / properties / filters / properties / time_period_end / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_end / descriptionPrevious value: -"End of the time window (YYYY-MM-DD)"New value: +"End of the time window (YYYY-MM-DD). Given alone, the window starts at 2007-10-01, the earliest searchable date."Input schema / properties / filters / properties / time_period_end / typeRemoved value: -"string"Input schema / properties / filters / properties / time_period_start / anyOfAdded value: +[
+ {
+ "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"
+ }
+]Input schema / properties / filters / properties / time_period_start / descriptionPrevious value: -"Start of the time window (YYYY-MM-DD)"New value: +"Start of the time window (YYYY-MM-DD), 2007-10-01 or later. Given alone, the window runs through today (UTC)."Input schema / properties / filters / properties / time_period_start / typeRemoved value: -"string"Output schema / properties / applied_time_period_end / descriptionPrevious value: -"End date filter applied (YYYY-MM-DD)"New value: +"End of the time window sent (YYYY-MM-DD), including a filled-in end"Output schema / properties / applied_time_period_start / descriptionPrevious value: -"Start date filter applied (YYYY-MM-DD)"New value: +"Start of the time window sent (YYYY-MM-DD), including a filled-in start"Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"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."New value: +"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."Output schema / properties / error / properties / data / properties / reason / examplesPrevious value: -[
- "api_unavailable",
- "api_timeout"
-]New value: +[
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest"
+]Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when no periods are returned — suggests broadening filters. Absent when results are present."New value: +"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."usaspending_autocomplete_filters6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "type",
+ "search_text",
+ "results",
+ "total",
+ "lookup_type",
+ "query",
+ "result_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "type",
- "search_text",
- "results",
- "total",
- "lookup_type",
- "query",
- "result_count"
-]usaspending_disaster_spending6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "dimension",
+ "spending_type",
+ "results",
+ "applied_dimension"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "dimension",
- "spending_type",
- "results",
- "applied_dimension"
-]usaspending_get_agency6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "sub_agency_page",
+ "has_more_sub_agencies"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "sub_agency_page",
- "has_more_sub_agencies"
-]usaspending_get_award5 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `award_not_found`: No award exists for the given award ID. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "award_not_found",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}usaspending_get_award_federal_accounts6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "current_page",
- "has_next_page"
-]usaspending_get_award_subawards6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "prime_award_id",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "prime_award_id",
- "current_page",
- "has_next_page"
-]usaspending_get_award_transactions6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "queried_award_id",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "queried_award_id",
- "current_page",
- "has_next_page"
-]usaspending_get_federal_account5 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}usaspending_get_federal_account_breakdown6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "account_code",
+ "dimension",
+ "results",
+ "page_metadata",
+ "applied_dimension",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "account_code",
- "dimension",
- "results",
- "page_metadata",
- "applied_dimension",
- "current_page",
- "has_next_page"
-]usaspending_get_idv_awards6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "parent_award_id",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "parent_award_id",
- "current_page",
- "has_next_page"
-]usaspending_get_recipient5 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `recipient_not_found`: No recipient found for the given recipient ID. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "recipient_not_found",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}usaspending_list_agencies6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "total",
+ "agency_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "results",
- "total",
- "agency_count"
-]usaspending_search_awards6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout",
+ "pagination_limit_exceeded",
+ "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"
+}Output schema / requiredRemoved value: -[
- "results",
- "page_metadata",
- "page",
- "has_next"
-]usaspending_search_federal_accounts6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "results",
- "page_metadata",
- "page",
- "has_next"
-]usaspending_search_recipients6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "page_metadata",
+ "recipient_count",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "results",
- "page_metadata",
- "recipient_count",
- "page",
- "has_next"
-]usaspending_spending_by_category6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "category",
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "category",
- "results",
- "page_metadata",
- "page",
- "has_next"
-]usaspending_spending_by_geography6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "scope",
+ "geo_layer",
+ "results",
+ "total",
+ "total_areas_available",
+ "applied_scope",
+ "applied_geo_layer",
+ "area_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "scope",
- "geo_layer",
- "results",
- "total",
- "total_areas_available",
- "applied_scope",
- "applied_geo_layer",
- "area_count"
-]usaspending_spending_over_time6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "group",
+ "results",
+ "total_periods",
+ "time_group",
+ "period_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `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"
+}Output schema / requiredRemoved value: -[
- "group",
- "results",
- "total_periods",
- "time_group",
- "period_count"
-]usaspending_disaster_spending4 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The result-set ceiling the upstream applied.",
+ "type": "number"
+}Output schema / properties / noticeAdded value: +{
+ "description": "Caveat explaining a capped total and how to bring the set under the cap.",
+ "type": "string"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of results returned on this page.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when the upstream capped the reachable result set rather than counting it.",
+ "type": "boolean"
+}usaspending_autocompleteusaspending_autocomplete_filtersusaspending_get_award3 fields changedOutput schema / properties / period_of_performance / properties / end_date / descriptionPrevious value: -"Performance end date"New value: +"Performance end date (YYYY-MM-DD)"Output schema / properties / period_of_performance / properties / potential_end_date / descriptionPrevious value: -"Potential end date including options"New value: +"Potential end date including options (YYYY-MM-DD)"Output schema / properties / period_of_performance / properties / start_date / descriptionPrevious value: -"Performance start date"New value: +"Performance start date (YYYY-MM-DD)"usaspending_search_awards2 fields changedInput schema / properties / agency_name / descriptionPrevious value: -"Filter to a specific awarding agency by name (e.g., \"Department of Defense\"). Use usaspending_autocomplete type=awarding_agency to find exact names."New value: +"Filter to a specific awarding agency by name (e.g., \"Department of Defense\"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names."Input schema / properties / naics_codes / descriptionPrevious value: -"Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete type=naics to look up codes."New value: +"Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete_filters type=naics to look up codes."usaspending_spending_by_geography9 fields changedInput schema / properties / filters / properties / award_type_codes / descriptionPrevious value: -"Award type codes: A/B/C/D (contracts), 02–05 (grants), 06/10 (direct payments), 07/08 (loans)"New value: +"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."Input schema / properties / limitAdded value: +{
+ "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"
+}Output schema / properties / applied_award_type_defaultAdded value: +{
+ "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"
+}Output schema / properties / capAdded value: +{
+ "description": "The limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of geographic areas returned.",
+ "type": "number"
+}Output schema / properties / total_areas_availableAdded value: +{
+ "description": "Number of geographic areas the filters matched, before limit was applied",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when the area list was capped at limit.",
+ "type": "boolean"
+}Output schema / properties / truncationCeilingAdded value: +{
+ "description": "Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones.",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "scope",
- "geo_layer",
- "results",
- "total",
- "applied_scope",
- "applied_geo_layer",
- "area_count"
-]New value: +[
+ "scope",
+ "geo_layer",
+ "results",
+ "total",
+ "total_areas_available",
+ "applied_scope",
+ "applied_geo_layer",
+ "area_count"
+]usaspending_search_awards7 fields changedInput schema / properties / last_record_sort_value / descriptionPrevious value: -"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. When both cursor fields are supplied, page is ignored."New value: +"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."Input schema / properties / page / descriptionPrevious value: -"Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit); to read past that, use the cursor fields below."New value: +"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."Output schema / properties / has_next / descriptionPrevious value: -"Whether there are more pages of results"New value: +"Whether more results may remain — set on a full page even when the upstream flag reports none."Output schema / properties / page_metadata / properties / has_next / descriptionPrevious value: -"Whether there are more pages of results"New value: +"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."Output schema / properties / page_metadata / properties / last_record_sort_value / descriptionPrevious value: -"Keyset-pagination cursor for the next page — pass back as last_record_sort_value to continue past the 50,000-result page limit"New value: +"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."Output schema / properties / page_metadata / properties / last_record_unique_id / descriptionPrevious value: -"Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value"New value: +"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."Output schema / properties / truncated / descriptionPrevious value: -"True when this page was capped at `limit` and more results remain (continue via page or the cursor)."New value: +"True when this page was capped at `limit` and more results may remain (continue via page or the cursor)."usaspending_spending_over_time1 field changedOutput schema / properties / results / items / properties / idvsAdded value: +{
+ "description": "IDV (Indefinite Delivery Vehicle) obligation amount in USD for this period",
+ "type": "number"
+}usaspending_get_award_federal_accountsusaspending_get_federal_account2 fields changedInput schema / properties / account_code / descriptionPrevious value: -"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts."New value: +"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."Output schema / properties / childrenAdded value: +{
+ "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"
+}usaspending_get_federal_account_breakdownusaspending_get_federal_account1 field changedInput schema / properties / account_code / descriptionPrevious value: -"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Appears in award funding details from usaspending_get_award."New value: +"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts."usaspending_search_awards1 field changedOutput schema / properties / upstream_messages / descriptionPrevious value: -"Notices the USAspending API returned for this request — e.g. a supplied filter that was ignored because this endpoint does not support it, or the 2007-10-01 date-floor note. Present whenever the API returns any messages."New value: +"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."usaspending_spending_over_time4 fields changedInput schema / properties / group / descriptionPrevious value: -"Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (calendar month)"New value: +"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)"Output schema / properties / results / items / properties / time_period / descriptionPrevious value: -"Time period for this row"New value: +"Time period for this row. Populated per the requested grouping: fiscal_year alone, fiscal_year + quarter, or fiscal_year + month."Output schema / properties / results / items / properties / time_period / properties / calendar_yearRemoved value: -{
- "description": "Calendar year",
- "type": "string"
-}Output schema / properties / results / items / properties / time_period / properties / month / descriptionPrevious value: -"Calendar month (1–12)"New value: +"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."usaspending_get_agency14 fields changedInput schema / properties / pageAdded value: +{
+ "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"
+}Output schema / properties / budget_authority_amountRemoved value: -{
- "description": "Total budget authority amount in USD for current fiscal year",
- "type": "number"
-}Output schema / properties / budgetary_resources_amountAdded value: +{
+ "description": "Total budgetary resources in USD for the fiscal year",
+ "type": "number"
+}Output schema / properties / fiscal_yearAdded value: +{
+ "description": "Fiscal year the budgetary totals below reflect (most recent available)",
+ "type": "number"
+}Output schema / properties / has_more_sub_agenciesAdded value: +{
+ "description": "Whether more sub-agency pages are available",
+ "type": "boolean"
+}Output schema / properties / noticeAdded value: +{
+ "description": "Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown.",
+ "type": "string"
+}Output schema / properties / obligated_amount / descriptionPrevious value: -"Total obligated amount in USD for current fiscal year"New value: +"Total amount obligated in USD for the fiscal year"Output schema / properties / outlay_amountAdded value: +{
+ "description": "Total outlays in USD for the fiscal year",
+ "type": "number"
+}Output schema / properties / sub_agencies / descriptionPrevious value: -"Sub-agency breakdown within this toptier agency"New value: +"Sub-agency breakdown within this toptier agency (one page)"Output schema / properties / sub_agency_pageAdded value: +{
+ "description": "Current sub-agency page returned",
+ "type": "number"
+}Output schema / properties / sub_agency_page_metadataAdded value: +{
+ "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"
+}Output schema / properties / sub_agency_totalAdded value: +{
+ "description": "Total sub-agencies across all pages (when available)",
+ "type": "number"
+}Output schema / properties / transactions_countRemoved value: -{
- "description": "Total transaction count",
- "type": "number"
-}Output schema / requiredAdded value: +[
+ "sub_agency_page",
+ "has_more_sub_agencies"
+]usaspending_get_award1 field changedOutput schema / properties / transactions_countRemoved value: -{
- "description": "Number of transactions; use with usaspending_get_award_transactions",
- "type": "number"
-}usaspending_get_award_transactions1 field changedOutput schema / properties / notice / descriptionPrevious value: -"Guidance when no transactions were returned — suggests checking transactions_count from usaspending_get_award first. Absent when results are present."New value: +"Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present."usaspending_get_recipient9 fields changedOutput schema / properties / business_types_descriptionRemoved value: -{
- "description": "Human-readable business type descriptions",
- "items": {
- "type": "string"
- },
- "type": "array"
-}Output schema / properties / location / properties / zipAdded value: +{
+ "description": "ZIP code",
+ "type": "string"
+}Output schema / properties / location / properties / zip4Added value: +{
+ "description": "ZIP+4 extension",
+ "type": "string"
+}Output schema / properties / location / properties / zip5Removed value: -{
- "description": "5-digit ZIP code",
- "type": "string"
-}Output schema / properties / totalRemoved value: -{
- "additionalProperties": false,
- "description": "Total award amounts by type",
- "properties": {
- "contracts": {
- "description": "Total contracts amount in USD",
- "type": "number"
- },
- "direct_payments": {
- "description": "Total direct payments amount in USD",
- "type": "number"
- },
- "grants": {
- "description": "Total grants amount in USD",
- "type": "number"
- },
- "loans": {
- "description": "Total loans amount in USD",
- "type": "number"
- },
- "other": {
- "description": "Total other financial assistance amount in USD",
- "type": "number"
- }
- },
- "type": "object"
-}Output schema / properties / total_face_value_loan_amountAdded value: +{
+ "description": "Total face value of loans in USD",
+ "type": "number"
+}Output schema / properties / total_face_value_loan_transactionsAdded value: +{
+ "description": "Number of face-value loan transactions",
+ "type": "number"
+}Output schema / properties / total_transaction_amountAdded value: +{
+ "description": "Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided",
+ "type": "number"
+}Output schema / properties / total_transactionsAdded value: +{
+ "description": "Total number of award transactions",
+ "type": "number"
+}usaspending_autocomplete6 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (1–50)"New value: +"Maximum number of results to return (1–500). The recipient lookup enforces an upstream max of 500; naics/psc/cfda/awarding_agency return only their matching entries regardless."Input schema / properties / limit / maximumPrevious value: -50New value: +500Output schema / properties / results / items / descriptionPrevious value: -"Matched code entry with optional code, name, and ID fields"New value: +"Matched entry — code/name for code lookups, name plus optional UEI/DUNS for recipients"Output schema / properties / results / items / properties / dunsAdded value: +{
+ "description": "DUNS number (legacy) — recipient type only; populated when the search text matches a DUNS",
+ "type": "string"
+}Output schema / properties / results / items / properties / id / descriptionPrevious value: -"Numeric or string ID (for agency and recipient types)"New value: +"Numeric or string ID (for the awarding_agency type)"Output schema / properties / results / items / properties / ueiAdded value: +{
+ "description": "Unique Entity Identifier (SAM.gov) — recipient type only; populated when the search text matches a UEI",
+ "type": "string"
+}usaspending_get_idv_awards3 fields changedOutput schema / properties / has_next_page / descriptionPrevious value: -"Whether there are more pages of child awards"New value: +"Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none."Output schema / properties / page_metadata / properties / has_next / descriptionPrevious value: -"Whether there are more pages of results"New value: +"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."Output schema / properties / truncated / descriptionPrevious value: -"True when more child awards remain beyond this page."New value: +"True when this page was full and more child awards may remain beyond it."usaspending_search_recipients15 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum results to return (1–100)"New value: +"Maximum results per page (1–100)"Input schema / properties / pageAdded value: +{
+ "default": 1,
+ "description": "Page number (1-based) — request the next page to retrieve matches beyond the first",
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / properties / capRemoved value: -{
- "description": "The limit that was applied.",
- "type": "number"
-}Output schema / properties / has_nextAdded value: +{
+ "description": "Whether there are more pages of results",
+ "type": "boolean"
+}Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — suggests how to broaden the search. Absent when results are present."New value: +"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."Output schema / properties / pageAdded value: +{
+ "description": "Current page number returned",
+ "type": "number"
+}Output schema / properties / page_metadataAdded value: +{
+ "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"
+}Output schema / properties / recipient_count / descriptionPrevious value: -"Number of matching recipients returned"New value: +"Number of matching recipients returned on this page"Output schema / properties / results / items / properties / locationRemoved value: -{
- "additionalProperties": false,
- "description": "Recipient address location",
- "properties": {
- "city_name": {
- "description": "City of recipient address",
- "type": "string"
- },
- "country_code": {
- "description": "Country code",
- "type": "string"
- },
- "state_code": {
- "description": "State code",
- "type": "string"
- }
- },
- "type": "object"
-}Output schema / properties / results / items / properties / stateRemoved value: -{
- "description": "State code of recipient address",
- "type": "string"
-}Output schema / properties / shownRemoved value: -{
- "description": "Number of recipients returned.",
- "type": "number"
-}Output schema / properties / totalRemoved value: -{
- "description": "Number of results returned",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total matching recipients across all pages",
+ "type": "number"
+}Output schema / properties / truncatedRemoved value: -{
- "description": "True when results were capped at the limit.",
- "type": "boolean"
-}Output schema / requiredPrevious value: -[
- "results",
- "total",
- "recipient_count"
-]New value: +[
+ "results",
+ "page_metadata",
+ "recipient_count",
+ "page",
+ "has_next"
+]usaspending_search_awards15 fields changedInput schema / properties / filtersAdded value: +{
+ "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, 02/03/04/05, 06/10, 07/08, IDV_A–IDV_E)",
+ "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": {
+ "description": "End date (YYYY-MM-DD). Requires time_period_start.",
+ "type": "string"
+ },
+ "time_period_start": {
+ "description": "Start date (YYYY-MM-DD); earliest valid 2007-10-01. Requires time_period_end.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}Input schema / properties / last_record_sort_valueAdded 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. When both cursor fields are supplied, page is ignored.",
+ "type": "string"
+}Input schema / properties / last_record_unique_idAdded value: +{
+ "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"
+}Input schema / properties / page / descriptionPrevious value: -"Page number (1-based)"New value: +"Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit); to read past that, use the cursor fields below."Input schema / properties / recipient_name / descriptionPrevious value: -"Filter by recipient name (partial match). Use usaspending_search_recipients for precise recipient_id filtering."New value: +"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."Output schema / properties / capAdded value: +{
+ "description": "Per-page cap (limit) applied to this page.",
+ "type": "number"
+}Output schema / properties / page_metadata / descriptionPrevious value: -"Pagination metadata"New value: +"Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page."Output schema / properties / page_metadata / properties / last_record_sort_valueAdded 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",
+ "type": "string"
+}Output schema / properties / page_metadata / properties / last_record_unique_idAdded value: +{
+ "description": "Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value",
+ "type": "number"
+}Output schema / properties / page_metadata / properties / totalRemoved value: -{
- "description": "Total number of matching awards",
- "type": "number"
-}Output schema / properties / results / items / properties / agency_slugAdded value: +{
+ "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"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of awards returned on this page.",
+ "type": "number"
+}Output schema / properties / totalCountRemoved value: -{
- "description": "Total number of matching awards across all pages (when available)",
- "type": "number"
-}Output schema / properties / truncatedAdded value: +{
+ "description": "True when this page was capped at `limit` and more results remain (continue via page or the cursor).",
+ "type": "boolean"
+}Output schema / properties / upstream_messagesAdded value: +{
+ "description": "Notices the USAspending API returned for this request — e.g. a supplied filter that was ignored because this endpoint does not support it, or the 2007-10-01 date-floor note. Present whenever the API returns any messages.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}usaspending_disaster_spending6 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum results per page (1–100, not used for overview dimension)"New value: +"Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated."Input schema / properties / spending_type / descriptionPrevious value: -"Data type: award (award-level obligations and outlays) or total (includes direct non-award spending). Applies to agency and recipient dimensions only."New value: +"Data type for the agency and recipient dimensions: award (award-level obligations and outlays) or total (includes direct non-award spending). Ignored for cfda and overview; the geography dimension is not user-controllable and always reports obligation-based amounts."Output schema / properties / results / items / properties / aggregated_amount / descriptionPrevious value: -"Aggregated amount in USD (geography dimension)"New value: +"Obligation-based spending amount in USD (geography dimension)"Output schema / properties / results / items / properties / per_capitaAdded value: +{
+ "description": "Obligation-based spending per capita in USD (geography dimension)",
+ "type": "number"
+}Output schema / properties / results / items / properties / populationAdded value: +{
+ "description": "Population of the geographic area (geography dimension)",
+ "type": "number"
+}Output schema / properties / spending_type / descriptionPrevious value: -"Data type returned (award or total)"New value: +"Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview"usaspending_autocomplete3 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of results returned.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when results were capped at the limit.",
+ "type": "boolean"
+}usaspending_disaster_spending2 fields changedOutput schema / properties / result_totalRemoved value: -{
- "description": "Total items for paginated dimensions (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total items for paginated dimensions (when available)",
+ "type": "number"
+}usaspending_get_award_subawards2 fields changedOutput schema / properties / subaward_totalRemoved value: -{
- "description": "Total subaward count across all pages (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total subaward count across all pages (when available)",
+ "type": "number"
+}usaspending_get_award_transactions2 fields changedOutput schema / properties / totalCountAdded value: +{
+ "description": "Total transaction count across all pages (when available)",
+ "type": "number"
+}Output schema / properties / transaction_totalRemoved value: -{
- "description": "Total transaction count across all pages (when available)",
- "type": "number"
-}usaspending_get_idv_awards3 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The per-page limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of child awards returned on this page.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when more child awards remain beyond this page.",
+ "type": "boolean"
+}usaspending_search_awards2 fields changedOutput schema / properties / totalRemoved value: -{
- "description": "Total number of matching awards across all pages (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of matching awards across all pages (when available)",
+ "type": "number"
+}usaspending_search_federal_accounts2 fields changedOutput schema / properties / totalRemoved value: -{
- "description": "Total number of matching accounts across all pages (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of matching accounts across all pages (when available)",
+ "type": "number"
+}usaspending_search_recipients3 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of recipients returned.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when results were capped at the limit.",
+ "type": "boolean"
+}usaspending_spending_by_category2 fields changedOutput schema / properties / totalRemoved value: -{
- "description": "Total number of items in this category (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of items in this category (when available)",
+ "type": "number"
+}usaspending_get_award_subawards1 field changedOutput schema / properties / noticeAdded value: +{
+ "description": "Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present.",
+ "type": "string"
+}usaspending_get_award_transactions1 field changedOutput schema / properties / noticeAdded value: +{
+ "description": "Guidance when no transactions were returned — suggests checking transactions_count from usaspending_get_award first. Absent when results are present.",
+ "type": "string"
+}usaspending_get_idv_awardsusaspending_search_awards7 fields changedInput schema / properties / naics_codeRemoved value: -{
- "description": "Filter by NAICS industry code (e.g., \"541512\"). Use usaspending_autocomplete type=naics to look up codes.",
- "type": "string"
-}Input schema / properties / naics_codesAdded value: +{
+ "description": "Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete type=naics to look up codes.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordAdded value: +{
+ "description": "Keyword filter applied to this search",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS codes filter applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_search_federal_accountsusaspending_spending_by_category5 fields changedOutput schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordsAdded value: +{
+ "description": "Keyword filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS code filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_spending_by_geography5 fields changedOutput schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordsAdded value: +{
+ "description": "Keyword filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS code filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_spending_over_time5 fields changedOutput schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordsAdded value: +{
+ "description": "Keyword filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS code filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}USAspending MCP — Federal spending data from USAspending.gov API
See who wins US federal contracts and grants (USAspending.gov). $0.02/call via x402.
US federal contracts, grants, and spending awards
SAM.gov contract opportunities and entity lookup (BYOK) plus USASpending federal award data.
Add one secure layer between your agents and this server.