usas_search_recipients
Search USAspending recipients by keyword with parent/child/recipient hierarchy. Returns recipient IDs, DUNS, UEI, level, and total amount to use before retrieving recipient profile.
Instructions
Search USAspending recipient list with parent/child/recipient hierarchy. Returns recipients with id, duns, uei, level (P=parent, C=child, R=recipient), total_amount. Use for 'find the recipient_id for Booz Allen' before usas_get_recipient_profile.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | ||
| recipientLevel | No | P=parent, C=child, R=recipient | |
| limit | No |
Implementation Reference
- src/usaspending.ts:698-734 (handler)The actual handler function 'searchRecipients' that executes the tool logic. It POSTs to USAspending's 'recipient/' endpoint with keyword, optional recipientLevel, and limit. Returns recipients with id, duns, uei, name, level, totalAmount.
export async function searchRecipients(args: { keyword: string; recipientLevel?: "P" | "C" | "R"; limit?: number; }) { type Resp = { page_metadata?: { total?: number }; results?: { id?: string; duns?: string; uei?: string; name?: string; recipient_level?: string; amount?: number; }[]; }; const body: Record<string, unknown> = { keyword: args.keyword, limit: args.limit ?? 10, page: 1, }; if (args.recipientLevel) { body.recipient_level = args.recipientLevel; } const json = await postUsas<Resp>("recipient/", body); return { totalRecords: json.page_metadata?.total ?? 0, recipients: (json.results ?? []).map((r) => ({ id: r.id ?? "", duns: r.duns, uei: r.uei, name: r.name ?? "", level: r.recipient_level, totalAmount: r.amount ?? 0, })), }; } - src/server.ts:175-182 (schema)Zod input schema 'UsasSearchRecipientsInput' defining the tool's inputs: keyword (string, required), recipientLevel (enum P/C/R, optional), and limit (number, optional).
const UsasSearchRecipientsInput = z.object({ keyword: z.string(), recipientLevel: z .enum(["P", "C", "R"]) .optional() .describe("P=parent, C=child, R=recipient"), limit: z.number().min(1).max(50).optional(), }); - src/server.ts:427-432 (registration)Tool registration/definition in the tools array: name 'usas_search_recipients', description, and inputSchema reference.
{ name: "usas_search_recipients", description: "Search USAspending recipient list with parent/child/recipient hierarchy. Returns recipients with id, duns, uei, level (P=parent, C=child, R=recipient), total_amount. Use for 'find the recipient_id for Booz Allen' before usas_get_recipient_profile.", inputSchema: UsasSearchRecipientsInput, }, - src/server.ts:747-748 (registration)Dispatch case in the CallToolRequestSchema handler: maps 'usas_search_recipients' to usas.searchRecipients() with parsed input.
case "usas_search_recipients": return await usas.searchRecipients(UsasSearchRecipientsInput.parse(args));