Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.
Look up valid code values for filter fields by searching free-text descriptions. Use the type parameter to select the lookup table: naics (NAICS industry codes), psc (product/service codes), cfda (CFDA/Assistance Listing program numbers), awarding_agency (agency names and IDs), or recipient (recipient names with UEI/DUNS). Call this before filtering awards when you know a description but not the exact code. Returns matching codes and names for use in other tool filters.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Lookup table to search: naics (industry codes), psc (product/service codes), cfda (assistance programs), awarding_agency (agency names), recipient (recipient names) | |
| limit | No | Maximum number of results to return (1–500), enforced client-side. The recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x this value, so its results are capped to this limit before returning — the cap keeps them in bucket order, so name matches fill the page first and identifier matches appear only in whatever room is left. To resolve a specific UEI or DUNS, pass the identifier itself as search_text. naics/psc/cfda/awarding_agency honor this limit exactly. | |
| search_text | Yes | Free-text search string — use a description, keyword, or partial code to find matches |
| Name | Required | Description |
|---|---|---|
| cap | No | The limit that was applied. |
| 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. |
| total | No | Number of results returned |
| results | No | Matching codes and names |
| truncated | No | True when results were capped at the limit. |
| 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 readOnlyHint, idempotentHint, and openWorldHint, so the description does not need to restate these. The description adds that it 'Returns matching codes and names for use in other tool filters,' which is helpful but not deeply behavioral. It does not disclose rate limits, edge cases, or output shape (though output schema exists). The description remains consistent with annotations, adding only mild extra context.
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 composed of four sentences that front-load the main action and then detail the type options and use case. While listing all five enum values is somewhat verbose, it is directly useful and not redundant. Every sentence contributes meaning, and the structure is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the tool's purpose, when to call it, and the meaning of parameters. It omits explicit discussion of the `limit` parameter's quirks (like the recipient 3x behavior), but those are documented in the schema, so the description is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by elaborating on the `type` parameter, clarifying what each enum value means (e.g., 'naics (NAICS industry codes)'), which goes beyond the schema's short descriptions. It also frames the `search_text` as a free-text description search. This compensation for schema brevity justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Look up valid code values for filter fields') and identifies the resource (code values across multiple domains). It explicitly distinguishes itself from sibling tools by positioning as a pre-filter lookup helper, and the list of type options adds specificity.
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 provides a clear when-to-use instruction: 'Call this before filtering awards when you know a description but not the exact code.' This implicitly tells the agent not to use it when the code is already known, but it does not explicitly name alternative tools or state why other tools should not be used, so it falls short of a fully explicit usage guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.) broken down by agency, CFDA assistance program, recipient, or geography. Use the dimension parameter to select the breakdown axis: overview (top-level totals), agency, cfda, recipient, or geography. Filter by DEF codes (Disaster/Emergency Funding codes) to isolate a specific emergency appropriation. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated. | |
| 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 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. | award |
| Name | Required | Description |
|---|---|---|
| cap | No | The result-set ceiling the upstream applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results returned on this page. |
| notice | No | Caveat explaining a capped total and how to bring the set under the cap. |
| results | No | Breakdown results (empty for overview dimension) |
| overview | No | Top-level overview totals (dimension=overview only) |
| dimension | No | Breakdown dimension returned |
| truncated | No | True when the upstream capped the reachable result set rather than counting it. |
| totalCount | No | Total items for paginated dimensions (when available) |
| current_page | No | Current page (non-overview dimensions) |
| has_next_page | No | Whether there are more pages |
| page_metadata | No | Pagination metadata (non-overview dimensions) |
| spending_type | No | Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview |
| applied_dimension | No | Breakdown dimension applied |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds minimal behavioral context—mentioning DEF codes and pointing to other tools for those codes—but does not describe return formats, pagination nuances, or any side effects beyond what annotations and schema already imply. Since annotations carry the burden, a 3 is appropriate.
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 with no redundancy. The primary purpose is front-loaded, dimension options are listed compactly, and DEF code rationale is explained efficiently. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete given the rich schema (100% coverage) and the presence of an output schema. It covers the main decision points (dimension, DEF codes) and provides cross-references. The schema handles all parameter details, so nothing critical is missing for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the semantic purpose of the dimension parameter and DEF codes, including examples of actual codes and how to use them. This goes slightly beyond the schema's per-parameter descriptions, elevating the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches disaster/emergency supplemental spending and lists the breakdown axes (overview, agency, cfda, recipient, geography). It provides concrete examples (COVID-19, hurricanes, infrastructure law) and names the specific domain, distinguishing it from other spending-related tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for disaster/emergency spending scenarios and explains how to select dimensions and filter by DEF codes. However, it does not explicitly contrast with sibling tools (e.g., when to use this vs. usaspending_spending_by_category) or state exclusions, so some inference is required.
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), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdown with obligation and transaction counts. Accepts either a 3-digit toptier_code (e.g., 097 for DoD, 012 for Agriculture) or an agency_slug (e.g., department-of-defense) — both appear in usaspending_list_agencies results and award search results.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list. | |
| agency_slug | No | URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both. | |
| toptier_code | No | 3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both. |
| Name | Required | Description |
|---|---|---|
| name | No | Agency full name |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown. |
| 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 (most recent available) |
| abbreviation | No | Agency abbreviation |
| sub_agencies | No | Sub-agency breakdown within this toptier agency (one page) |
| toptier_code | No | 3-digit toptier agency code |
| outlay_amount | No | Total outlays in USD for the fiscal year |
| sub_agency_page | No | Current sub-agency page returned |
| 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 |
| has_more_sub_agencies | No | Whether more sub-agency pages are available |
| 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?
Annotations already convey readOnlyHint=true and idempotentHint=true, so the agent knows this is safe. The description adds behavioral context by specifying that it returns a paginated breakdown, includes DEF codes for disaster/emergency funding, and provides example codes/slugs. It does not contradict annotations and adds helpful detail about the data scope without over-explaining.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences but packs substantial detail: the first sentence lists the core data returned, the second explains the identifier options and sources. It is front-loaded with the main purpose and uses examples efficiently. It is appropriately sized for a moderately complex tool, though it could be slightly trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, return values are already specified, so the description need not restate them. It covers how to obtain the identifiers (from usaspending_list_agencies or award results), the mutual exclusivity rule, and the pagination behavior via sub_agency_page_metadata. The description is sufficient for an agent to call this tool correctly without additional introspection.
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% (every parameter has a description), but the tool description adds crucial semantics beyond the schema: it explains that toptier_code and agency_slug are mutually exclusive alternatives and provides concrete examples (097, 012; department-of-defense). It also clarifies that the page parameter is for sub-agency pagination. This extra guidance helps the agent select and format parameters correctly.
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 ('Fetch') and a precise resource ('an agency's fiscal-year overview') and enumerates the returned data (mission, budgetary resources, obligation/outlay totals, DEF codes, sub-agency breakdown). It clearly differentiates itself from sibling tools like usaspending_list_agencies, which lists agencies, while this fetches details for one agency.
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 states that it accepts either toptier_code or agency_slug and explicitly says 'both appear in usaspending_list_agencies results and award search results,' guiding the agent on where to obtain inputs. It also instructs 'Use either toptier_code or agency_slug, not both,' which is a clear constraint. However, it does not explicitly describe scenarios where a sibling tool (e.g., usaspending_get_federal_account) would be more appropriate, but the purpose is clear enough that this is minimal.
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 info, agency hierarchy, period of performance, place of performance, funding account linkages (account_obligations_by_defc), parent IDV information, and subaward count. Use generated_internal_id values from usaspending_search_awards as input. Recipient hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters. For IDV-category awards (category="idv"), use usaspending_get_idv_awards to list the child contracts and task/delivery orders placed under them.
| 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 |
|---|---|---|
| cfda | No | CFDA program (grants/assistance) |
| 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, grant, direct_payment, loan, idv, 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_obligation | No | Total obligation amount in USD |
| type_description | No | Human-readable award type |
| place_of_performance | No | Place of performance |
| period_of_performance | No | Period of performance dates |
| product_or_service_code | No | Product or service code (contracts) |
| generated_unique_award_id | No | Generated unique award ID |
| base_and_all_options_value | No | Base and all options value in USD (contracts) |
| account_obligations_by_defc | No | Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat that. It adds value by specifying the types of data returned (account_obligations_by_defc, parent IDV info, subaward count) and the special handling for IDV awards. It omits rate limits or auth, but for a read-only operation these are less critical.
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 well-structured: first sentence states the core purpose, then the return payload, input source, and routing to related tools. Each sentence contributes new information, and the most critical instruction (input source) is prominent. 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?
For a single-parameter, read-only tool with an output schema, the description covers everything an agent needs: what it does, what input to pass, what data it returns, and when to use a different tool. The output schema handles return structure, so no further detail is required.
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?
The schema already documents the award_id parameter with 100% coverage, including an example and the note to use generated_internal_id. The description reiterates the same guidance without adding new semantic details. Baseline 3 is appropriate because the schema handles parameter semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and resource 'award details', and lists specific data returned (recipient info, agency hierarchy, etc.). It differentiates from siblings by explicitly directing IDV awards to usaspending_get_idv_awards, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to use generated_internal_id from usaspending_search_awards, and says when NOT to use this tool (for IDV awards, use usaspending_get_idv_awards). It also mentions related tools for recipient and NAICS data, providing clear routing and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it. This is the award → appropriation link: each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) to chain into usaspending_get_federal_account for the account budget detail. The award_id must be a generated_unique_award_id — from usaspending_search_awards (generated_internal_id field) or usaspending_get_award. Distinct from usaspending_get_award account_obligations_by_defc, which breaks funding down by Disaster/Emergency Funding code rather than by account. An award_id that does not exist returns an empty list rather than an error.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100) | |
| award_id | Yes | Award generated_unique_award_id (e.g., CONT_AWD_GSFC0198106DNAS526555_8000_-NONE-_-NONE-) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — the award_id may not exist or may have no account linkage. Absent when results are present. |
| results | No | Federal accounts funding this award |
| award_id | No | Award ID queried |
| totalCount | No | Total number of funding accounts across all pages (when available) |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of funding accounts |
| page_metadata | No | Pagination metadata |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses a specific edge case: 'An award_id that does not exist returns an empty list rather than an error.' It also details the output format (federal_account in AGENCY-MAIN format), which is behavior not captured by annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet dense with information. Each sentence serves a purpose: purpose, output format, ID requirement, differentiation from sibling, and edge-case behavior. There is no filler, and key details are front-loaded (the core function appears first).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema and annotations, the description covers all essential aspects: what it returns, how to source the parameter, how it differs from a sibling, and error behavior. It also explains the chaining use case. Nothing critical is missing for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for award_id by specifying it must be a generated_unique_award_id and providing sources (generated_internal_id from search or generated_unique_award_id from get_award). This goes beyond the schema's example, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource pair: 'List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it.' It further distinguishes itself from the sibling usaspending_get_award's account_obligations_by_defc by noting the different breakdown (by account vs. by DEFC), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use and when-not guidance is provided: the description names an alternative (usaspending_get_award account_obligations_by_defc) and explains the key difference. It also instructs on how to obtain the required award_id (from usaspending_search_awards or usaspending_get_award) and suggests chaining the output to usaspending_get_federal_account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subaward contracts or grants under a prime federal award. Reveals the sub-contractor or sub-grantee layer — the organizations that actually perform the work. Each row shows the subaward number, amount, description, action date, and recipient. Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| sort | No | Sort field for subawards | action_date |
| limit | No | Maximum subawards per page (1–100) | |
| order | No | Sort direction | desc |
| award_id | Yes | Generated unique award ID (generated_internal_id from usaspending_search_awards) |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present. |
| results | No | List of subawards under this prime award |
| award_id | No | Prime award ID queried |
| totalCount | No | Total subaward count across all pages (when available) |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of subawards |
| page_metadata | No | Pagination metadata |
| prime_award_id | No | Prime award ID whose subawards were listed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. The description adds meaningful behavioral context: it clarifies that the tool returns a list of subawards, reveals the sub-contractor layer, and highlights the need to check subaward_count first. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The first sentence front-loads the core purpose and output contents; the second adds a practical usage note. Structure is clean and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, an output schema, and strong annotations, the description covers purpose, usage precondition, and expected row fields. It does not explicitly mention pagination, but the schema's page/limit parameters handle that. The check-subaward_count hint adds operational completeness. Adequate for an idempotent read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters already have clear descriptions. The description adds only marginal parameter-related value: it implies award_id refers to a 'prime federal award' and mentions row fields that map to sort options, but does not enhance understanding beyond the schema's parameter documentation. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and a specific resource ('subaward contracts or grants under a prime federal award'). It goes further to explain the purpose ('Reveals the sub-contractor or sub-grantee layer') and enumerates the fields returned per row. This distinguishes it from sibling tools like usaspending_get_award (prime award details) and usaspending_get_award_transactions (transaction layer).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage precondition: 'Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.' This names the exact sibling tool to use and the condition that gates this tool. It does not compare with other award tools like transactions, but the purpose clause already narrows the use case sufficiently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List individual transactions (contract modifications, grant amendments) on a federal award. Each transaction represents a change event — obligation modifications, performance period extensions, scope changes, etc. Use this to trace the spending history and obligation changes over the life of an award. Award IDs come from usaspending_search_awards (generated_internal_id field).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| sort | No | Sort field for transactions | action_date |
| limit | No | Maximum transactions per page (1–100) | |
| order | No | Sort direction | desc |
| award_id | Yes | Generated unique award ID (generated_internal_id from usaspending_search_awards) |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present. |
| results | No | List of transactions for this award |
| award_id | No | Award ID queried |
| totalCount | No | Total transaction count across all pages (when available) |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of transactions |
| page_metadata | No | Pagination metadata |
| queried_award_id | No | Award ID whose transactions were listed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating operation. The description adds value by explaining what a transaction represents and why it's useful for tracing award history, which is behavior beyond mere read-only status. It does not contradict the annotations and provides semantic context without repeating the hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Only three sentences, with the core purpose stated in the first sentence. Every sentence contributes: the first defines the operation, the second explains what a transaction is, the third gives the use case and ID source. No word wasted, and the most critical information (what and why) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a straightforward list operation, the description is complete. The output schema is present (context signal) so return structure is handled elsewhere. The description covers the conceptual model (what a transaction is), the use case, and the provenance of the required ID. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — all five parameters have descriptions in the schema, including the source of award_id. The description reinforces the award_id source but does not add meaningful new information beyond what the schema already provides. With full schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('transactions on a federal award'), and the nature of those transactions ('change events — obligation modifications, performance period extensions, scope changes'). This distinguishes it from sibling tools like get_award or get_award_subawards, which target different award-related data. The mention of tracing spending history further clarifies the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case ('trace the spending history and obligation changes over the life of an award') and specifies the source of the required parameter ('Award IDs come from usaspending_search_awards'). It does not explicitly state when NOT to use this tool or mention alternatives, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a federal account's budget data: total obligations, gross outlays, and budgetary resources, plus the per-Treasury-Account-Symbol (TAS) component breakdown in children. Federal accounts connect appropriations law to actual agency spending. Account codes come from usaspending_search_federal_accounts (its account_number output field) or usaspending_get_award_federal_accounts (its federal_account field), and are formatted as AGENCY-MAIN (e.g., 097-0100 for DoD Operation and Maintenance). For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| account_code | Yes | Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| children | No | Treasury Account Symbol (TAS) components that make up this federal account, each with its own obligated, outlay, and budgetary-resource amounts. Omitted when the upstream returns none. |
| bureau_name | No | Bureau name within the agency |
| fiscal_year | No | Fiscal year of the financial data |
| account_title | No | Full account title |
| agency_identifier | No | Agency identifier code |
| main_account_code | No | Main account code |
| parent_agency_name | No | Managing parent agency name |
| federal_account_code | No | Federal account code |
| total_obligated_amount | No | Total obligated amount in USD |
| total_budgetary_resources | No | Total budgetary resources in USD |
| total_gross_outlay_amount | No | Total gross outlay amount in USD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds behavioral context by detailing the returned data structure (total obligations, gross outlays, budgetary resources, and per-TAS breakdown in children). It does not contradict annotations and enriches the agent's understanding of what the tool returns beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficient. It leads with the core purpose, adds a brief domain context sentence, then provides input sourcing/format, and ends with a clear routing to an alternative. No fluff, every sentence earns its place, and it's well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (has output schema: true) and a single well-documented parameter, the description is complete. It explains the input format, how to obtain it, what data comes back, the domain significance, and the alternative for more granular breakdowns. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter account_code, so the baseline is 3. The description adds extra value by explicitly stating the format (AGENCY-MAIN, e.g., 097-0100) and pointing to the source tools that return this value, which is beyond the schema's description. This helps the agent form the correct input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action – 'Fetch a federal account's budget data' – and enumerates the exact data types: total obligations, gross outlays, budgetary resources, and per-TAS breakdown in children. It also distinguishes itself from the sibling tool usaspending_get_federal_account_breakdown by noting the alternative for obligations by program activity/object class. This clearly separates it from other federal-account tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent where to obtain account codes: from usaspending_search_federal_accounts (via account_number) or usaspending_get_award_federal_accounts (via federal_account). It also provides an alternative condition: 'For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.' This is clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. Account codes are AGENCY-MAIN format and come from usaspending_search_federal_accounts (its account_number output field), usaspending_get_award_federal_accounts (its federal_account field), or usaspending_get_federal_account. Paginated with an honest total count. For the account's own metadata and top-level totals, use usaspending_get_federal_account.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100) | |
| dimension | Yes | Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased) | |
| account_code | Yes | Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — the account code may not exist or may have no obligations on this axis. Absent when results are present. |
| results | No | Breakdown rows for the requested dimension |
| dimension | No | Breakdown dimension returned |
| totalCount | No | Total number of breakdown rows across all pages (when available) |
| account_code | No | Federal account code queried |
| current_page | No | Current page returned |
| has_next_page | No | Whether there are more pages of breakdown rows |
| page_metadata | No | Pagination metadata |
| applied_dimension | No | Breakdown dimension applied |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: pagination with an 'honest total count' and the axis options. This exceeds the minimal bar set by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences of dense, front-loaded content. The purpose comes first, alternatives are embedded, and no filler exists. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a complete schema (100% coverage), an output schema for return shape, and annotations covering safety, the description covers the remaining context: pagination behavior, total count, and routing to the correct sibling tool. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the distinction between the two dimension values and mentions the account_code format and source tools, but this information is largely duplicated in the schema's property descriptions. No new semantic detail is added beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Fetch a federal account's obligations') and immediately defines the two breakdown axes, distinguishing this from siblings. It also names the alternative tool for metadata/totals, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (for breakdown by dimension) and when not to ('For the account's own metadata and top-level totals, use usaspending_get_federal_account'). It also tells the agent exactly where to obtain account codes from three sibling tools, leaving no ambiguity about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List child contracts and task/delivery orders placed under an IDV (Indefinite Delivery Vehicle) award. Each row includes the generated_unique_award_id to chain into usaspending_get_award for full detail. The award_id must be the generated_unique_award_id of the parent IDV — obtainable from usaspending_search_awards (generated_internal_id field) or from usaspending_get_award. IDV category awards returned by usaspending_get_award have child orders accessible via this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| sort | No | Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date) | obligated_amount |
| type | No | Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVs | child_awards |
| limit | No | Maximum results per page (1–100) | |
| order | No | Sort direction | desc |
| award_id | Yes | Parent IDV generated_unique_award_id (e.g., CONT_IDV_NNK14MA74C_8000) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award |
| Name | Required | Description |
|---|---|---|
| cap | No | The per-page limit that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of child awards returned on this page. |
| notice | No | Recovery hint when results are empty — the award may have no children of the requested type. Absent when results are present. |
| results | No | Child awards placed under this IDV |
| award_id | No | Parent IDV award ID queried |
| truncated | No | True when this page was full and more child awards may remain beyond it. |
| current_page | No | Current page returned |
| has_next_page | No | Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none. |
| page_metadata | No | Pagination metadata (no total count available from this endpoint) |
| parent_award_id | No | Parent IDV award ID whose children were listed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the behavioral context that each row includes the generated_unique_award_id for chaining, and that the award_id must be an IDV-generated unique ID. This goes beyond the annotations by explaining the output linkage and the input constraint, which is valuable for the agent's understanding of how results can be used.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the core purpose, and the second provides essential input requirements and chaining information. It is front-loaded with the most critical information and structured logically, earning its place without any redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 6 parameters and the presence of an output schema, the description covers the essential operational context: what it returns (rows with generated_unique_award_id), how to obtain the required parent ID, and the relationship to other tools. It does not need to explain the output schema since that exists separately. The only slight gap is that it doesn't explicitly state behavior for non-IDV inputs, but it implies the tool is for IDV awards. Overall, it is complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant extra meaning for the award_id parameter by specifying it must be the generated_unique_award_id and providing the exact source fields (generated_internal_id from usaspending_search_awards, or generated_unique_award_id from usaspending_get_award). It also clarifies the enum values for type (child_awards, child_idvs, grandchild_awards). This adds value beyond the schema 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 clearly states the verb (List), resource (child contracts and task/delivery orders under an IDV award), and the distinguishing feature that each row includes the generated_unique_award_id to chain into usaspending_get_award. It explicitly differentiates from sibling tools like usaspending_get_award (which provides detail on a single award) and usaspending_search_awards (which searches), so an agent can select this tool unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it tells the agent that the award_id must be the generated_unique_award_id of the parent IDV and explains how to obtain it (from usaspending_search_awards generated_internal_id or usaspending_get_award). It also clarifies that IDV category awards from usaspending_get_award have child orders accessible here, effectively telling the agent to use this tool when they have a parent IDV and need child awards. No exclusions are needed because the scope is clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are UUID hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Optionally scope the totals to a specific fiscal year and award type. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.
| Name | Required | Description | Default |
|---|---|---|---|
| award_type | No | Award type category to scope award totals | |
| fiscal_year | No | Fiscal year to scope award totals (e.g., 2024) | |
| recipient_id | Yes | Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award |
| Name | Required | Description |
|---|---|---|
| uei | No | Unique Entity Identifier (SAM.gov) |
| duns | No | DUNS number (legacy) |
| name | No | Recipient legal business name |
| error | No | Present when the call failed. Absent on success. |
| 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 |
| total_transaction_amount | No | Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided |
| total_face_value_loan_amount | No | Total face value of loans in USD |
| total_face_value_loan_transactions | No | Number of face-value loan transactions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral detail about the returned profile contents, the ID format (UUID with level suffix), and optional scoping of totals by fiscal year and award type. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose and specific contents. The ID origin and optional filters are introduced efficiently without repetition or fluff. Every sentence adds essential context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (so return values are structured), the description covers prerequisites (ID source), optional filters, and cross-referencing tips. An agent has everything needed to decide when and how to call this tool, and the read-only/idempotent annotations cover safety. No meaningful gaps.
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% with descriptions for all parameters. The description adds value by explaining the recipient_id format and provenance (from which tools), and clarifies that award_type and fiscal_year scope award totals. This goes beyond the schema's basic attribute descriptions, aiding correct parameter use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a recipient's full profile' and lists specific contents (address, business type codes, parent org, alternate names, totals). This distinguishes it from siblings like usaspending_search_recipients (search) and usaspending_get_award (award details), so an agent can immediately identify the tool's role.
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 implies when to use it: after obtaining a recipient_id from usaspending_search_recipients or usaspending_get_award. It provides context for ID prerequisites but does not explicitly state exclusions (e.g., 'use search_recipients to find recipients'). The guidance is clear but slightly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the current fiscal year. Use this as the entry point for agency navigation — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based filters on spending analysis tools.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount | agency_name |
| order | No | Sort direction: asc or desc | asc |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| total | No | Total number of agencies returned |
| results | No | List of top-tier federal agencies with budget and obligation data |
| agency_count | No | Total number of top-tier federal agencies returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context: it returns data for the current fiscal year only, lists the specific data elements, and frames the tool as the initial navigation step. This goes beyond merely restating the read-only nature, though it does not mention pagination or limits—minor given the output schema likely describes the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the core purpose and output content; the second provides critical usage context by naming downstream tools. Every sentence earns its keep.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional sort parameters and an output schema, the description is complete. It tells the agent exactly what will be returned, scopes the data to the current fiscal year, and explains how it fits into the broader toolchain. Required parameters are none, so no input gaps exist. The output schema covers return structure, so the description doesn't need to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'sort' and 'order' parameters have clear enum values, defaults, and descriptions in the schema. The tool description does not add any extra parameter semantics beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a precise resource ('all top-tier federal agencies'), and the exact fields returned (toptier codes, agency slugs, budget authority, obligation totals). It also explicitly distinguishes itself from usaspending_get_agency by positioning itself as the entry point for agency navigation, so an agent can clearly tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool as the entry point for agency navigation and notes that the toptier codes and agency slugs it returns are required inputs for usaspending_get_agency and agency-based filters. This gives clear when-to-use guidance and implies when not to use it (i.e., when you already have an agency identifier and need details).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search federal awards by keyword, recipient, agency, award type, NAICS code, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usaspending_get_award. Award types: A/B/C/D = contracts, 02/03/04/05 = grants, 06/10 = direct payments, 07/08 = loans, IDV_A/IDV_B/IDV_C/IDV_D/IDV_E = IDVs. 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 | Award Amount |
| 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 intentionally not accepted — this endpoint silently ignores it; filter by recipient via recipient_name. | |
| keyword | No | Full-text search across award descriptions, recipient names, and place names | |
| agency_name | No | Filter to a specific awarding agency by name (e.g., "Department of Defense"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names. | |
| naics_codes | No | Filter by NAICS industry codes (e.g., ["541512"]). Use usaspending_autocomplete_filters type=naics to look up codes. | |
| time_period | No | Filter awards by date range (action date) | |
| 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 location. Uses FIPS codes and 2-letter state abbreviations, not place names — use a geocoding server to resolve names to codes first. | |
| award_type_codes | No | 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. | |
| 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. |
| 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. |
| notice | No | Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present. |
| 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 this page was capped at `limit` and more results may remain (continue via page or the cursor). |
| 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 |
| 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 date filter applied (YYYY-MM-DD) |
| applied_time_period_start | No | Start date filter applied (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description adds valuable context beyond that: the 90-day publication lag for DoD contracts, the earliest data date (2007-10-01), and implicit pagination caveats (via the schema). These are non-obvious behaviors that could affect results and the description explicitly flags them. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact four-sentence paragraph that front-loads the core purpose and then adds essential caveats. It is efficiently structured and avoids fluff, though some details (award type codes, date format) are also in the schema, which is slightly redundant. Overall, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, nested objects, output schema present), the description covers the essential points: what it returns (ranked summaries with recipient names, amounts, agencies, award IDs), when to use it versus siblings, and key data limitations. Pagination details and per-parameter constraints are in the schema, so the description need not repeat them. It is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter has detailed descriptions in the schema (e.g., pagination warnings, mapping of award types, constraint of recipient_id being ignored). The description's top-level text repeats the award type mapping and date format, but these are also present in the schema. The description adds limited unique parameter insight, so it meets the baseline but does not exceed it.
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 precise verb and resource: 'Search federal awards' by specific criteria (keyword, recipient, agency, award type, NAICS, location, date range). It also differentiates itself by noting it returns 'generated award IDs for use with usaspending_get_award', which clearly separates the search purpose from the retrieval purpose. The listed filter types and the award-type mapping give a complete picture of the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use related tools: it tells the agent to use usaspending_autocomplete_filters for agency and NAICS lookups, and usaspending_search_recipients for recipient lookup. It also implies a workflow (search for awards, then get_award for details). It does not explicitly state when *not* to use this tool, but the alternative usage is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. Use account_number from results as input to usaspending_get_federal_account for full budget detail. Use usaspending_list_agencies to look up agency_identifier codes (3-digit strings, e.g. "097" for DoD).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) | |
| limit | No | Maximum results per page (1–100) | |
| keyword | No | Filter accounts by name or title keyword (e.g., "defense", "transportation") | |
| sort_field | No | Field to sort results by | budgetary_resources |
| sort_direction | No | Sort direction | desc |
| agency_identifier | No | 3-digit agency identifier code (e.g., "097" for Department of Defense). Use usaspending_list_agencies to look up codes. |
| Name | Required | Description |
|---|---|---|
| page | No | Current page number returned |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present. |
| results | No | Matching federal accounts |
| has_next | No | Whether there are more pages of results |
| totalCount | No | Total number of matching accounts across all pages (when available) |
| page_metadata | No | Pagination metadata |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description doesn't need to restate those. It adds behavioral value by specifying the returned fields (account numbers, names, managing agencies, budgetary resources) and the intended chaining to get_federal_account. This gives the agent insight into the result shape and how to proceed, which is helpful beyond mere annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The primary purpose is front-loaded, followed by two directed usage notes for related tools. Every sentence earns its place, and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema and 6 optional parameters, the description covers the essential workflow: searching, retrieving results, and chaining to related tools. It doesn't explicitly address pagination or sorting, but the schema and defaults handle that. For a search tool, this description is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description reinforces the agency_identifier parameter by referencing usaspending_list_agencies for code lookup, which adds a hint about valid values. However, it does not add syntax or format details beyond what the schema provides, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists and keyword-searches federal accounts by agency identifier or title keyword, which is a specific verb+resource. It also distinguishes itself from the closely related usaspending_get_federal_account (which retrieves full details for a specific account) and usaspending_list_agencies (which returns agency identifiers). The purpose is unambiguous and separates it from other search tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to use usaspending_get_federal_account for full budget detail after obtaining an account_number, and to use usaspending_list_agencies to look up agency_identifier codes. While it does not explicitly state when not to use this tool (e.g., vs. searching awards), the context of federal accounts is clear. The guidance is practical and linked to the workflow, earning a strong score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for organizations or individuals receiving federal funds by name, UEI (Unique Entity Identifier), or DUNS. Returns recipient hash IDs, UEI/DUNS identifiers, total award amounts, and hierarchy level. Results are paginated — use page to retrieve matches beyond the first page; page_metadata.total reports the full match count. Recipient hash IDs from this tool can be passed to usaspending_get_recipient for full profiles. Recipient level: P = parent organization, C = child entity, R = standalone.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based) — request the next page to retrieve matches beyond the first | |
| limit | No | Maximum results per page (1–100) | |
| keyword | Yes | Name, UEI, DUNS, or keyword to search for — partial matches are supported | |
| award_type | No | Filter by award type category to scope the total amounts returned |
| Name | Required | Description |
|---|---|---|
| page | No | Current page number returned |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint — how to continue to the next page when more results exist, or how to broaden the search when empty. Absent when the full match set fits on this page. |
| results | No | Matching recipients |
| has_next | No | Whether there are more pages of results |
| totalCount | No | Total matching recipients across all pages |
| page_metadata | No | Pagination metadata — page through with the page input to reach later matches |
| recipient_count | No | Number of matching recipients returned on this page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and idempotentHint, so the safety profile is known. The description adds behavioral nuance beyond annotations: pagination mechanics (use page, page_metadata.total), return fields, and hierarchy level definitions (P, C, R). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. Each sentence serves a purpose: core search action, returned fields, pagination, and hierarchical level explanation. No wasted words; ideal length for an agent to quickly parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which covers return values), the description covers essential aspects: what to search, pagination behavior, and hierarchy codes. It also references the companion tool. Minor gaps like error handling or rate limits are not documented, but they are not required given the annotations and output schema. Complete for typical agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds marginal semantics (e.g., 'partial matches are supported' is already in schema; pagination note aligns with page parameter but is more behavioral). No new parameter-level meaning is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Search for organizations or individuals receiving federal funds' by name, UEI, or DUNS. It distinguishes itself from siblings like usaspending_get_recipient by explicitly noting returned hash IDs feed into that tool. Purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States clear context: search for recipients by identifier and that results are paginated. Mentions companion usaspending_get_recipient for full profiles, implying a follow-up path. However, it doesn't explicitly state when NOT to use this tool or compare with other search siblings (e.g., usaspending_search_awards), so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate federal spending grouped by a specific dimension: NAICS industry code, PSC product/service code, awarding agency, funding agency, CFDA assistance program, or recipient. Returns top items with obligation amounts — useful for trend and breakdown analysis. Chain NAICS codes into usaspending_search_awards filters or usaspending_autocomplete_filters lookups.
| 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), recipient_duns, or recipient_parent_duns |
| Name | Required | Description |
|---|---|---|
| page | No | Current page returned |
| error | No | Present when the call failed. Absent on success. |
| notice | No | Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present. |
| 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_agency_name | No | Awarding agency name filter applied |
| applied_naics_codes | No | NAICS code filters applied (comma-separated) |
| applied_time_period_end | No | End date filter applied (YYYY-MM-DD) |
| applied_time_period_start | No | Start date filter applied (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that it returns 'top items with obligation amounts', which informs the agent of the output nature beyond just the schema. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero fluff. The primary purpose is stated first, followed by a usage hint, and a practical chaining example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and rich param schema. The description explains the return type (top items with obligation amounts) and gives a chaining workflow. It doesn't mention edge cases like empty results or specific filters, but these are covered by schema and are not critical for basic invocation.
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 all parameters are documented in the schema. The description does not elaborate on parameter formats or constraints beyond what the schema provides. The only added value is the chaining hint, but that is not parameter-specific. 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 states a specific verb ('Aggregate'), a resource ('federal spending'), and the grouping dimensions explicitly (NAICS, PSC, agency, CFDA, recipient). It clearly distinguishes this from sibling tools like search or time-series tools by focusing on 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 states it is 'useful for trend and breakdown analysis' and gives a concrete chaining example (NAICS codes into usaspending_search_awards or autocomplete_filters). It doesn't explicitly contrast with spending_over_time or by_geography, but the category focus and chaining hint make when-to-use clear enough.
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. Geographic filters accept FIPS codes and 2-letter state abbreviations — NOT place names. Resolve place names to FIPS codes using a geocoding server (Census or OpenStreetMap) before applying location filters. Chain per-capita results with Census population data for meaningful comparisons.
| 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. | |
| 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 (50 states), county (county-level), or district (congressional district) | |
| subawards | No | Include subaward data instead of prime award data |
| 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 | Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present. |
| 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_geo_layer | No | Geographic granularity applied: state, county, or district |
| 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) |
| total_areas_available | No | Number of geographic areas the filters matched, before limit was applied |
| applied_time_period_end | No | End date filter applied (YYYY-MM-DD) |
| applied_time_period_start | No | Start date filter applied (YYYY-MM-DD) |
| 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds non-obvious behavior: '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.' This alerts the agent to response size and limit semantics, which is value beyond the annotations. No contradiction exists.
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 four sentences with no redundant phrasing. The main purpose is front-loaded, followed by use cases, a critical input format warning, and a usage tip. Every sentence earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, a nested filters object, and an output schema (not shown but indicated). The description covers typical applications, the non-pagination behavior, and the prerequisite of FIPS resolution. It does not describe return value shape, but the output schema covers that. For a moderately complex aggregation tool, this is complete enough; a 4 reflects minor gaps like missing explicit notes on combining filters.
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 compensates further by explaining the FIPS/abbreviation constraint for geographic filters and pointing out the limit's client-side capping behavior with a concrete scale example. This adds practical meaning beyond the schema's per-field descriptions, particularly for the filters object.
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: 'Aggregate federal spending by state, county, or congressional district.' This clearly distinguishes it from sibling tools like spending_by_category (categories) and spending_over_time (time series). The resource and granularity are explicit, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use case guidance ('per-capita analysis, regional comparisons, and mapping federal investment patterns') and instructs on prerequisite steps ('Resolve place names to FIPS codes using a geocoding server'). It does not explicitly name alternative tools or state when not to use it, but the context is strong enough to guide an agent. A 4 is appropriate because it offers actionable usage conditions without explicit exclusions.
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, or NAICS code to trace spending trends in a specific area. Returns per-period totals and optional breakdowns by award category (contracts, grants, direct payments, IDVs, loans, other).
| 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 | Recovery hint when no periods are returned — suggests broadening filters. Absent when results are present. |
| 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_agency_name | No | Awarding agency name filter applied |
| applied_naics_codes | No | NAICS code filters applied (comma-separated) |
| applied_time_period_end | No | End date filter applied (YYYY-MM-DD) |
| applied_time_period_start | No | Start date filter applied (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering safety and mutability. The description adds valuable behavioral context beyond those: it explicitly defines the fiscal year (Oct–Sep) and warns that fiscal month 1 is October, not January—critical for correct interpretation of results. It also discloses the return structure (per-period totals and optional award-category breakdowns), which is not present in the annotations. No contradictions exist.
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 three sentences with no filler. The first sentence front-loads the core action and grouping options; the second adds a critical nuance about the fiscal year; the third explains filters and output shape. Every sentence earns its place, and the structure is logically ordered from purpose to caveat to usage, keeping it tight and skimmable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, one nested object, and an output schema), the description covers the essential usage context: the main grouping axis, the fiscal-year caveat, the filter dimensions, and the output shape. It does not mention defaults (e.g., award_type_codes defaulting to contracts) or the subawards toggle, but those are fully documented in the schema. Since the output schema exists, the description need not explain return values beyond what it already does. Overall, it is complete enough for an agent to invoke correctly without external documentation.
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 the 'group' enum, filters (keywords, agency_name, naics_codes, recipient_id, time_period_start/end, award_type_codes), and the 'subawards' flag. The description's mention of filter types and grouping parallels the schema without adding technical detail beyond what is already present. The fiscal-year clarification is useful but also exists in the schema's description for the 'group' parameter, so the description does not elevate understanding beyond the baseline for fully-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary action ('Fetch aggregated federal obligation amounts') and the exact grouping axis ('by fiscal year, fiscal quarter, or fiscal month'). It also specifies the filter dimensions (award type, agency, recipient, keyword, NAICS code), which distinguishes it from time-less aggregation tools like spending_by_category or spending_by_geography. The purpose is unmistakable and immediately differentiates the tool from its siblings.
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 implies usage for tracking spending trends over time ('to trace spending trends in a specific area') and clarifies fiscal-year semantics, which helps avoid misuse. However, it does not explicitly contrast itself with sibling tools (e.g., 'use this for time series, use spending_by_category for category breakdowns'). No when-not-to-use guidance is provided, so the agent must infer when this tool is preferable to alternatives.
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. Dates show when Glama detected each change.
usaspending_autocomplete_filters6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "type",
+ "search_text",
+ "results",
+ "total",
+ "lookup_type",
+ "query",
+ "result_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `no_match`: No codes or names matched the search text. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "no_match",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "type",
- "search_text",
- "results",
- "total",
- "lookup_type",
- "query",
- "result_count"
-]usaspending_disaster_spending6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "dimension",
+ "spending_type",
+ "results",
+ "applied_dimension"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "dimension",
- "spending_type",
- "results",
- "applied_dimension"
-]usaspending_get_agency6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "sub_agency_page",
+ "has_more_sub_agencies"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `agency_not_found`: No agency found for the given toptier_code or agency_slug. `missing_input`: Neither toptier_code nor agency_slug was provided. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "agency_not_found",
+ "missing_input",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "sub_agency_page",
- "has_more_sub_agencies"
-]usaspending_get_award5 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `award_not_found`: No award exists for the given award ID. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "award_not_found",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}usaspending_get_award_federal_accounts6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "current_page",
- "has_next_page"
-]usaspending_get_award_subawards6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "prime_award_id",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "prime_award_id",
- "current_page",
- "has_next_page"
-]usaspending_get_award_transactions6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "queried_award_id",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "queried_award_id",
- "current_page",
- "has_next_page"
-]usaspending_get_federal_account5 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `account_not_found`: No federal account found for the given account code. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "account_not_found",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}usaspending_get_federal_account_breakdown6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "account_code",
+ "dimension",
+ "results",
+ "page_metadata",
+ "applied_dimension",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "account_code",
- "dimension",
- "results",
- "page_metadata",
- "applied_dimension",
- "current_page",
- "has_next_page"
-]usaspending_get_idv_awards6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "award_id",
+ "results",
+ "page_metadata",
+ "parent_award_id",
+ "current_page",
+ "has_next_page"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "award_id",
- "results",
- "page_metadata",
- "parent_award_id",
- "current_page",
- "has_next_page"
-]usaspending_get_recipient5 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ }
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `recipient_not_found`: No recipient found for the given recipient ID. `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "recipient_not_found",
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}usaspending_list_agencies6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "total",
+ "agency_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "results",
- "total",
- "agency_count"
-]usaspending_search_awards6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. `pagination_limit_exceeded`: page multiplied by limit exceeds the endpoint 50,000-result page window and no cursor was supplied. `date_before_earliest`: The resolved start date precedes the 2007-10-01 earliest date this endpoint can search. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout",
+ "pagination_limit_exceeded",
+ "date_before_earliest"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "results",
- "page_metadata",
- "page",
- "has_next"
-]usaspending_search_federal_accounts6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "results",
- "page_metadata",
- "page",
- "has_next"
-]usaspending_search_recipients6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "results",
+ "page_metadata",
+ "recipient_count",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "results",
- "page_metadata",
- "recipient_count",
- "page",
- "has_next"
-]usaspending_spending_by_category6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "category",
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "category",
- "results",
- "page_metadata",
- "page",
- "has_next"
-]usaspending_spending_by_geography6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "scope",
+ "geo_layer",
+ "results",
+ "total",
+ "total_areas_available",
+ "applied_scope",
+ "applied_geo_layer",
+ "area_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "scope",
- "geo_layer",
- "results",
- "total",
- "total_areas_available",
- "applied_scope",
- "applied_geo_layer",
- "area_count"
-]usaspending_spending_over_time6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "group",
+ "results",
+ "total_periods",
+ "time_group",
+ "period_count"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `api_unavailable`: USAspending.gov API is unreachable or returns an error. `api_timeout`: USAspending.gov did not respond before the request deadline elapsed. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "api_unavailable",
+ "api_timeout"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "group",
- "results",
- "total_periods",
- "time_group",
- "period_count"
-]usaspending_disaster_spending4 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The result-set ceiling the upstream applied.",
+ "type": "number"
+}Output schema / properties / noticeAdded value: +{
+ "description": "Caveat explaining a capped total and how to bring the set under the cap.",
+ "type": "string"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of results returned on this page.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when the upstream capped the reachable result set rather than counting it.",
+ "type": "boolean"
+}usaspending_autocompleteusaspending_autocomplete_filtersusaspending_get_award3 fields changedOutput schema / properties / period_of_performance / properties / end_date / descriptionPrevious value: -"Performance end date"New value: +"Performance end date (YYYY-MM-DD)"Output schema / properties / period_of_performance / properties / potential_end_date / descriptionPrevious value: -"Potential end date including options"New value: +"Potential end date including options (YYYY-MM-DD)"Output schema / properties / period_of_performance / properties / start_date / descriptionPrevious value: -"Performance start date"New value: +"Performance start date (YYYY-MM-DD)"usaspending_search_awards2 fields changedInput schema / properties / agency_name / descriptionPrevious value: -"Filter to a specific awarding agency by name (e.g., \"Department of Defense\"). Use usaspending_autocomplete type=awarding_agency to find exact names."New value: +"Filter to a specific awarding agency by name (e.g., \"Department of Defense\"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names."Input schema / properties / naics_codes / descriptionPrevious value: -"Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete type=naics to look up codes."New value: +"Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete_filters type=naics to look up codes."usaspending_spending_by_geography9 fields changedInput schema / properties / filters / properties / award_type_codes / descriptionPrevious value: -"Award type codes: A/B/C/D (contracts), 02–05 (grants), 06/10 (direct payments), 07/08 (loans)"New value: +"Award type codes: A/B/C/D (contracts), IDV_A–IDV_E (IDVs), 02–05 (grants), 06/10 (direct payments), 07/08 (loans), 09/11 (insurance and other assistance), -1 (unspecified). Groups may be mixed here. Omit to aggregate every type."Input schema / properties / limitAdded value: +{
+ "default": 50,
+ "description": "Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-side. A nationwide county query matches over 3,000 areas.",
+ "maximum": 500,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / properties / applied_award_type_defaultAdded value: +{
+ "description": "Disclosure that no filters were supplied, so award_type_codes defaulted to the complete set. Absent when the caller supplied at least one filter.",
+ "type": "string"
+}Output schema / properties / capAdded value: +{
+ "description": "The limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of geographic areas returned.",
+ "type": "number"
+}Output schema / properties / total_areas_availableAdded value: +{
+ "description": "Number of geographic areas the filters matched, before limit was applied",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when the area list was capped at limit.",
+ "type": "boolean"
+}Output schema / properties / truncationCeilingAdded value: +{
+ "description": "Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones.",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "scope",
- "geo_layer",
- "results",
- "total",
- "applied_scope",
- "applied_geo_layer",
- "area_count"
-]New value: +[
+ "scope",
+ "geo_layer",
+ "results",
+ "total",
+ "total_areas_available",
+ "applied_scope",
+ "applied_geo_layer",
+ "area_count"
+]usaspending_search_awards7 fields changedInput schema / properties / last_record_sort_value / descriptionPrevious value: -"Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap. When both cursor fields are supplied, page is ignored."New value: +"Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap. The upstream stops emitting the pair once page × limit reaches 10,000, so take it from a page below that offset. When both cursor fields are supplied, page is ignored."Input schema / properties / page / descriptionPrevious value: -"Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit); to read past that, use the cursor fields below."New value: +"Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit), but the keyset cursor below is only returned while the offset stays under 10,000 — capture the cursor pair before paging past that, or the only way forward is page numbers."Output schema / properties / has_next / descriptionPrevious value: -"Whether there are more pages of results"New value: +"Whether more results may remain — set on a full page even when the upstream flag reports none."Output schema / properties / page_metadata / properties / has_next / descriptionPrevious value: -"Whether there are more pages of results"New value: +"Whether more results may remain — true on a full page even when the upstream flag reports none, since this endpoint under-reports continuation on a final full page and on every page past a 10,000-result offset. A short or empty page marks the end."Output schema / properties / page_metadata / properties / last_record_sort_value / descriptionPrevious value: -"Keyset-pagination cursor for the next page — pass back as last_record_sort_value to continue past the 50,000-result page limit"New value: +"Keyset-pagination cursor for the next page — pass back as last_record_sort_value to continue past the 50,000-result page limit. Absent once page × limit reaches 10,000, where the upstream stops emitting the pair."Output schema / properties / page_metadata / properties / last_record_unique_id / descriptionPrevious value: -"Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value"New value: +"Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value. Absent on the same pages that omit last_record_sort_value."Output schema / properties / truncated / descriptionPrevious value: -"True when this page was capped at `limit` and more results remain (continue via page or the cursor)."New value: +"True when this page was capped at `limit` and more results may remain (continue via page or the cursor)."usaspending_spending_over_time1 field changedOutput schema / properties / results / items / properties / idvsAdded value: +{
+ "description": "IDV (Indefinite Delivery Vehicle) obligation amount in USD for this period",
+ "type": "number"
+}usaspending_get_award_federal_accountsusaspending_get_federal_account2 fields changedInput schema / properties / account_code / descriptionPrevious value: -"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts."New value: +"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts."Output schema / properties / childrenAdded value: +{
+ "description": "Treasury Account Symbol (TAS) components that make up this federal account, each with its own obligated, outlay, and budgetary-resource amounts. Omitted when the upstream returns none.",
+ "items": {
+ "additionalProperties": false,
+ "description": "Treasury Account Symbol component with its own financial amounts",
+ "properties": {
+ "budgetary_resources_amount": {
+ "description": "Budgetary resources in USD for this Treasury Account Symbol",
+ "type": "number"
+ },
+ "code": {
+ "description": "Full Treasury Account Symbol (e.g., 080-2020/2021-0120-000) — the availability-period-scoped component of this federal account, not an account_code accepted by this tool",
+ "type": "string"
+ },
+ "gross_outlay_amount": {
+ "description": "Gross outlay amount in USD for this Treasury Account Symbol",
+ "type": "number"
+ },
+ "name": {
+ "description": "Treasury Account Symbol title",
+ "type": "string"
+ },
+ "obligated_amount": {
+ "description": "Obligated amount in USD for this Treasury Account Symbol",
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+}usaspending_get_federal_account_breakdownusaspending_get_federal_account1 field changedInput schema / properties / account_code / descriptionPrevious value: -"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Appears in award funding details from usaspending_get_award."New value: +"Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts."usaspending_search_awards1 field changedOutput schema / properties / upstream_messages / descriptionPrevious value: -"Notices the USAspending API returned for this request — e.g. a supplied filter that was ignored because this endpoint does not support it, or the 2007-10-01 date-floor note. Present whenever the API returns any messages."New value: +"Notices the USAspending API returned with this response — e.g. a supplied filter it ignored because this endpoint does not support it. Every successful response also carries a standing advisory that search covers 2007-10-01 onward; that advisory is boilerplate, not a verdict on the dates requested. Present whenever the API returns any messages."usaspending_spending_over_time4 fields changedInput schema / properties / group / descriptionPrevious value: -"Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (calendar month)"New value: +"Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (fiscal month — an ordinal within the fiscal year, where 1 = October)"Output schema / properties / results / items / properties / time_period / descriptionPrevious value: -"Time period for this row"New value: +"Time period for this row. Populated per the requested grouping: fiscal_year alone, fiscal_year + quarter, or fiscal_year + month."Output schema / properties / results / items / properties / time_period / properties / calendar_yearRemoved value: -{
- "description": "Calendar year",
- "type": "string"
-}Output schema / properties / results / items / properties / time_period / properties / month / descriptionPrevious value: -"Calendar month (1–12)"New value: +"Fiscal month: an ordinal within fiscal_year, 1–12, where 1 = October and 12 = September. Fiscal month 1 of FY2025 is October 2024 — not January."usaspending_get_agency14 fields changedInput schema / properties / pageAdded value: +{
+ "default": 1,
+ "description": "Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.",
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / properties / budget_authority_amountRemoved value: -{
- "description": "Total budget authority amount in USD for current fiscal year",
- "type": "number"
-}Output schema / properties / budgetary_resources_amountAdded value: +{
+ "description": "Total budgetary resources in USD for the fiscal year",
+ "type": "number"
+}Output schema / properties / fiscal_yearAdded value: +{
+ "description": "Fiscal year the budgetary totals below reflect (most recent available)",
+ "type": "number"
+}Output schema / properties / has_more_sub_agenciesAdded value: +{
+ "description": "Whether more sub-agency pages are available",
+ "type": "boolean"
+}Output schema / properties / noticeAdded value: +{
+ "description": "Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown.",
+ "type": "string"
+}Output schema / properties / obligated_amount / descriptionPrevious value: -"Total obligated amount in USD for current fiscal year"New value: +"Total amount obligated in USD for the fiscal year"Output schema / properties / outlay_amountAdded value: +{
+ "description": "Total outlays in USD for the fiscal year",
+ "type": "number"
+}Output schema / properties / sub_agencies / descriptionPrevious value: -"Sub-agency breakdown within this toptier agency"New value: +"Sub-agency breakdown within this toptier agency (one page)"Output schema / properties / sub_agency_pageAdded value: +{
+ "description": "Current sub-agency page returned",
+ "type": "number"
+}Output schema / properties / sub_agency_page_metadataAdded value: +{
+ "additionalProperties": false,
+ "description": "Pagination metadata for the sub-agency breakdown",
+ "properties": {
+ "has_next": {
+ "description": "Whether more sub-agency pages are available",
+ "type": "boolean"
+ },
+ "limit": {
+ "description": "Sub-agencies per page",
+ "type": "number"
+ },
+ "page": {
+ "description": "Current sub-agency page number",
+ "type": "number"
+ },
+ "total": {
+ "description": "Total sub-agencies across all pages",
+ "type": "number"
+ }
+ },
+ "required": [
+ "page",
+ "has_next",
+ "limit"
+ ],
+ "type": "object"
+}Output schema / properties / sub_agency_totalAdded value: +{
+ "description": "Total sub-agencies across all pages (when available)",
+ "type": "number"
+}Output schema / properties / transactions_countRemoved value: -{
- "description": "Total transaction count",
- "type": "number"
-}Output schema / requiredAdded value: +[
+ "sub_agency_page",
+ "has_more_sub_agencies"
+]usaspending_get_award1 field changedOutput schema / properties / transactions_countRemoved value: -{
- "description": "Number of transactions; use with usaspending_get_award_transactions",
- "type": "number"
-}usaspending_get_award_transactions1 field changedOutput schema / properties / notice / descriptionPrevious value: -"Guidance when no transactions were returned — suggests checking transactions_count from usaspending_get_award first. Absent when results are present."New value: +"Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present."usaspending_get_recipient9 fields changedOutput schema / properties / business_types_descriptionRemoved value: -{
- "description": "Human-readable business type descriptions",
- "items": {
- "type": "string"
- },
- "type": "array"
-}Output schema / properties / location / properties / zipAdded value: +{
+ "description": "ZIP code",
+ "type": "string"
+}Output schema / properties / location / properties / zip4Added value: +{
+ "description": "ZIP+4 extension",
+ "type": "string"
+}Output schema / properties / location / properties / zip5Removed value: -{
- "description": "5-digit ZIP code",
- "type": "string"
-}Output schema / properties / totalRemoved value: -{
- "additionalProperties": false,
- "description": "Total award amounts by type",
- "properties": {
- "contracts": {
- "description": "Total contracts amount in USD",
- "type": "number"
- },
- "direct_payments": {
- "description": "Total direct payments amount in USD",
- "type": "number"
- },
- "grants": {
- "description": "Total grants amount in USD",
- "type": "number"
- },
- "loans": {
- "description": "Total loans amount in USD",
- "type": "number"
- },
- "other": {
- "description": "Total other financial assistance amount in USD",
- "type": "number"
- }
- },
- "type": "object"
-}Output schema / properties / total_face_value_loan_amountAdded value: +{
+ "description": "Total face value of loans in USD",
+ "type": "number"
+}Output schema / properties / total_face_value_loan_transactionsAdded value: +{
+ "description": "Number of face-value loan transactions",
+ "type": "number"
+}Output schema / properties / total_transaction_amountAdded value: +{
+ "description": "Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided",
+ "type": "number"
+}Output schema / properties / total_transactionsAdded value: +{
+ "description": "Total number of award transactions",
+ "type": "number"
+}usaspending_autocomplete6 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (1–50)"New value: +"Maximum number of results to return (1–500). The recipient lookup enforces an upstream max of 500; naics/psc/cfda/awarding_agency return only their matching entries regardless."Input schema / properties / limit / maximumPrevious value: -50New value: +500Output schema / properties / results / items / descriptionPrevious value: -"Matched code entry with optional code, name, and ID fields"New value: +"Matched entry — code/name for code lookups, name plus optional UEI/DUNS for recipients"Output schema / properties / results / items / properties / dunsAdded value: +{
+ "description": "DUNS number (legacy) — recipient type only; populated when the search text matches a DUNS",
+ "type": "string"
+}Output schema / properties / results / items / properties / id / descriptionPrevious value: -"Numeric or string ID (for agency and recipient types)"New value: +"Numeric or string ID (for the awarding_agency type)"Output schema / properties / results / items / properties / ueiAdded value: +{
+ "description": "Unique Entity Identifier (SAM.gov) — recipient type only; populated when the search text matches a UEI",
+ "type": "string"
+}usaspending_get_idv_awards3 fields changedOutput schema / properties / has_next_page / descriptionPrevious value: -"Whether there are more pages of child awards"New value: +"Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none."Output schema / properties / page_metadata / properties / has_next / descriptionPrevious value: -"Whether there are more pages of results"New value: +"Whether more child awards may remain — true on a full page even when the upstream flag reports none (this endpoint returns no total). A short or empty page marks the end."Output schema / properties / truncated / descriptionPrevious value: -"True when more child awards remain beyond this page."New value: +"True when this page was full and more child awards may remain beyond it."usaspending_search_recipients15 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum results to return (1–100)"New value: +"Maximum results per page (1–100)"Input schema / properties / pageAdded value: +{
+ "default": 1,
+ "description": "Page number (1-based) — request the next page to retrieve matches beyond the first",
+ "maximum": 9007199254740991,
+ "minimum": 1,
+ "type": "integer"
+}Output schema / properties / capRemoved value: -{
- "description": "The limit that was applied.",
- "type": "number"
-}Output schema / properties / has_nextAdded value: +{
+ "description": "Whether there are more pages of results",
+ "type": "boolean"
+}Output schema / properties / notice / descriptionPrevious value: -"Recovery hint when results are empty — suggests how to broaden the search. Absent when results are present."New value: +"Recovery hint — how to continue to the next page when more results exist, or how to broaden the search when empty. Absent when the full match set fits on this page."Output schema / properties / pageAdded value: +{
+ "description": "Current page number returned",
+ "type": "number"
+}Output schema / properties / page_metadataAdded value: +{
+ "additionalProperties": false,
+ "description": "Pagination metadata — page through with the page input to reach later matches",
+ "properties": {
+ "has_next": {
+ "description": "Whether there are more pages of results",
+ "type": "boolean"
+ },
+ "limit": {
+ "description": "Results per page",
+ "type": "number"
+ },
+ "page": {
+ "description": "Current page number",
+ "type": "number"
+ },
+ "total": {
+ "description": "Total matching recipients across all pages",
+ "type": "number"
+ }
+ },
+ "required": [
+ "page",
+ "has_next",
+ "limit"
+ ],
+ "type": "object"
+}Output schema / properties / recipient_count / descriptionPrevious value: -"Number of matching recipients returned"New value: +"Number of matching recipients returned on this page"Output schema / properties / results / items / properties / locationRemoved value: -{
- "additionalProperties": false,
- "description": "Recipient address location",
- "properties": {
- "city_name": {
- "description": "City of recipient address",
- "type": "string"
- },
- "country_code": {
- "description": "Country code",
- "type": "string"
- },
- "state_code": {
- "description": "State code",
- "type": "string"
- }
- },
- "type": "object"
-}Output schema / properties / results / items / properties / stateRemoved value: -{
- "description": "State code of recipient address",
- "type": "string"
-}Output schema / properties / shownRemoved value: -{
- "description": "Number of recipients returned.",
- "type": "number"
-}Output schema / properties / totalRemoved value: -{
- "description": "Number of results returned",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total matching recipients across all pages",
+ "type": "number"
+}Output schema / properties / truncatedRemoved value: -{
- "description": "True when results were capped at the limit.",
- "type": "boolean"
-}Output schema / requiredPrevious value: -[
- "results",
- "total",
- "recipient_count"
-]New value: +[
+ "results",
+ "page_metadata",
+ "recipient_count",
+ "page",
+ "has_next"
+]usaspending_search_awards15 fields changedInput schema / properties / filtersAdded value: +{
+ "description": "Optional analytics-style filter object mirroring the shape the spending analytics tools accept, for reusing one filter set across tools. When both this object and the equivalent top-level flat filters are given, this object wins per-field. recipient_id is intentionally not accepted — this endpoint silently ignores it; filter by recipient via recipient_name.",
+ "properties": {
+ "agency_name": {
+ "description": "Awarding agency name (toptier), e.g., \"Department of Defense\"",
+ "type": "string"
+ },
+ "award_type_codes": {
+ "description": "Award type codes; all must belong to one group (A/B/C/D, 02/03/04/05, 06/10, 07/08, IDV_A–IDV_E)",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "keywords": {
+ "description": "Full-text search terms across award descriptions, recipient names, and places",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "naics_codes": {
+ "description": "NAICS industry codes to require, e.g., [\"541512\"]",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "recipient_name": {
+ "description": "Recipient name search (partial match); maps to recipient_search_text. Use instead of recipient_id, which this endpoint ignores.",
+ "type": "string"
+ },
+ "time_period_end": {
+ "description": "End date (YYYY-MM-DD). Requires time_period_start.",
+ "type": "string"
+ },
+ "time_period_start": {
+ "description": "Start date (YYYY-MM-DD); earliest valid 2007-10-01. Requires time_period_end.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}Input schema / properties / last_record_sort_valueAdded value: +{
+ "description": "Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap. When both cursor fields are supplied, page is ignored.",
+ "type": "string"
+}Input schema / properties / last_record_unique_idAdded value: +{
+ "description": "Keyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Input schema / properties / page / descriptionPrevious value: -"Page number (1-based)"New value: +"Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit); to read past that, use the cursor fields below."Input schema / properties / recipient_name / descriptionPrevious value: -"Filter by recipient name (partial match). Use usaspending_search_recipients for precise recipient_id filtering."New value: +"Filter by recipient name (partial match); maps to this endpoint's recipient_search_text. This endpoint has no recipient_id filter — use usaspending_search_recipients to look up a recipient by name."Output schema / properties / capAdded value: +{
+ "description": "Per-page cap (limit) applied to this page.",
+ "type": "number"
+}Output schema / properties / page_metadata / descriptionPrevious value: -"Pagination metadata"New value: +"Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page."Output schema / properties / page_metadata / properties / last_record_sort_valueAdded value: +{
+ "description": "Keyset-pagination cursor for the next page — pass back as last_record_sort_value to continue past the 50,000-result page limit",
+ "type": "string"
+}Output schema / properties / page_metadata / properties / last_record_unique_idAdded value: +{
+ "description": "Keyset-pagination cursor for the next page — pass back as last_record_unique_id alongside last_record_sort_value",
+ "type": "number"
+}Output schema / properties / page_metadata / properties / totalRemoved value: -{
- "description": "Total number of matching awards",
- "type": "number"
-}Output schema / properties / results / items / properties / agency_slugAdded value: +{
+ "description": "URL-friendly awarding-agency slug (e.g., national-aeronautics-and-space-administration) — pass to usaspending_get_agency as agency_slug. Absent when the agency has no profile page.",
+ "type": "string"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of awards returned on this page.",
+ "type": "number"
+}Output schema / properties / totalCountRemoved value: -{
- "description": "Total number of matching awards across all pages (when available)",
- "type": "number"
-}Output schema / properties / truncatedAdded value: +{
+ "description": "True when this page was capped at `limit` and more results remain (continue via page or the cursor).",
+ "type": "boolean"
+}Output schema / properties / upstream_messagesAdded value: +{
+ "description": "Notices the USAspending API returned for this request — e.g. a supplied filter that was ignored because this endpoint does not support it, or the 2007-10-01 date-floor note. Present whenever the API returns any messages.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}usaspending_disaster_spending6 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum results per page (1–100, not used for overview dimension)"New value: +"Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated."Input schema / properties / spending_type / descriptionPrevious value: -"Data type: award (award-level obligations and outlays) or total (includes direct non-award spending). Applies to agency and recipient dimensions only."New value: +"Data type for the agency and recipient dimensions: award (award-level obligations and outlays) or total (includes direct non-award spending). Ignored for cfda and overview; the geography dimension is not user-controllable and always reports obligation-based amounts."Output schema / properties / results / items / properties / aggregated_amount / descriptionPrevious value: -"Aggregated amount in USD (geography dimension)"New value: +"Obligation-based spending amount in USD (geography dimension)"Output schema / properties / results / items / properties / per_capitaAdded value: +{
+ "description": "Obligation-based spending per capita in USD (geography dimension)",
+ "type": "number"
+}Output schema / properties / results / items / properties / populationAdded value: +{
+ "description": "Population of the geographic area (geography dimension)",
+ "type": "number"
+}Output schema / properties / spending_type / descriptionPrevious value: -"Data type returned (award or total)"New value: +"Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview"usaspending_autocomplete3 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of results returned.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when results were capped at the limit.",
+ "type": "boolean"
+}usaspending_disaster_spending2 fields changedOutput schema / properties / result_totalRemoved value: -{
- "description": "Total items for paginated dimensions (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total items for paginated dimensions (when available)",
+ "type": "number"
+}usaspending_get_award_subawards2 fields changedOutput schema / properties / subaward_totalRemoved value: -{
- "description": "Total subaward count across all pages (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total subaward count across all pages (when available)",
+ "type": "number"
+}usaspending_get_award_transactions2 fields changedOutput schema / properties / totalCountAdded value: +{
+ "description": "Total transaction count across all pages (when available)",
+ "type": "number"
+}Output schema / properties / transaction_totalRemoved value: -{
- "description": "Total transaction count across all pages (when available)",
- "type": "number"
-}usaspending_get_idv_awards3 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The per-page limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of child awards returned on this page.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when more child awards remain beyond this page.",
+ "type": "boolean"
+}usaspending_search_awards2 fields changedOutput schema / properties / totalRemoved value: -{
- "description": "Total number of matching awards across all pages (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of matching awards across all pages (when available)",
+ "type": "number"
+}usaspending_search_federal_accounts2 fields changedOutput schema / properties / totalRemoved value: -{
- "description": "Total number of matching accounts across all pages (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of matching accounts across all pages (when available)",
+ "type": "number"
+}usaspending_search_recipients3 fields changedOutput schema / properties / capAdded value: +{
+ "description": "The limit that was applied.",
+ "type": "number"
+}Output schema / properties / shownAdded value: +{
+ "description": "Number of recipients returned.",
+ "type": "number"
+}Output schema / properties / truncatedAdded value: +{
+ "description": "True when results were capped at the limit.",
+ "type": "boolean"
+}usaspending_spending_by_category2 fields changedOutput schema / properties / totalRemoved value: -{
- "description": "Total number of items in this category (when available)",
- "type": "number"
-}Output schema / properties / totalCountAdded value: +{
+ "description": "Total number of items in this category (when available)",
+ "type": "number"
+}usaspending_get_award_subawards1 field changedOutput schema / properties / noticeAdded value: +{
+ "description": "Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present.",
+ "type": "string"
+}usaspending_get_award_transactions1 field changedOutput schema / properties / noticeAdded value: +{
+ "description": "Guidance when no transactions were returned — suggests checking transactions_count from usaspending_get_award first. Absent when results are present.",
+ "type": "string"
+}usaspending_get_idv_awardsusaspending_search_awards7 fields changedInput schema / properties / naics_codeRemoved value: -{
- "description": "Filter by NAICS industry code (e.g., \"541512\"). Use usaspending_autocomplete type=naics to look up codes.",
- "type": "string"
-}Input schema / properties / naics_codesAdded value: +{
+ "description": "Filter by NAICS industry codes (e.g., [\"541512\"]). Use usaspending_autocomplete type=naics to look up codes.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Output schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordAdded value: +{
+ "description": "Keyword filter applied to this search",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS codes filter applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_search_federal_accountsusaspending_spending_by_category5 fields changedOutput schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordsAdded value: +{
+ "description": "Keyword filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS code filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_spending_by_geography5 fields changedOutput schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordsAdded value: +{
+ "description": "Keyword filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS code filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_spending_over_time5 fields changedOutput schema / properties / applied_agency_nameAdded value: +{
+ "description": "Awarding agency name filter applied",
+ "type": "string"
+}Output schema / properties / applied_keywordsAdded value: +{
+ "description": "Keyword filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_naics_codesAdded value: +{
+ "description": "NAICS code filters applied (comma-separated)",
+ "type": "string"
+}Output schema / properties / applied_time_period_endAdded value: +{
+ "description": "End date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}Output schema / properties / applied_time_period_startAdded value: +{
+ "description": "Start date filter applied (YYYY-MM-DD)",
+ "type": "string"
+}usaspending_disaster_spending2 fields changedInput schema / properties / filters / descriptionPrevious value: -"Optional filters — def_codes narrows to a specific emergency appropriation"New value: +"Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)"Input schema / properties / filters / properties / def_codes / descriptionPrevious value: -"DEF codes to filter by (e.g., [\"L\", \"M\", \"N\", \"O\", \"P\"] for COVID-19). Omit to include all emergency funding."New 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."usaspending_spending_by_geography1 field changedOutput schema / properties / noticeAdded value: +{
+ "description": "Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present.",
+ "type": "string"
+}usaspending_spending_over_time1 field changedOutput schema / properties / noticeAdded value: +{
+ "description": "Recovery hint when no periods are returned — suggests broadening filters. Absent when results are present.",
+ "type": "string"
+}usaspending_autocomplete4 fields changedOutput schema / properties / lookup_typeAdded value: +{
+ "description": "Lookup table that was searched",
+ "type": "string"
+}Output schema / properties / queryAdded value: +{
+ "description": "Search text sent to the autocomplete API",
+ "type": "string"
+}Output schema / properties / result_countAdded value: +{
+ "description": "Number of matching results returned",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "type",
- "search_text",
- "results",
- "total"
-]New value: +[
+ "type",
+ "search_text",
+ "results",
+ "total",
+ "lookup_type",
+ "query",
+ "result_count"
+]usaspending_disaster_spending5 fields changedOutput schema / properties / applied_dimensionAdded value: +{
+ "description": "Breakdown dimension applied",
+ "type": "string"
+}Output schema / properties / current_pageAdded value: +{
+ "description": "Current page (non-overview dimensions)",
+ "type": "number"
+}Output schema / properties / has_next_pageAdded value: +{
+ "description": "Whether there are more pages",
+ "type": "boolean"
+}Output schema / properties / result_totalAdded value: +{
+ "description": "Total items for paginated dimensions (when available)",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "dimension",
- "spending_type",
- "results"
-]New value: +[
+ "dimension",
+ "spending_type",
+ "results",
+ "applied_dimension"
+]usaspending_get_award_subawards5 fields changedOutput schema / properties / current_pageAdded value: +{
+ "description": "Current page returned",
+ "type": "number"
+}Output schema / properties / has_next_pageAdded value: +{
+ "description": "Whether there are more pages of subawards",
+ "type": "boolean"
+}Output schema / properties / prime_award_idAdded value: +{
+ "description": "Prime award ID whose subawards were listed",
+ "type": "string"
+}Output schema / properties / subaward_totalAdded value: +{
+ "description": "Total subaward count across all pages (when available)",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "award_id",
- "results",
- "page_metadata"
-]New value: +[
+ "award_id",
+ "results",
+ "page_metadata",
+ "prime_award_id",
+ "current_page",
+ "has_next_page"
+]usaspending_get_award_transactions5 fields changedOutput schema / properties / current_pageAdded value: +{
+ "description": "Current page returned",
+ "type": "number"
+}Output schema / properties / has_next_pageAdded value: +{
+ "description": "Whether there are more pages of transactions",
+ "type": "boolean"
+}Output schema / properties / queried_award_idAdded value: +{
+ "description": "Award ID whose transactions were listed",
+ "type": "string"
+}Output schema / properties / transaction_totalAdded value: +{
+ "description": "Total transaction count across all pages (when available)",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "award_id",
- "results",
- "page_metadata"
-]New value: +[
+ "award_id",
+ "results",
+ "page_metadata",
+ "queried_award_id",
+ "current_page",
+ "has_next_page"
+]usaspending_list_agencies2 fields changedOutput schema / properties / agency_countAdded value: +{
+ "description": "Total number of top-tier federal agencies returned",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "results",
- "total"
-]New value: +[
+ "results",
+ "total",
+ "agency_count"
+]usaspending_search_awards6 fields changedOutput schema / properties / has_nextAdded value: +{
+ "description": "Whether there are more pages of results",
+ "type": "boolean"
+}Output schema / properties / messageRemoved value: -{
- "description": "Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present.",
- "type": "string"
-}Output schema / properties / noticeAdded value: +{
+ "description": "Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present.",
+ "type": "string"
+}Output schema / properties / pageAdded value: +{
+ "description": "Current page number returned",
+ "type": "number"
+}Output schema / properties / totalAdded value: +{
+ "description": "Total number of matching awards across all pages (when available)",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "results",
- "page_metadata"
-]New value: +[
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+]usaspending_search_recipients4 fields changedOutput schema / properties / messageRemoved value: -{
- "description": "Recovery hint when results are empty — suggests how to broaden the search. Absent when results are present.",
- "type": "string"
-}Output schema / properties / noticeAdded value: +{
+ "description": "Recovery hint when results are empty — suggests how to broaden the search. Absent when results are present.",
+ "type": "string"
+}Output schema / properties / recipient_countAdded value: +{
+ "description": "Number of matching recipients returned",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "results",
- "total"
-]New value: +[
+ "results",
+ "total",
+ "recipient_count"
+]usaspending_spending_by_category6 fields changedOutput schema / properties / has_nextAdded value: +{
+ "description": "Whether there are more pages",
+ "type": "boolean"
+}Output schema / properties / messageRemoved value: -{
- "description": "Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present.",
- "type": "string"
-}Output schema / properties / noticeAdded value: +{
+ "description": "Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present.",
+ "type": "string"
+}Output schema / properties / pageAdded value: +{
+ "description": "Current page returned",
+ "type": "number"
+}Output schema / properties / totalAdded value: +{
+ "description": "Total number of items in this category (when available)",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "category",
- "results",
- "page_metadata"
-]New value: +[
+ "category",
+ "results",
+ "page_metadata",
+ "page",
+ "has_next"
+]usaspending_spending_by_geography4 fields changedOutput schema / properties / applied_geo_layerAdded value: +{
+ "description": "Geographic granularity applied: state, county, or district",
+ "type": "string"
+}Output schema / properties / applied_scopeAdded value: +{
+ "description": "Location scope applied: place_of_performance or recipient_location",
+ "type": "string"
+}Output schema / properties / area_countAdded value: +{
+ "description": "Number of geographic areas returned",
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "scope",
- "geo_layer",
- "results",
- "total"
-]New value: +[
+ "scope",
+ "geo_layer",
+ "results",
+ "total",
+ "applied_scope",
+ "applied_geo_layer",
+ "area_count"
+]usaspending_spending_over_time3 fields changedOutput schema / properties / period_countAdded value: +{
+ "description": "Number of time periods returned",
+ "type": "number"
+}Output schema / properties / time_groupAdded value: +{
+ "description": "Time grouping applied: fiscal_year, quarter, or month",
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "group",
- "results",
- "total_periods"
-]New value: +[
+ "group",
+ "results",
+ "total_periods",
+ "time_group",
+ "period_count"
+]usaspending_autocompleteusaspending_disaster_spendingusaspending_get_agencyusaspending_get_awardusaspending_get_award_subawardsusaspending_get_award_transactionsusaspending_get_federal_accountusaspending_get_recipientusaspending_list_agenciesusaspending_search_awardsusaspending_search_recipientsusaspending_spending_by_categoryusaspending_spending_by_geographyusaspending_spending_over_timeClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
USAspending MCP — Federal spending data from USAspending.gov API
US federal contracts, grants, and spending awards
SAM.gov contract opportunities and entity lookup (BYOK) plus USASpending federal award data.
Research U.S. federal contracts, awards, vendors, changes, exclusions, and source documents.
Add one secure layer between your agents and this server.
Each tool targets a distinct entity or operation: agency, award, subaward, transaction, federal account, recipient, and various spending breakdowns. Even similar-sounding tools like get_award_federal_accounts vs get_federal_account are clearly separated by their core purpose (award funding sources vs account budget details).
Almost all tools follow the usaspending_<verb>_<object> pattern (e.g., get_award, search_recipients). The spending_* series breaks the verb-noun convention but is internally consistent. Minor deviation lowers the score slightly.
At 18 tools, this is on the higher end of reasonable but each tool maps to a distinct USAspending API endpoint and covers a different aspect of federal spending. The count is justified by the breadth of the domain, though it feels slightly heavy.
The surface covers award search/detail, agency navigation, federal accounts, recipients, subawards, transactions, IDVs, and multiple spending aggregations (category, geography, time, disaster). No obvious dead ends: all ID-producing tools have corresponding lookup tools, and common workflows like award→federal account→breakdown are fully supported.
