Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Scored across 18 tools
Tools are split cleanly by resource and action: search_* vs get_* vs list_*, and the aggregation tools (spending_by_category, spending_by_geography, spending_over_time) each target a distinct axis. Descriptions actively disambiguate close pairs (e.g. get_federal_account vs get_federal_account_breakdown, get_award_federal_accounts vs account_obligations_by_defc), though minor overlap remains between autocomplete_filters (type=recipient/naics) and the dedicated search_* lookups.
All names share the usaspending_ prefix and snake_case, with predictable verb_noun forms (search_awards, get_recipient, list_agencies). A few are noun-phrase style (spending_by_category, disaster_spending) and the verb set mixes search/get/list, but the pattern stays readable and consistent overall.
18 tools is slightly heavy but justified by the breadth of the domain — awards, recipients, agencies, federal accounts, IDVs, subawards, transactions, and three aggregation axes plus disaster spending. Each tool maps to a genuine query need rather than a redundant variant.
Strong lifecycle coverage: discovery (list_agencies, search_*), detail (get_award, get_recipient, get_federal_account), and drill-down chains (subawards, transactions, IDV children, award→federal accounts→account breakdown) plus aggregation and disaster spending. Gaps are minor — no reference/glossary tool for code systems (award type, DEF code semantics) beyond autocomplete, and no direct CFDA program detail or recipient-awards listing shortcut.
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 — agency_name filters take the matched name; a sub-tier name shared by several parents matches under all parents), 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. Agency matches combine independently capped top-tier then sub-tier buckets, preserving their order without deduplicating names; offices are excluded. 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. Every lookup returns at most limit rows. | |
| 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 profile is covered, and the description adds real behavior: awarding_agency results carry tier and top-tier parent, and a sub-tier name shared by several parents matches under all parents, which materially affects how downstream agency_name filters behave. Return-shape detail (UEI/DUNS on recipients, code+name pairs) is partially duplicated from the schema, but the matching semantics are genuinely new.
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?
It is front-loaded with purpose, then alternatives, then the return contract, and every sentence carries information. The type enumeration partially restates the schema's enum descriptions, which is mild redundancy in an otherwise efficient paragraph.
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 need not spell out return values, and annotations cover the safety profile; what remains — when to call it, what each lookup table yields, and how matched names propagate into filters — is all present. An agent could invoke this correctly on the first attempt.
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 earns extra credit by mapping each enum value to the filter it feeds (psc→psc_codes, cfda→assistance_listings) and by explaining the agency_name consumption rule, which the schema does not state. It adds no comparable depth for search_text or limit, but limit is already thoroughly documented in 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?
The description opens with a specific verb+resource ('Look up valid code values for filter fields by searching free-text descriptions') and enumerates the five lookup tables, so an agent can distinguish it from siblings like usaspending_search_recipients or usaspending_search_awards without opening the schema. The framing as a code-resolution helper rather than a general search is 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?
'Call this before filtering awards when you know a description but not the exact code' gives an explicit triggering condition and the downstream consumers of the results. It stops short of explicit exclusions — notably it never says how it differs from usaspending_search_recipients, which also returns recipient names, so an agent must infer that this tool is for code resolution only.
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 broken down by agency, CFDA assistance program, recipient, or geography, or request an overview. Filter by DEF codes to select emergency appropriations, then check amount_coverage before interpreting amounts: award breakdowns and geography cover the provider COVID grouping, while overview and agency total cover all requested codes. Rows and award counts can match codes outside the monetary scope. 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). Breakdowns rank obligations descending before pagination; geography ranks aggregated_amount. Agency award without award_type_codes collects all provider pages before ranking, so a smaller limit does not reduce that upstream work. 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 | Upstream messages, ignored filters, empty-page recovery, and guidance for recipient ceilings or remaining geography areas. |
| 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) |
| applied_query | No | Trimmed recipient query sent upstream |
| 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 |
| amount_coverage | No | Scope of all monetary fields, including geography amounts/per-capita and totals; independent of row membership and counts |
| applied_def_codes | No | DEF codes applied (comma-separated) |
| applied_dimension | No | Breakdown dimension applied |
| truncationCeiling | No | geography: the lowest aggregated_amount on this page within amount_coverage — no area on a later page has a higher reported value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, open-world behavior, yet the description adds genuinely non-obvious traits: award breakdowns and geography aggregate only the provider COVID grouping while overview and agency total cover all requested codes, and matching rows/counts can include codes outside the monetary scope. That is exactly the kind of caveat an agent needs before reporting numbers. It stops short of 5 because nothing is said about pagination cost or failure modes (those live only in the limit schema text).
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 purpose is front-loaded in sentence one, but the second sentence is a single overloaded clause bundling DEF code selection, amount_coverage checking, and per-dimension scope. Substantial portions of the amount-coverage explanation duplicate the def_codes schema description almost verbatim, so the text is dense and partly redundant rather than wasteful.
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 the description needn't document return fields, and it still flags amount_coverage interpretation, which is the main interpretation hazard. Combined with the rich schema for dimension, spending_type, and limit, an agent has enough to call it correctly. The main gap is the absence of sibling routing for overlapping spending tools.
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 a 3 is the baseline; the description earns above that by adding DEF code discovery pointers ('usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields'), which the schema only partially mirrors. It also ties def_codes semantics to per-dimension amount coverage, giving meaning to the filter beyond its pattern/length constraints.
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 first sentence gives a specific verb ('Fetch') and a specific resource ('disaster and emergency supplemental spending'), then enumerates the four breakdown axes plus the overview mode, matching the dimension enum. It is clear what the tool returns, though it does not explicitly distinguish itself from siblings like usaspending_spending_by_geography or usaspending_spending_by_category, which overlap in shape.
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 real operational guidance — use DEF codes to select emergency appropriations, and check amount_coverage before interpreting amounts — and routes the agent to usaspending_get_agency/get_award to find DEF codes. However, it never explains when to pick this tool over the generic spending_by_category/spending_by_geography siblings, and the requirement that def_codes is mandatory for non-overview dimensions is only stated in the schema, not the description.
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 directory toptier_code (e.g., 097 for DoD, 1601 for Labor; one/two-digit numeric inputs are zero-padded to three digits) 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 | Directory toptier agency code (e.g., 097, 012, 1601) from usaspending_list_agencies. One/two-digit numeric values are padded to three digits (80 becomes 080); three/four-digit codes are preserved. 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 | Directory toptier agency code, which can have three or four digits |
| 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?
Goes well beyond the readOnly/idempotent/closed-world annotations by disclosing fallback semantics (sub-agency year defaults to the current fiscal year when no budget year is available within 5 seconds), the sub_agency_fiscal_year field that names which year is returned, and graceful degradation via unavailable_sections with per-section reasons. The 5-second timeout and partial-failure behavior are exactly the kind of operational context annotations cannot 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 what is returned, then moves to input identification, then to failure behavior — a sensible order with no filler sentences. It is dense to the point of being a single long paragraph, and the zero-padding detail is repeated from the schema, so it is not maximally tight.
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 shape need not be explained, yet the description still explains the non-obvious pieces: which fiscal year the two sections cover and how missing sections are surfaced. For a three-parameter, read-only overview tool this leaves no operational question an agent would need answered before calling 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 coverage is 100%, so the baseline is 3, but the description adds the exactly-one-of constraint between toptier_code and agency_slug that the schema does not enforce (no oneOf/anyOf), plus a concrete zero-padding rule and real code examples. Page semantics are left entirely to the schema, keeping this just below a 5.
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 an agency's fiscal-year overview') and enumerates the contents: mission, budgetary resources, obligation/outlay totals, sub-agency count, DEF codes, and a paginated sub-agency breakdown. This is clearly distinguishable from the sibling usaspending_list_agencies, which is referenced only as a source of codes.
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?
Explains input selection ('exactly one directory toptier_code ... or an agency_slug') and points to usaspending_list_agencies and award search results as where those identifiers come from, which implicitly routes list-level discovery to the sibling. It does not explicitly say when NOT to use this tool or name an alternative for the same data, 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 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 |
| total_account_outlay | No | Total federal-account outlay in USD |
| period_of_performance | No | Period of performance dates |
| base_exercised_options | No | Base and exercised options value in USD when reported for contracts or IDVs |
| account_outlays_by_defc | No | Federal-account outlays by Disaster/Emergency Funding code in upstream order |
| product_or_service_code | No | Product or service code (contracts) |
| total_account_obligation | No | Total federal-account obligation in USD |
| generated_unique_award_id | No | Generated unique award ID |
| base_and_all_options_value | No | Base and all options value in USD (contracts) |
| account_obligations_by_defc | No | Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, openWorld=false, so the safety profile is covered. The description adds substantive behavioral detail about scope (loan face value/subsidy, funding account linkages, subaward count) that helps an agent judge whether this call answers its question, though it says nothing about payload size or error behavior for an invalid ID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and input source are front-loaded, and every sentence routes the agent somewhere useful. The long enumerations of returned fields are dense but mostly earn their place, though they overlap with the existing output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-ID read tool with full annotation coverage and an output schema, the description covers what an agent needs: input provenance, the IDV exception, and where to send the hashes/NAICS it receives. Nothing required for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter and schema description coverage is 100%, so the schema already explains award_id and its format. The description reinforces the provenance rule (use generated_internal_id from search_awards) but adds little beyond what the schema states, making the baseline 3 correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch full details of a federal award by its generated unique award ID') and immediately scopes the return content. It distinguishes itself from usaspending_search_awards and explicitly carves out IDV-category awards for usaspending_get_idv_awards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to use generated_internal_id values from usaspending_search_awards as input, and gives the exact when-to-use-alternative rule: for category="idv" use usaspending_get_idv_awards. It also names downstream tools (get_recipient, search_awards) for follow-up data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 for an empty page, distinguished from a known zero total; 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?
Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description still adds real behavioral detail beyond them: the AGENCY-MAIN row format with an example (080-0120), and the important edge case that a nonexistent award_id yields an empty list rather than an error. Pagination defaults are left entirely to 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?
Four sentences, front-loaded with what the tool returns, then chaining, then differentiation, then the edge case — a sensible priority order with no filler. The main inefficiency is the award_id provenance being repeated almost verbatim from the schema, which adds length without adding information.
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 handling return values and full annotation coverage of safety semantics, what remains for the description — row contents, ID format, chaining target, sibling disambiguation, and empty-result behavior — is all present. An agent has everything needed to select and call this 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 schema already documents all three parameters, including the exact provenance of award_id. The description's restatement that award_id must be a generated_unique_award_id with the same two source fields is emphasis rather than new meaning, and page/limit are never mentioned. Baseline 3 applies when the schema carries the parameter burden.
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 — 'List the Treasury federal accounts that funded an award' — and immediately names the payload of each row (amount obligated, funding agency). It also distinguishes itself from two named siblings, usaspending_get_federal_account and usaspending_get_award's account_obligations_by_defc, so an agent can route without opening another 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 states the tool's role in a workflow ('This is the award → appropriation link') and names the downstream tool to chain into. It explicitly carves out the alternative case: use account_obligations_by_defc instead when the split needed is by Disaster/Emergency Funding code rather than by 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 establish read-only, idempotent, and closed-world behavior, so the bar is lower. The description adds useful context beyond the annotations by describing what the result rows contain and clarifying the real-world meaning of subawards. It does not address pagination behavior or rate limits, which keeps it from a 5.
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: the purpose and semantic layer come first, the row contents second, and the precondition last. There is no filler or repetition.
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 and annotations covering safety, the description supplies the key missing context — the real-world meaning of a subaward and the prerequisite check. It is nearly complete, though it could mention pagination expectations for large subaward sets.
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 page, sort, limit, order, and award_id with enums and defaults. The description adds only indirect context by mentioning the returned fields, which map loosely to the sort enum, but provides no additional parameter guidance. 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 states a specific verb and resource ('List subaward contracts or grants under a prime federal award') and explains the semantic layer being retrieved — the sub-contractor or sub-grantee organizations that actually perform the work. This clearly distinguishes it from siblings like usaspending_get_award or usaspending_get_award_transactions.
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 an explicit precondition and names the sibling to consult first: 'Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.' That directly tells the agent when to call this versus the parent award tool, removing guesswork.
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 readOnly, idempotent, closed-world, so the safety profile needs no restating. The description adds genuine domain semantics about what each returned transaction represents (obligation modifications, performance period extensions, scope changes), which is context the annotations cannot provide. It stops short of describing pagination/result-set behavior for large awards.
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 short sentences, front-loaded with the verb and resource, then domain semantics, then the prerequisite for the required ID. No redundancy with the schema or annotations.
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?
Output schema exists, so return-value explanation is unnecessary, and the annotations cover safety semantics. What remains — what the tool is for and where the required award_id comes from — is fully addressed, leaving nothing an agent needs in order to call 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 description coverage is 100% and all five parameters (page, limit, sort, order, award_id) carry their own descriptions, so the baseline is 3. The description reinforces the provenance of the required award_id, but adds no format guidance 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?
States a specific verb and resource ('List individual transactions... on a federal award') and explicitly characterizes what a transaction is (contract modifications, grant amendments, change events), which separates it from the award-summary siblings. It doesn't explicitly name usaspending_get_award as the alternative for summary data, so the differentiation is implied rather than stated.
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?
'Use this to trace the spending history and obligation changes over the life of an award' gives clear intent, and the prerequisite is spelled out: award IDs come from usaspending_search_awards (generated_internal_id field). No when-not-use or explicit alternative routing is provided.
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. fiscal_year selects a reporting year; omit it for the current federal fiscal year. An empty year retains metadata and a notice, without substituting another year. 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 |
|---|---|---|---|
| fiscal_year | No | Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint 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. |
| notice | No | Explains when the selected fiscal year has no financial totals or Treasury Account Symbol components; no alternative year is substituted |
| 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 cover read-only, idempotent, closed-world behavior, and the description adds a non-obvious edge case beyond them: an empty year 'retains metadata and a notice, without substituting another year' — so the agent won't mistake a sparse response for a failure. It does not mention error modes or pagination limits for the children list, keeping it short of a 5.
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 return payload, then defaults, then code provenance, then the alternative — a sensible ordering with no wasted lead-in. It is on the dense side at six sentences, and the background line about appropriations law is context rather than instruction, but nothing is misleading or padded enough to hurt.
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 and full annotation coverage in place, the description only needs to supply routing, defaults, and edge cases — and it does all three, including how to obtain the required account_code from two sibling tools. An agent could call this correctly on the first attempt from the description alone.
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 already spells out the AGENCY-MAIN format and the 097-0100 example, so much of the description's parameter text is restatement. It does add real meaning by resolving the schema's vague 'preserve the endpoint default' into 'omit it for the current federal fiscal year', and by naming the exact upstream output fields that supply the code.
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 ('Fetch a federal account's budget data') and enumerates what comes back: total obligations, gross outlays, budgetary resources, plus the per-TAS children breakdown. That scope statement separates it cleanly from the sibling breakdown and search tools without needing their schemas.
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 explicit when-to-use signals (omit fiscal_year for the current FY), names the two sources for the required account_code, and routes the agent elsewhere for the specific alternative case: 'For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.' Both the substitute and the condition are stated.
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. fiscal_year scopes financial reporting periods to the full October–September year, not award action dates; omit it for all available periods. 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) | |
| fiscal_year | No | Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint 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. |
| notice | No | Recovery for an empty page, distinguished from a known zero total; absent when results are present. |
| period | No | FY<year> for a selected year, otherwise all available periods |
| 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) |
| fiscal_year | No | Fiscal year selected by the caller; omitted for all available periods |
| time_period | No | Full fiscal-year range applied to financial reporting periods, not award action dates; omitted for all available periods |
| 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 readOnly/idempotent/closed-world, and the description adds behavior beyond them: pagination with a meaningful total count, and the important caveat that fiscal_year follows the October–September federal year rather than award action dates. That date-semantics warning is exactly the kind of non-obvious trait an agent cannot infer from annotations or 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?
Front-loaded with the verb and resource, then prerequisites, then the sibling hand-off — no wasted sentences. Slight redundancy with the schema on the dimension axis keeps it from being maximally tight.
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, full annotation coverage, and complete parameter documentation, the description supplies everything else an agent needs: axis choice, fiscal-year semantics, code format and origin, pagination, and the alternative tool. Nothing material 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 earns more by explaining that fiscal_year is a reporting period (Oct–Sep) distinct from award action dates and by stating the AGENCY-MAIN format and provenance of account_code. The dimension explanation largely restates the enum documentation, so it stops short of a 5.
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?
Specific verb+resource: fetches a federal account's obligations broken down by program activity or object class, with both axes named. It explicitly distinguishes itself from usaspending_get_federal_account (metadata and top-level totals) and implies its difference from category/geography spending tools by scoping to a single account.
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 when to use each axis, when to omit fiscal_year, and names the exact sibling to use instead for account metadata and totals. It also tells the agent where account codes must come from (search_federal_accounts account_number, get_award_federal_accounts federal_account, or get_federal_account), closing the main prerequisite gap.
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?
Beyond the read-only and idempotent annotations, it explains the parent-child award relationship and discloses that each result includes generated_unique_award_id for follow-up detail retrieval. It does not add operational details such as empty-result behavior or rate limits, but the workflow context is substantive.
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 front-loaded with the operation and scope, then efficiently covers result chaining, identifier requirements, and applicability. Its four sentences each serve a distinct purpose without unnecessary background.
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?
Together with the fully documented input schema and output schema, the description supplies the identifier provenance and cross-tool workflow needed to invoke the tool correctly. Sorting, pagination, and child-type options are already adequately handled by the schema.
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 already documents the parent IDV identifier, its sources, pagination, sorting, and child-award types. The description reinforces the award_id requirement and acquisition workflow but adds little parameter meaning beyond those structured descriptions.
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 uses a specific verb and resource: it lists child contracts and task/delivery orders under a parent IDV. It also distinguishes this relationship-listing tool from usaspending_get_award, which is used for full award detail.
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 an explicit workflow: obtain the parent IDV identifier from usaspending_search_awards or usaspending_get_award, then use returned child identifiers to chain into usaspending_get_award. The final sentence clarifies that the tool applies to IDV-category awards with child orders.
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 hexadecimal 8-4-4-4-12 hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Totals cover the trailing 12 months unless fiscal_year selects one fiscal year, and period names the window. For a recipient's totals by award type, use usaspending_spending_over_time with filters.recipient_id and award_type_codes. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.
| Name | Required | Description | Default |
|---|---|---|---|
| fiscal_year | No | Fiscal year to scope the totals to (e.g., 2024, which runs October 2023 through September 2024). Omit for the trailing 12 months. | |
| recipient_id | Yes | Recipient hexadecimal 8-4-4-4-12 hash with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P — from usaspending_search_recipients or usaspending_get_award |
| 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 description is not burdened with safety disclosure. It still adds real behavioral context the annotations lack: the default aggregation window (trailing 12 months) versus a fiscal-year scope, and that a period name labels the window. It does not discuss pagination or error cases, but the output schema covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each carrying information: contents, ID sourcing, time-window semantics, and an alternative tool. It is front-loaded with the payload description, though the ID format sentence partially duplicates the schema and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read of a single entity with annotations and an output schema, the description supplies everything needed to call it correctly: valid ID provenance, default time window, fiscal-year override, and the sibling to use for award-type breakdowns. Only marginal items like cross-referencing semantics of UEI/DUNS remain thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented, including the hash format and the fiscal-year example. The description restates the ID format and the trailing-12-month default rather than adding new meaning, apart from noting UEI and DUNS can be cross-referenced with SAM.gov and SEC EDGAR, which is marginal value. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb and resource ('Fetch a recipient's full profile') and enumerates the returned contents — address, business type codes, parent organization, alternate names, total transaction and loan amounts. It is clearly distinguishable from usaspending_search_recipients (which supplies IDs) and usaspending_spending_over_time (which handles award-type breakdowns).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent where recipient IDs come from (usaspending_search_recipients or usaspending_get_award) and explicitly routes a related need — totals by award type — to usaspending_spending_over_time with the relevant filter fields. It does not state exclusions such as when to prefer usaspending_get_award instead, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the latest reported period. Returns the full directory unless limit is supplied; optional pagination slices the provider-sorted directory. 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 |
|---|---|---|---|
| page | No | Page number when limit is supplied (defaults to page 1); ignored without limit. | |
| sort | No | Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount | agency_name |
| limit | No | Agencies per page; omitted returns the full directory. No maximum. | |
| 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 in the full directory before pagination |
| results | No | List of top-tier federal agencies with budget and obligation data |
| has_next | No | Whether another page exists; present only when limit is supplied |
| totalCount | No | Total number of agencies in the full directory before pagination |
| 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 establish read-only, idempotent, closed-world behavior, so the description only needs to add operational context, and it does: full directory by default, pagination only meaningful when limit is supplied, and a provider-sorted ordering. It stops short of describing result size or whether the full directory is large enough to warrant paging, which would complete the picture.
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 compact sentences ordered by importance: what it returns, how paging behaves, then why to call it. No filler, no restatement of the title, and the routing advice lands last where it is actionable.
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 zero-required-parameter read tool with a full output schema, the description covers everything an agent needs: scope of the directory, default versus paginated behavior, and its role as a prerequisite for sibling tools. Return-value detail is correctly delegated to the output schema.
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 every parameter already documents itself, so the description is only required to avoid contradicting it. The default-behavior restatement (full directory without limit) is useful, but the phrase "provider-sorted directory" sits awkwardly against the explicit sort/order parameters and could momentarily confuse an agent about whether it controls ordering.
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 ("List top-tier federal agencies") and names exactly what the records carry: toptier codes, agency slugs, budget authority amounts, obligation totals for the latest reported period. That inventory cleanly separates it from usaspending_get_agency, which takes a single agency as input.
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 frames itself as "the entry point for agency navigation" and states the downstream condition — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based spending filters. An agent knows both when to call this and what to do with the output.
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; effective keywords need at least three characters without trimming; empty is unset | |
| 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 | Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents. | |
| naics_codes | No | NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated. 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 the applied filters on an empty page. This endpoint supplies no total, so an empty page does not establish zero matches. 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 only declare read-only, idempotent, open-world access; the description adds substantive behavior: results are ranked summaries, loan rows substitute loan value/subsidy cost/issue date for amount and dates, and coverage is bounded by a 2007-10-01 floor and a 90-day DoD publication lag. Those are exactly the surprises an agent would otherwise misread as missing data.
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 filter list are front-loaded, followed by return shape and then the caveats that matter most (date floor, DoD lag). The inline enumeration of every award-type code duplicates the award_type_codes schema description and is the one length cost that does not fully earn 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?
For a 17-parameter, deeply nested search tool with an output schema, the description covers the things structured fields cannot: what a result row means, the loan-row exception, the temporal boundary of the corpus, and the downstream handoff. Nothing essential to calling 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% and the schema already spells out sort group rules, keyset cursor semantics, PSC/DEF/assistance-listing interactions, and type-mismatch rejections, so the schema carries the parameter burden. The description only restates the award-type groupings and the ISO date format, both of which are already documented per-parameter, so it adds little beyond the 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 ("Search federal awards") plus the full set of filter dimensions, then says what comes back (ranked award summaries with recipient names, amounts, agencies, and award IDs). It explicitly routes to the sibling usaspending_get_award for the IDs it returns, so an agent can distinguish it from detail-oriented siblings 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?
The description makes the search-then-fetch workflow explicit by naming usaspending_get_award as the consumer of returned award IDs, and gives the data-coverage conditions (earliest 2007-10-01, 90-day DoD contract lag) that tell an agent when results will look empty. It does not explicitly say when to prefer usaspending_spending_by_category or usaspending_search_recipients, though code-lookup pointers to usaspending_autocomplete_filters live in the schema.
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 directory toptier code or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. fiscal_year selects the resource amounts, not account membership; omit it for the latest available submission year. Search and detail totals use different calculations and can differ for the same year. Use account_number from results as input to usaspending_get_federal_account for full budget detail. Use usaspending_list_agencies to look up the input agency_identifier (directory toptier_code, e.g. "097" for DoD or "1601" for Labor); account rows return their account-prefix agency_identifier, e.g. "016" for Labor.
| 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 |
| fiscal_year | No | Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default. | |
| sort_direction | No | Sort direction | desc |
| agency_identifier | No | Directory toptier_code from usaspending_list_agencies (e.g., "097" for Defense, "1601" for Labor). This differs from the account-prefix agency_identifier returned in account rows (e.g., "016" for Labor). |
| 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) |
| fiscal_year | No | Effective fiscal year of the budgetary resources, as reported by USAspending; account membership spans all submitted years |
| 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 safety is covered; the description adds non-obvious behavior instead, namely that fiscal_year selects resource amounts rather than account membership and that search versus detail totals can diverge for the same year. It stops short of describing paging behavior or result-set ceilings, which are the remaining behavioral gaps.
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 purpose is front-loaded in the first sentence, followed by return fields, then caveats, then routing — a sensible order with no filler. It loses a point for restating the account-prefix versus directory toptier_code distinction that the schema already documents, which lengthens the final sentence without new information.
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 7-parameter, all-optional search tool with a full output schema, the description covers the essentials: what is returned, how fiscal year affects results, why totals may not match detail calls, and which sibling to call next. Nothing an agent needs in order 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, but the description does add meaning beyond the schema for fiscal_year (it changes amounts, not membership; omit for the latest submission year) rather than merely restating the endpoint default. The agency_identifier explanation largely mirrors its schema description, so the gain is incremental rather than comprehensive.
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: 'List and keyword-search federal accounts by directory toptier code or title keyword,' and names the two dimensions available for filtering. It also names the return payload (account numbers, names, managing agencies, budgetary resources), so an agent can distinguish this list/search tool from usaspending_get_federal_account and usaspending_list_agencies without opening either 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?
Routing is explicit in both directions: 'Use account_number from results as input to usaspending_get_federal_account for full budget detail' and 'Use usaspending_list_agencies to look up the input agency_identifier.' It also gives a conditional: omit fiscal_year for the latest available submission year, which tells the agent when not to supply a parameter.
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. Surrounding whitespace is trimmed; blank text applies no keyword filter and is disclosed. | |
| 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 | Blank-keyword disclosure and pagination recovery. An empty page is distinguished from a known zero total; absent when no notice applies. |
| 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 already cover the safety profile (readOnly, idempotent, openWorld), and the description adds real behavioral context on top: pagination behavior, the page_metadata.total full-match count, and the P/C/R recipient hierarchy legend that is not derivable from annotations. The return-field enumeration partially duplicates the output schema, so it is not fully additive.
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?
Well structured and front-loaded: identity of the tool first, then pagination, then the handoff to the sibling, then the level legend. Each sentence is purposeful, though the enumerated return fields are mildly redundant given an output schema exists.
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 four-parameter search tool with a full output schema and read-only annotations, the description covers capability, pagination, follow-up routing, and the code legend well. Minor omissions remain, such as behavior on zero matches or result ordering, but nothing essential to 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 coverage is 100%, so the schema already documents keyword, page, limit, and award_type with defaults, ranges, and enum values. The description restates the pagination meaning of page but adds no new syntax or formatting guidance beyond what the schema provides; the P/C/R legend explains output, not an input parameter.
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 — 'Search for organizations or individuals receiving federal funds' — and names the exact lookup keys (name, UEI, DUNS). It is clearly distinguishable from the sibling usaspending_get_recipient, which it explicitly frames as the follow-up profile lookup.
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 a clear routing rule: use this tool to find recipients, then pass the returned hash ID to usaspending_get_recipient for full profiles. It also explains the pagination workflow via page and page_metadata.total. It stops short of an explicit exclusion (e.g., when to prefer autocomplete or award search instead), so it is strong but not exhaustive.
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_recipient_id | No | Normalized recipient hash and level sent |
| 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 safety profile is covered; the description adds that results are "top items with obligation amounts" and that recipient_duns rows carry recipient_id and uei, which is behavioral detail beyond the annotations. Pagination behavior and what determines the "top" ranking are left implicit, but the output schema covers the response shape.
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: purpose and dimensions first, then filter scope, then chaining/traversal. Dense but largely waste-free, though the filter enumeration duplicates the schema and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 read-only annotations, the description only needs to supply purpose, dimension selection, and cross-tool workflow, which it does. Gaps: the enumerated dimensions omit awarding_subagency and funding_subagency, and there is no guidance on choosing between this and the geography/time-series siblings.
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%, with rich per-field text on DEF codes, PSC prefixes, agency names, and Assistance Listings, so the baseline is 3. The description mostly restates the filter list the schema already documents and adds only the chaining hint, which is workflow rather than added parameter meaning.
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?
"Aggregate federal spending grouped by a specific dimension" gives a precise verb plus resource, then enumerates the dimensions (NAICS, PSC, awarding agency, funding agency, CFDA, recipient) that correspond to the category enum. An agent can distinguish this breakdown tool from siblings like usaspending_spending_over_time or usaspending_spending_by_geography without opening a 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 states the tool is for "trend and breakdown analysis" and gives concrete downstream routing: chain NAICS/PSC/CFDA codes into these filters, into usaspending_search_awards filters, or into usaspending_autocomplete_filters lookups, and use recipient_id to open usaspending_get_recipient. It never explicitly says when to prefer a sibling aggregation tool (geography or time series) instead, so the exclusion side is missing.
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) |
| applied_recipient_id | No | Normalized recipient hash and level sent |
| 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 readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description still adds real behavioral context beyond them: results are ranked by obligation and capped at limit, shape_codes selection runs over every matched area rather than only the returned page, and unmatched codes surface in a notice.
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?
Five tight sentences, front-loaded with purpose, then filters, then area-selection rules, then the geocoding requirement. Dense but every sentence carries operational information; no filler or restatement of the title.
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 and 100% schema coverage, the description need not explain return values, and it covers the tricky parts: code formats, cap behavior, and the geocode-first prerequisite. Minor gap: subawards and the scope choice are left entirely to schema text, so an agent must read the schema to distinguish place-of-performance from recipient aggregation.
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 does add value on shape_codes — spelling out the 2-letter postal, 5-digit FIPS, and 4-digit district formats and warning that place names are rejected — but it says nothing about scope (place_of_performance vs recipient_location), subawards, or limit that the schema does not already carry.
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 and resource: 'Aggregate federal spending by state, county, or congressional district,' naming the three geo_layer granularities. It is clearly distinguishable from siblings like spending_by_category and spending_over_time, which aggregate along different axes.
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 concrete use cases (per-capita analysis, regional comparisons, mapping) and workflow guidance: resolve place names with a geocoding server before calling, use shape_codes to reach areas ranked past the cap, and chain with Census population data. It does not explicitly contrast itself with sibling aggregation tools such as spending_by_category, so it stops short of full when-not guidance.
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 | Discloses effective award-type scope, composes any filled time-window bound, and names active code/recipient filters when no periods are returned. |
| 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_recipient_id | No | Normalized recipient hash and level sent |
| applied_time_period_end | No | End of the time window sent (YYYY-MM-DD), including a filled-in end |
| applied_award_type_codes | No | Effective award type codes sent (comma-separated); totals and every breakdown cover only these codes |
| applied_time_period_start | No | Start of the time window sent (YYYY-MM-DD), including a filled-in start |
| applied_award_type_default | No | Present only when omitted or empty codes select the contract default |
| applied_assistance_listings | No | Assistance Listing numbers sent (comma-separated) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish read-only, idempotent, open-world behavior, and the description adds useful context beyond them: fiscal-year grouping semantics, the October-start convention for fiscal months, the contract default, and that results include per-period totals with optional category breakdowns. It does not disclose every edge case documented in the schema, such as negative DEF-filtered totals or type-mismatch rejections, so it is strong but not exhaustive.
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 front-loaded with the core purpose, followed by fiscal-calendar clarification, filter scope, and return shape. Every sentence carries useful information and there is no filler.
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 nested filters, full schema description coverage, and an output schema, the description is complete enough to support correct selection and invocation. It covers the essential fiscal grouping semantics, defaults, filtering scope, and output shape without needing to duplicate every schema detail.
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 parameter meaning is already fully documented in the input schema. The description summarizes the filter categories and notes the contract default, but it adds little syntax or interaction detail 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 states a specific verb and resource: fetch aggregated federal obligation amounts grouped by fiscal year, quarter, or month. It distinguishes this time-series tool from sibling tools by emphasizing per-period spending trends and optional award-category breakdowns.
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 clear context for use: tracing spending trends in a specific area, with filters such as award type, agency, recipient, keyword, NAICS, Assistance Listing, PSC, or DEF. It also states the default to contract awards, though it does not explicitly name when to choose this over alternatives like usaspending_spending_by_category or usaspending_spending_by_geography.
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_disaster_spending8 fields changedInput schema / properties / filters / properties / def_codes / descriptionPrevious value: -"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Optional for overview totals and funding; required for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."New value: +"DEF codes, 1–3 letters or digits, sent uppercased. Optional for overview; required for breakdowns. Amount coverage is reported separately: award breakdowns and geography aggregate only the provider COVID grouping; matching rows and counts may include other codes. Overview and agency total cover all requested codes. Find codes in usaspending_get_agency def_codes fields."Input schema / properties / filters / properties / def_codes / items / descriptionAdded value: +"Disaster Emergency Fund Code, e.g. Z or L"Input schema / properties / filters / properties / def_codes / items / patternAdded value: +"^[0-9A-Za-z]{1,3}$"Input schema / properties / limit / descriptionPrevious 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."New value: +"Maximum results per page (1–100). Breakdowns rank obligations descending before pagination; geography ranks aggregated_amount. Agency award without award_type_codes collects all provider pages before ranking, so a smaller limit does not reduce that upstream work. Ignored for overview."Output schema / properties / amount_coverageAdded value: +{
+ "additionalProperties": false,
+ "description": "Scope of all monetary fields, including geography amounts/per-capita and totals; independent of row membership and counts",
+ "properties": {
+ "status": {
+ "description": "Coverage of requested DEF codes by monetary fields, not provider record completeness",
+ "enum": [
+ "complete",
+ "partial",
+ "unavailable",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "supported_def_codes": {
+ "description": "Requested codes included in amounts; omitted when unknown",
+ "items": {
+ "description": "DEF code included in amounts",
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "unsupported_def_codes": {
+ "description": "Requested codes excluded from amounts; omitted when unknown",
+ "items": {
+ "description": "DEF code excluded from amounts",
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status"
+ ],
+ "type": "object"
+}Output schema / properties / totals / properties / obligation / descriptionPrevious value: -"Obligations in USD across the whole matching result set"New value: +"Obligations in USD across the matching result set, within amount_coverage"Output schema / properties / totals / properties / outlay / descriptionPrevious value: -"Outlays in USD across the whole matching result set"New value: +"Outlays in USD across the matching result set, within amount_coverage"Output schema / properties / truncationCeiling / descriptionPrevious value: -"geography: the lowest aggregated_amount on this page — no area on a later page has a higher one."New value: +"geography: the lowest aggregated_amount on this page within amount_coverage — no area on a later page has a higher reported value."usaspending_get_agency2 fields changedInput schema / properties / toptier_code / descriptionPrevious value: -"3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both."New value: +"Directory toptier agency code (e.g., 097, 012, 1601) from usaspending_list_agencies. One/two-digit numeric values are padded to three digits (80 becomes 080); three/four-digit codes are preserved. Use either toptier_code or agency_slug, not both."Output schema / properties / toptier_code / descriptionPrevious value: -"3-digit toptier agency code"New value: +"Directory toptier agency code, which can have three or four digits"usaspending_get_award_federal_accounts1 field changedOutput schema / properties / results / items / properties / funding_toptier_agency_id / descriptionPrevious value: -"Internal USAspending database ID of the funding toptier agency — not the 3-digit toptier code accepted by usaspending_get_agency"New value: +"Internal USAspending database ID of the funding toptier agency — distinct from the directory toptier_code accepted by usaspending_get_agency"usaspending_get_idv_awards1 field changedInput schema / properties / sort / enumAdded value: +[
+ "award_type",
+ "description",
+ "funding_agency",
+ "awarding_agency",
+ "last_date_to_order",
+ "obligated_amount",
+ "period_of_performance_current_end_date",
+ "period_of_performance_start_date",
+ "piid"
+]usaspending_get_recipient1 field changedInput schema / properties / recipient_id / descriptionPrevious value: -"Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award"New value: +"Recipient hexadecimal 8-4-4-4-12 hash with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P — from usaspending_search_recipients or usaspending_get_award"usaspending_list_agencies1 field changedOutput schema / properties / results / items / properties / toptier_code / descriptionPrevious value: -"Three-digit toptier agency code (e.g., 097 for DoD) — required by usaspending_get_agency"New value: +"Directory toptier agency code (e.g., 097 for DoD, 1601 for Labor); three or four digits — accepted by usaspending_get_agency and search_federal_accounts agency_identifier"usaspending_search_awards6 fields changedInput schema / properties / filters / properties / keywords / descriptionPrevious value: -"Full-text search terms across award descriptions, recipient names, and places"New value: +"Full-text search terms across award descriptions, recipient names, and places; effective terms need at least three characters without trimming; nonempty nested values override flat values"Input schema / properties / filters / properties / naics_codes / descriptionPrevious value: -"NAICS industry codes to require, e.g., [\"541512\"]"New value: +"NAICS industry codes to require: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize; unclassified spellings remain provider-validated; nonempty nested values override flat values"Input schema / properties / keyword / descriptionPrevious value: -"Full-text search across award descriptions, recipient names, and place names"New value: +"Full-text search across award descriptions, recipient names, and place names; effective keywords need at least three characters without trimming; empty is unset"Input schema / properties / naics_codes / descriptionPrevious value: -"Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete_filters type=naics to look up codes."New value: +"NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated. Use usaspending_autocomplete_filters type=naics to look up codes."Output schema / properties / error / properties / data / properties / reason / descriptionPrevious value: -"Machine-readable failure mode. Declared by this tool: `incomplete_cursor`: Only one of last_record_sort_value and last_record_unique_id was supplied. `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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `incomplete_cursor`: Only one of last_record_sort_value and last_record_unique_id was supplied. `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: -[
- "incomplete_cursor",
- "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"
-]New value: +[
+ "invalid_keyword",
+ "invalid_naics_code",
+ "incomplete_cursor",
+ "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"
+]usaspending_search_federal_accounts2 fields changedInput schema / properties / agency_identifier / descriptionPrevious value: -"3-digit agency identifier code (e.g., \"097\" for Department of Defense). Use usaspending_list_agencies to look up codes."New value: +"Directory toptier_code from usaspending_list_agencies (e.g., \"097\" for Defense, \"1601\" for Labor). This differs from the account-prefix agency_identifier returned in account rows (e.g., \"016\" for Labor)."Output schema / properties / results / items / properties / agency_identifier / descriptionPrevious value: -"3-digit agency identifier code for this account"New value: +"Account-prefix agency identifier (e.g., 016 for Labor); distinct from the directory toptier_code used by the input filter"usaspending_search_recipients1 field changedOutput schema / properties / results / items / properties / id / descriptionPrevious value: -"Recipient hash ID (UUID format with level suffix: -P parent, -C child, -R standalone) — pass to usaspending_get_recipient for full profile"New value: +"Recipient hexadecimal 8-4-4-4-12 hash with level suffix: -P parent, -C child, -R standalone — pass to usaspending_get_recipient for full profile"usaspending_spending_by_category6 fields changedInput schema / properties / filters / properties / keywords / descriptionPrevious value: -"Full-text keyword filters"New value: +"Full-text keyword filters; each effective term needs at least three characters, including significant whitespace"Input schema / properties / filters / properties / naics_codes / descriptionPrevious value: -"NAICS code filters"New value: +"NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated"Input schema / properties / filters / properties / recipient_id / descriptionPrevious value: -"Exact recipient hash ID filter"New value: +"recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset"Output schema / properties / applied_recipient_idAdded value: +{
+ "description": "Normalized recipient hash and level sent",
+ "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. `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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `invalid_recipient_id`: An active analytics recipient_id is malformed. `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",
- "assistance_listings_type_mismatch",
- "psc_codes_type_mismatch"
-]New value: +[
+ "invalid_keyword",
+ "invalid_naics_code",
+ "invalid_recipient_id",
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest",
+ "assistance_listings_type_mismatch",
+ "psc_codes_type_mismatch"
+]usaspending_spending_by_geography6 fields changedInput schema / properties / filters / properties / keywords / descriptionPrevious value: -"Full-text keyword filter (e.g., [\"cybersecurity\", \"cloud\"])"New value: +"Full-text keyword filters; each effective term needs at least three characters, including significant whitespace"Input schema / properties / filters / properties / naics_codes / descriptionPrevious value: -"NAICS industry codes to include"New value: +"NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated"Input schema / properties / filters / properties / recipient_id / descriptionPrevious value: -"Exact recipient hash ID to filter awards"New value: +"recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset"Output schema / properties / applied_recipient_idAdded value: +{
+ "description": "Normalized recipient hash and level sent",
+ "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. `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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `invalid_recipient_id`: An active analytics recipient_id is malformed. `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",
- "assistance_listings_type_mismatch",
- "psc_codes_type_mismatch"
-]New value: +[
+ "invalid_keyword",
+ "invalid_naics_code",
+ "invalid_recipient_id",
+ "api_unavailable",
+ "api_timeout",
+ "date_range_inverted",
+ "date_before_earliest",
+ "assistance_listings_type_mismatch",
+ "psc_codes_type_mismatch"
+]usaspending_spending_over_time11 fields changedInput schema / properties / filters / properties / keywords / descriptionPrevious value: -"Full-text keyword filters"New value: +"Full-text keyword filters; each effective term needs at least three characters, including significant whitespace"Input schema / properties / filters / properties / naics_codes / descriptionPrevious value: -"NAICS code filters"New value: +"NAICS codes: canonical 2, 4, or 6 digits; recognized ASCII integer aliases normalize whitespace, plus, leading zeros and digit underscores; unclassified spellings remain provider-validated"Input schema / properties / filters / properties / recipient_id / descriptionPrevious value: -"Exact recipient hash ID filter"New value: +"recipient_id from usaspending_search_recipients: hexadecimal 8-4-4-4-12 hash plus uppercase -P, -C, or -R; hash letters normalize to lowercase; empty is unset"Output schema / anyOfPrevious value: -[
- {
- "not": {
- "required": [
- "error"
- ]
- },
- "required": [
- "group",
- "results",
- "total_periods",
- "time_group",
- "period_count"
- ]
- },
- {
- "required": [
- "error"
- ]
- }
-]New value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "group",
+ "results",
+ "total_periods",
+ "applied_award_type_codes",
+ "time_group",
+ "period_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / applied_award_type_codesAdded value: +{
+ "description": "Effective award type codes sent (comma-separated); totals and every breakdown cover only these codes",
+ "type": "string"
+}Output schema / properties / applied_award_type_defaultAdded value: +{
+ "const": "contracts",
+ "description": "Present only when omitted or empty codes select the contract default",
+ "type": "string"
+}Output schema / properties / applied_recipient_idAdded value: +{
+ "description": "Normalized recipient hash and level sent",
+ "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. `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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_keyword`: An effective keyword has fewer than three characters. `invalid_naics_code`: An effective NAICS code is known to be invalid. `invalid_recipient_id`: An active analytics recipient_id is malformed. `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",
- "assistance_listings_type_mismatch",
- "psc_codes_type_mismatch"
-]New value: +[
+ "invalid_keyword",
+ "invalid_naics_code",
+ "invalid_recipient_id",
+ "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 — when no periods are returned — names any Assistance Listing, PSC, or DEF codes sent and suggests broadening filters. Absent when neither applies."New value: +"Discloses effective award-type scope, composes any filled time-window bound, and names active code/recipient filters when no periods are returned."Output schema / properties / results / items / descriptionPrevious value: -"Time period row with total obligations and optional award-type breakdowns"New value: +"Time period row with total obligations and optional award-type breakdowns, all restricted to applied_award_type_codes; an excluded category is not an agency-wide zero"usaspending_autocomplete_filters3 fields changedInput schema / properties / limit / descriptionPrevious value: -"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."New value: +"Maximum number of results to return (1–500), enforced client-side. Agency matches combine independently capped top-tier then sub-tier buckets, preserving their order without deduplicating names; offices are excluded. 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. Every lookup returns at most limit rows."Output schema / properties / results / items / properties / subtier_codeAdded value: +{
+ "description": "awarding_agency only: the matched sub-tier agency code, when supplied",
+ "type": "string"
+}Output schema / properties / results / items / properties / toptier_name / descriptionPrevious value: -"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."New value: +"awarding_agency only: the top-tier parent name. Use the matched name in agency_name on usaspending_search_awards and spending analytics to select the sub-agency; use toptier_name intentionally to select its whole parent department."usaspending_get_award9 fields changedOutput schema / properties / account_outlays_by_defcAdded value: +{
+ "description": "Federal-account outlays by Disaster/Emergency Funding code in upstream order",
+ "items": {
+ "additionalProperties": false,
+ "description": "DEF code entry with code and outlay amount",
+ "properties": {
+ "amount": {
+ "description": "Outlay amount in USD for this DEF code",
+ "type": "number"
+ },
+ "code": {
+ "description": "DEF code identifying the emergency supplemental",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / base_exercised_optionsAdded value: +{
+ "description": "Base and exercised options value in USD when reported for contracts or IDVs",
+ "type": "number"
+}Output schema / properties / place_of_performance / properties / congressional_codeAdded value: +{
+ "description": "Congressional district of performance, preserving leading zeros",
+ "type": "string"
+}Output schema / properties / place_of_performance / properties / county_nameAdded value: +{
+ "description": "County of performance",
+ "type": "string"
+}Output schema / properties / recipient / properties / location / properties / congressional_codeAdded value: +{
+ "description": "Recipient congressional district, preserving leading zeros",
+ "type": "string"
+}Output schema / properties / recipient / properties / location / properties / county_nameAdded value: +{
+ "description": "Recipient county",
+ "type": "string"
+}Output schema / properties / recipient / properties / location / properties / zip5Added value: +{
+ "description": "Recipient ZIP code, preserving leading zeros",
+ "type": "string"
+}Output schema / properties / total_account_obligationAdded value: +{
+ "description": "Total federal-account obligation in USD",
+ "type": "number"
+}Output schema / properties / total_account_outlayAdded value: +{
+ "description": "Total federal-account outlay in USD",
+ "type": "number"
+}usaspending_get_award_subawards3 fields changedOutput schema / properties / results / items / descriptionPrevious value: -"Subaward record with amount, recipient, and location"New value: +"Subaward record with identifier, amount, recipient, date, and description"Output schema / properties / results / items / properties / place_of_performanceRemoved value: -{
- "additionalProperties": false,
- "description": "Subaward place of performance",
- "properties": {
- "city": {
- "description": "City of performance",
- "type": "string"
- },
- "country": {
- "description": "Country code",
- "type": "string"
- },
- "state": {
- "description": "State code",
- "type": "string"
- }
- },
- "type": "object"
-}Output schema / properties / results / items / properties / recipient_ueiRemoved value: -{
- "description": "Sub-recipient Unique Entity Identifier",
- "type": "string"
-}usaspending_get_award_transactions7 fields changedOutput schema / properties / results / items / properties / awarding_agency_nameRemoved value: -{
- "description": "Awarding agency name",
- "type": "string"
-}Output schema / properties / results / items / properties / cfda_numberAdded value: +{
+ "description": "Assistance Listing (CFDA) number for assistance transactions",
+ "type": "string"
+}Output schema / properties / results / items / properties / face_value_loan_guaranteeAdded value: +{
+ "description": "Loan face value in USD; absent for non-loan transactions",
+ "type": "number"
+}Output schema / properties / results / items / properties / id / descriptionPrevious value: -"Transaction internal ID"New value: +"Generated transaction ID (ASST_TX or CONT_TX)"Output schema / properties / results / items / properties / id / typePrevious value: -"number"New value: +"string"Output schema / properties / results / items / properties / original_loan_subsidy_costAdded value: +{
+ "description": "Original loan subsidy cost in USD; absent for non-loan transactions",
+ "type": "number"
+}Output schema / properties / results / items / properties / recipient_nameRemoved value: -{
- "description": "Recipient name at time of transaction",
- "type": "string"
-}usaspending_get_federal_account2 fields changedInput schema / properties / fiscal_yearAdded value: +{
+ "anyOf": [
+ {
+ "description": "Integer federal fiscal year from 2001 through the current federal fiscal year",
+ "maximum": 9007199254740991,
+ "minimum": 2001,
+ "type": "integer"
+ },
+ {
+ "description": "Blank form value; leaves the fiscal year unset",
+ "maxLength": 0,
+ "minLength": 0,
+ "type": "string"
+ }
+ ],
+ "description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
+}Output schema / properties / noticeAdded value: +{
+ "description": "Explains when the selected fiscal year has no financial totals or Treasury Account Symbol components; no alternative year is substituted",
+ "type": "string"
+}usaspending_get_federal_account_breakdown5 fields changedInput schema / properties / fiscal_yearAdded value: +{
+ "anyOf": [
+ {
+ "description": "Integer federal fiscal year from 2001 through the current federal fiscal year",
+ "maximum": 9007199254740991,
+ "minimum": 2001,
+ "type": "integer"
+ },
+ {
+ "description": "Blank form value; leaves the fiscal year unset",
+ "maxLength": 0,
+ "minLength": 0,
+ "type": "string"
+ }
+ ],
+ "description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
+}Output schema / anyOfPrevious value: -[
- {
- "not": {
- "required": [
- "error"
- ]
- },
- "required": [
- "account_code",
- "dimension",
- "results",
- "page_metadata",
- "applied_dimension",
- "current_page",
- "has_next_page"
- ]
- },
- {
- "required": [
- "error"
- ]
- }
-]New value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "period",
+ "account_code",
+ "dimension",
+ "results",
+ "page_metadata",
+ "applied_dimension",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / fiscal_yearAdded value: +{
+ "description": "Fiscal year selected by the caller; omitted for all available periods",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / periodAdded value: +{
+ "description": "FY<year> for a selected year, otherwise all available periods",
+ "type": "string"
+}Output schema / properties / time_periodAdded value: +{
+ "additionalProperties": false,
+ "description": "Full fiscal-year range applied to financial reporting periods, not award action dates; omitted for all available periods",
+ "properties": {
+ "end_date": {
+ "description": "Inclusive financial reporting period end date (YYYY-MM-DD)",
+ "type": "string"
+ },
+ "start_date": {
+ "description": "Inclusive financial reporting period start date (YYYY-MM-DD)",
+ "type": "string"
+ }
+ },
+ "required": [
+ "start_date",
+ "end_date"
+ ],
+ "type": "object"
+}usaspending_list_agencies11 fields changedInput schema / properties / limitAdded value: +{
+ "description": "Agencies per page; omitted returns the full directory. No maximum.",
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / pageAdded value: +{
+ "description": "Page number when limit is supplied (defaults to page 1); ignored without limit.",
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / anyOfPrevious value: -[
- {
- "not": {
- "required": [
- "error"
- ]
- },
- "required": [
- "results",
- "total",
- "agency_count"
- ]
- },
- {
- "required": [
- "error"
- ]
- }
-]New value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "total",
+ "agency_count",
+ "totalCount"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / has_nextAdded value: +{
+ "description": "Whether another page exists; present only when limit is supplied",
+ "type": "boolean"
+}Output schema / properties / results / items / properties / budget_authority_amount / descriptionPrevious value: -"Total budget authority amount in USD for the current fiscal year"New value: +"Total budget authority amount in USD for the latest reported period"Output schema / properties / results / items / properties / fiscal_quarterAdded value: +{
+ "description": "Provider reporting fiscal quarter for the latest reported period",
+ "type": "number"
+}Output schema / properties / results / items / properties / fiscal_yearAdded value: +{
+ "description": "Provider reporting fiscal year for the latest reported period",
+ "type": "number"
+}Output schema / properties / results / items / properties / obligated_amount / descriptionPrevious value: -"Total obligated amount in USD for the current fiscal year"New value: +"Total obligated amount in USD for the latest reported period"Output schema / properties / results / items / properties / outlay_amount / descriptionPrevious value: -"Total outlay amount in USD for the current fiscal year"New value: +"Total outlay amount in USD for the latest reported period"Output schema / properties / total / descriptionPrevious value: -"Total number of agencies returned"New value: +"Total number of agencies in the full directory before pagination"Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of agencies in the full directory before pagination",
+ "type": "number"
+}usaspending_search_awards2 fields changedInput schema / properties / agency_name / descriptionPrevious 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."New value: +"Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents."Input schema / properties / filters / properties / agency_name / descriptionPrevious 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"New value: +"Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents."usaspending_search_federal_accounts2 fields changedInput schema / properties / fiscal_yearAdded value: +{
+ "anyOf": [
+ {
+ "description": "Integer federal fiscal year from 2001 through the current federal fiscal year",
+ "maximum": 9007199254740991,
+ "minimum": 2001,
+ "type": "integer"
+ },
+ {
+ "description": "Blank form value; leaves the fiscal year unset",
+ "maxLength": 0,
+ "minLength": 0,
+ "type": "string"
+ }
+ ],
+ "description": "Federal fiscal year (2001 through the current federal fiscal year; October 1 rollover). Omit or leave blank to preserve the endpoint default."
+}Output schema / properties / fiscal_yearAdded value: +{
+ "description": "Effective fiscal year of the budgetary resources, as reported by USAspending; account membership spans all submitted years",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}usaspending_spending_by_category1 field changedInput schema / properties / filters / properties / agency_name / descriptionPrevious 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"New value: +"Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents."usaspending_spending_by_geography1 field changedInput schema / properties / filters / properties / agency_name / descriptionPrevious 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"New value: +"Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents."usaspending_spending_over_time1 field changedInput schema / properties / filters / properties / agency_name / descriptionPrevious 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"New value: +"Awarding top-tier or sub-tier agency name — use the matched name from usaspending_autocomplete_filters type=awarding_agency; use toptier_name to select the whole parent department. A sub-tier name shared by several parents matches under all parents."usaspending_disaster_spending7 fields changedInput schema / properties / filters / properties / def_codes / descriptionPrevious value: -"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Required for all dimensions except overview — the upstream API returns HTTP 422 when omitted for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."New value: +"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Optional for overview totals and funding; required for agency, cfda, recipient, and geography breakdowns. DEF codes appear in usaspending_get_agency def_codes fields."Input schema / properties / filters / properties / queryAdded value: +{
+ "description": "Recipient search text, trimmed before sending. Omitted or blank means no query filter. Ignored with a notice on other dimensions.",
+ "type": "string"
+}Output schema / properties / applied_def_codesAdded value: +{
+ "description": "DEF codes applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_queryAdded value: +{
+ "description": "Trimmed recipient query sent upstream",
+ "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. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `missing_def_codes`: A non-overview dimension has no DEF codes. `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: -[
- "api_unavailable",
- "api_timeout"
-]New value: +[
+ "missing_def_codes",
+ "api_unavailable",
+ "api_timeout"
+]Output schema / properties / notice / descriptionPrevious 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."New value: +"Upstream messages, ignored filters, empty-page recovery, and guidance for recipient ceilings or remaining geography areas."usaspending_get_award_federal_accounts1 field changedOutput schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — the award_id may not exist or may have no account linkage. Absent when results are present."New value: +"Recovery for an empty page, distinguished from a known zero total; absent when results are present."usaspending_get_federal_account_breakdown1 field changedOutput schema / properties / notice / descriptionPrevious value: -"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."New value: +"Recovery for an empty page, distinguished from a known zero total; absent when results are present."usaspending_search_awards3 fields changedOutput 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. `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."New value: +"Machine-readable failure mode. Declared by this tool: `incomplete_cursor`: Only one of last_record_sort_value and last_record_unique_id was supplied. `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",
- "psc_codes_type_mismatch",
- "invalid_location"
-]New value: +[
+ "incomplete_cursor",
+ "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 / notice / descriptionPrevious 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."New value: +"How to page on when more results may remain, which date bound was filled in when only the other was supplied, and the applied filters on an empty page. This endpoint supplies no total, so an empty page does not establish zero matches. Absent when none applies."usaspending_search_recipients2 fields changedInput schema / properties / keyword / descriptionPrevious value: -"Name, UEI, DUNS, or keyword to search for — partial matches are supported"New value: +"Name, UEI, DUNS, or keyword to search for — partial matches are supported. Surrounding whitespace is trimmed; blank text applies no keyword filter and is disclosed."Output schema / properties / notice / descriptionPrevious 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."New value: +"Blank-keyword disclosure and pagination recovery. An empty page is distinguished from a known zero total; absent when no notice applies."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"Query USASpending.gov federal contract awards, grants, and government contractor recipients.
USAspending.gov contracts, grants, loans, subawards, recipients, agencies, and federal accounts.
USAspending MCP — Federal spending data from USAspending.gov API
See who wins US federal contracts and grants (USAspending.gov). $0.02/call via x402.
Add one secure layer between your agents and this server.