usas_search_individual_awards

Instructions

Implementation Reference

• src/usaspending.ts:125-172 (handler)

  The actual handler function `searchIndividualAwards` that executes the tool logic. It calls USAspending's `search/spending_by_award` endpoint (POST keyless) with agency/naics/fiscalYear/setAside/limit filters, then maps the response (Award ID, Recipient Name, Award Amount, etc.) into a structured result with a generatedInternalId for follow-up lookups.

  export async function searchIndividualAwards(args: {
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    setAside?: string;
    limit?: number;
  }) {
    const filters = buildFilters(args);
    type Resp = {
      results?: {
        "Award ID"?: string;
        "Recipient Name"?: string;
        "Award Amount"?: number;
        "Awarding Agency"?: string;
        "Awarding Sub Agency"?: string;
        "Place of Performance State Code"?: string;
        Description?: string;
        generated_internal_id?: string;
      }[];
    };
    const json = await postUsas<Resp>("search/spending_by_award", {
      filters,
      fields: [
        "Award ID",
        "Recipient Name",
        "Award Amount",
        "Awarding Agency",
        "Awarding Sub Agency",
        "Place of Performance State Code",
        "Description",
      ],
      limit: args.limit ?? 10,
      page: 1,
      subawards: false,
    });
    return {
      awards: (json.results ?? []).map((r) => ({
        awardId: r["Award ID"] ?? "",
        recipient: r["Recipient Name"] ?? "",
        amount: r["Award Amount"] ?? 0,
        awardingAgency: r["Awarding Agency"] ?? "",
        awardingSubAgency: r["Awarding Sub Agency"],
        placeOfPerformanceState: r["Place of Performance State Code"],
        description: r.Description,
        generatedInternalId: r.generated_internal_id ?? "",
      })),
    };
  }

• src/server.ts:685-689 (handler)

  The `runTool` switch-case that dispatches `usas_search_individual_awards` to `usas.searchIndividualAwards()` with parsed `UsasIndividualAwardsInput` arguments.

  case "usas_search_individual_awards":
    return await usas.searchIndividualAwards(
      UsasIndividualAwardsInput.parse(args),
    );
  case "usas_search_subagency_spending":

• src/server.ts:83-85 (schema)

  Input schema `UsasIndividualAwardsInput` extending `UsasFiltersBase` with an optional `limit` (1-50). Defines the shape of arguments the tool accepts: agency, naics, fiscalYear, setAside, and limit.

  const UsasIndividualAwardsInput = UsasFiltersBase.extend({
    limit: z.number().min(1).max(50).optional(),
  });

• src/server.ts:74-81 (schema)

  Base schema `UsasFiltersBase` used by `UsasIndividualAwardsInput`. Defines agency (string), naics (string), fiscalYear (int 2007+), and setAside (enum of SBA/8A/HZS/SDVOSBC/WOSB/EDWOSB/VSA/VSS) fields.

  const UsasFiltersBase = z.object({
    agency: z.string().optional().describe("Canonical agency name"),
    naics: z.string().optional(),
    fiscalYear: z.number().int().min(2007).optional(),
    setAside: z
      .enum(["SBA", "8A", "HZS", "SDVOSBC", "WOSB", "EDWOSB", "VSA", "VSS"])
      .optional(),
  });

• src/server.ts:325-330 (registration)

  Tool registration entry in the `TOOLS` array: defines the name `usas_search_individual_awards`, description, and links to its input schema.

  {
    name: "usas_search_individual_awards",
    description:
      "Line-item federal contracts on USAspending. Returns specific awards (recipient + $ + sub-agency + state + description). Use AFTER usas_search_awards when the user wants 'show me the actual contracts'. Each result includes a generatedInternalId for usas_get_award_detail follow-ups.",
    inputSchema: UsasIndividualAwardsInput,
  },