Skip to main content
Glama

Search past awards

search_awards
Read-onlyIdempotent

Use this when the user asks who won government contracts or grants: past awards by NAICS, agency, state, awardee name or UEI, with amounts and dates.

Filters: type (contract_award, grant_award or any), naics (up to 10 codes), agency (a name; the note says which agency it matched), state, awardee (part of a name), uei, keyword (matched in the title; a grant award's title is its recipient's name), awarded_within_days (1 to 1095, default 365), limit (1 to 50, default 20). If has_more is true, call again with cursor=next_cursor and the same filters. Example: naics="541512", agency="Department of Veterans Affairs". Pass several NAICS codes in one call.

Award records may be incomplete, so say so. Head a grant award with its awardee name and CFDA number, not its title. Pass an awardee's uei to get_company for its full history.

Print each award's url and source_url as markdown links; they are the award's details. An award id is not an opportunity id: get_opportunity does not take it.

Do not use for open opportunities to bid on (search_contracts, search_grants) or for one firm's history when its UEI is known (get_company).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_awards"
  }
}

Input Schema

NameRequiredDescriptionDefault
ueiNoThe awardee's 12-character UEI.
typeNocontract_award (federal contracts), grant_award, or any (both).any
limitNoNumber of results to return, 1 to 50.
naicsNoUp to 10 six-digit NAICS codes, comma-separated, e.g. '236220' or '541511,541512'. A record matches on its own codes (matched_naics says which). Unknown codes are ignored.
stateNoTwo-letter US state code of the place of performance.
agencyNoAgency name, e.g. 'Department of Veterans Affairs'; matched to the closest MatchAwards agency, which the result note names.
cursorNonext_cursor from the previous response. Pass it with the same filters to get the next page.
awardeeNoPart of the awardee's name, 2 to 100 characters.
keywordNo2 to 100 characters matched against the title only.
awarded_within_daysNoOnly awards from the last N days, 1 to 1095 (default 365).

Output Schema

NameRequiredDescriptionDefault
noteNo
as_ofNoWhen the API generated the results (ISO time).
resultsYes
warningNoSet when paging stopped early; the results so far are still valid.
has_moreYestrue: call again with cursor=next_cursor and the same filters.
next_cursorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / $defs / AwardRow / properties / id / description
      Previous value: -"Award id; null when the award has no page on matchawards.com."New value: +"Award id; null when the award has no page on matchawards.com. Not an opportunity id: get_opportunity does not take it."
  2. Added

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description goes further with non-obvious behavior: records may be incomplete and should be flagged as such, pagination works by re-calling with cursor=next_cursor plus identical filters, the agency filter is fuzzy-matched and the result note names the match, and an award id is not an opportunity id. It also specifies output presentation (print url and source_url as markdown links; head grant awards by awardee name and CFDA number, not title), which is real behavioral context not available in structured fields.

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?

It is front-loaded: the use case comes first, then a compact filter inventory, then pagination, then caveats, then exclusions. Nearly every sentence carries routing or behavioral information, though the filter parentheticals duplicate defaults already documented in the schema, adding minor redundancy to an otherwise dense and well-ordered block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter search tool with an output schema and full annotation coverage, this description covers everything an agent needs: selection criteria, filter semantics, pagination protocol, data-quality caveats, result presentation, and the sibling handoffs. Return-value shape is correctly left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 nevertheless adds meaning beyond the schema by noting that multiple NAICS codes belong in one call, that a grant award's title is its recipient's name (so keyword matching behaves differently for grants), and that matched_naics identifies which code hit. It partly wastes space restating schema facts like limit 1-50 default 20 and awarded_within_days 1-1095 default 365, which keeps it from a 5.

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 opening sentence states a specific verb and resource ('past awards' / 'who won government contracts or grants') and enumerates the dimensions it can search by (NAICS, agency, state, awardee name or UEI). It explicitly contrasts past awards with open opportunities, so the agent can distinguish it from search_contracts and search_grants without inspecting either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is an explicit when-to-use clause ('when the user asks who won government contracts or grants') and explicit when-not clauses: not for open opportunities (search_contracts, search_grants) and not for one firm's history when its UEI is known (get_company). It also routes onward ('Pass an awardee's uei to get_company'), which is exactly the alternative-selection guidance an agent needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.