usas_search_subawards

Instructions

Implementation Reference

• src/server.ts:349-353 (registration)

  Tool registration for 'usas_search_subawards' in the TOOLS array. Defines name, description (enumerate subcontracts on prime awards), and associates it with UsasSubawardsInput schema.

  {
    name: "usas_search_subawards",
    description:
      "Enumerate subcontracts on prime awards. Use for 'who teams with Leidos at DISA' or 'show small-business subs on Accenture's DHS contracts' — surfaces the prime/sub network for teaming-map artifacts.",
    inputSchema: UsasSubawardsInput,

• src/server.ts:104-110 (schema)

  Zod input schema UsasSubawardsInput — validates primeRecipientName, agency, naics, fiscalYear, and limit (1-50).

  const UsasSubawardsInput = z.object({
    primeRecipientName: z.string().optional(),
    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:231-273 (handler)

  searchSubawards() — the actual tool handler. Builds filters from args, adds recipient_search_text if primeRecipientName is provided, then POSTs to 'search/spending_by_award' with subawards:true. Maps results to subAwardId, subRecipient, amount, actionDate, primeAwardId.

  export async function searchSubawards(args: {
    primeRecipientName?: string;
    agency?: string;
    naics?: string;
    fiscalYear?: number;
    limit?: number;
  }) {
    const filters = buildFilters(args);
    if (args.primeRecipientName) {
      filters.recipient_search_text = [args.primeRecipientName];
    }
    type Resp = {
      results?: {
        "Sub-Award ID"?: string;
        "Sub-Award Recipient"?: string;
        "Sub-Award Amount"?: number;
        "Sub-Award Date"?: string;
        prime_award_generated_internal_id?: string;
      }[];
    };
    const json = await postUsas<Resp>("search/spending_by_award", {
      filters,
      fields: [
        "Sub-Award ID",
        "Sub-Award Recipient",
        "Sub-Award Amount",
        "Sub-Award Date",
        "Sub-Award NAICS",
      ],
      limit: args.limit ?? 15,
      page: 1,
      subawards: true,
    });
    return {
      subawards: (json.results ?? []).map((r) => ({
        subAwardId: r["Sub-Award ID"] ?? "",
        subRecipient: r["Sub-Award Recipient"] ?? "(name redacted)",
        amount: r["Sub-Award Amount"] ?? 0,
        actionDate: r["Sub-Award Date"] ?? "",
        primeAwardId: r.prime_award_generated_internal_id ?? "",
      })),
    };
  }

• src/server.ts:699-700 (registration)

  Case branch in runTool() switch — dispatches 'usas_search_subawards' to usas.searchSubawards() after parsing args with UsasSubawardsInput.

  case "usas_search_subawards":
    return await usas.searchSubawards(UsasSubawardsInput.parse(args));

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

  buildFilters() helper — constructs USAspending API filters from agency, naics, fiscalYear. Used by searchSubawards as the base filter object.

  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;
  }