usas_search_awards_by_recipient

Instructions

Implementation Reference

• src/server.ts:343-348 (registration)

  Tool registration in the TOOLS array — defines name, description, and inputSchema for 'usas_search_awards_by_recipient'.

  {
    name: "usas_search_awards_by_recipient",
    description:
      "Pull every contract a specific recipient has won within an agency × NAICS slice. Use when the user asks 'show me Booz Allen wins at VA last year' — returns line items + naicsCode + description, not aggregates.",
    inputSchema: UsasRecipientAwardsInput,
  },

• src/server.ts:96-102 (schema)

  Zod input schema UsasRecipientAwardsInput with fields: recipientName (required), agency, naics, fiscalYear, limit (optional).

  const UsasRecipientAwardsInput = z.object({
    recipientName: z.string(),
    agency: z.string().optional(),
    naics: z.string().optional(),
    fiscalYear: z.number().int().min(2007).optional(),
    limit: z.number().min(1).max(50).optional(),
  });

• src/usaspending.ts:176-227 (handler)

  Handler function searchAwardsByRecipient — posts to USAspending 'search/spending_by_award' endpoint with recipient filter, returns line items (awardId, recipient, amount, agency, NAICS, description, generatedInternalId).

  export async function searchAwardsByRecipient(args: {
    recipientName: string;
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    limit?: number;
  }) {
    const filters = buildFilters(args);
    filters.recipient_search_text = [args.recipientName];
    type Resp = {
      results?: {
        "Award ID"?: string;
        "Recipient Name"?: string;
        "Award Amount"?: number;
        "Awarding Agency"?: string;
        "Awarding Sub Agency"?: string;
        NAICS?: { code?: string; description?: 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",
        "NAICS",
        "Description",
      ],
      limit: args.limit ?? 15,
      page: 1,
      subawards: false,
    });
    const results = json.results ?? [];
    return {
      awards: 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"],
        naicsCode: r.NAICS?.code,
        naicsDescription: r.NAICS?.description,
        description: r.Description,
        generatedInternalId: r.generated_internal_id ?? "",
      })),
      totalRecords: results.length,
    };
  }

• src/server.ts:695-698 (registration)

  Tool dispatch in runTool switch statement — calls usas.searchAwardsByRecipient with parsed UsasRecipientAwardsInput.

  case "usas_search_awards_by_recipient":
    return await usas.searchAwardsByRecipient(
      UsasRecipientAwardsInput.parse(args),
    );

• src/usaspending.ts:42-67 (helper)

  Helper function buildFilters — constructs USAspending filter object from agency, naics, fiscalYear params. Used by searchAwardsByRecipient.

  function buildFilters(args: {
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    setAside?: string;
    pscCodes?: string[];
  }): UsasFilters {
    const filters: UsasFilters = { award_type_codes: ["A", "B", "C", "D"] };
    if (args.agency) {
      filters.agencies = [
        { type: "awarding", tier: "toptier", name: args.agency },
      ];
    }
    if (args.naics) filters.naics_codes = [args.naics];
    if (args.fiscalYear) {
      filters.time_period = [
        {
          start_date: `${args.fiscalYear - 1}-10-01`,
          end_date: `${args.fiscalYear}-09-30`,
        },
      ];
    }
    if (args.setAside) filters.set_aside_type_codes = [args.setAside];
    if (args.pscCodes?.length) filters.psc_codes = args.pscCodes;
    return filters;
  }