Skip to main content
Glama

usaspending-mcp-server

by io.github.cyanheads

Search Federal Awards

usaspending_search_awards
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNoPage 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.
sortNoSort field for resultsAward Amount
limitNoMaximum results per page (1–100)
orderNoSort directiondesc
filtersNoOptional 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.
keywordNoFull-text search across award descriptions, recipient names, and place names
agency_nameNoFilter to a specific awarding agency by name (e.g., "Department of Defense"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names.
naics_codesNoFilter by NAICS industry codes (e.g., ["541512"]). Use usaspending_autocomplete_filters type=naics to look up codes.
time_periodNoFilter awards by date range (action date)
recipient_nameNoFilter 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_filterNoFilter 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_codesNoFilter 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_idNoKeyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value.
last_record_sort_valueNoKeyset-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.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoPer-page cap (limit) applied to this page.
pageNoCurrent page number returned
errorNoPresent when the call failed. Absent on success.
shownNoNumber of awards returned on this page.
noticeNoRecovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present.
resultsNoMatching award summaries
has_nextNoWhether more results may remain — set on a full page even when the upstream flag reports none.
truncatedNoTrue when this page was capped at `limit` and more results may remain (continue via page or the cursor).
page_metadataNoPagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page.
applied_keywordNoKeyword filter applied to this search
upstream_messagesNoNotices 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_nameNoAwarding agency name filter applied
applied_naics_codesNoNAICS codes filter applied (comma-separated)
applied_time_period_endNoEnd date filter applied (YYYY-MM-DD)
applied_time_period_startNoStart date filter applied (YYYY-MM-DD)

TDQS

A4.3/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

All usaspending-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.3/5.0
Disambiguation5/5

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).

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness5/5

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.

Resources