usas_get_award_detail

Instructions

Implementation Reference

• src/usaspending.ts:280-336 (handler)

  The actual handler function for usas_get_award_detail. Calls the USAspending awards/{generated_internal_id} API endpoint and returns full award detail including period_of_performance, base_and_all_options, set-aside type, competition extent, and number_of_offers.

  export async function getAwardDetail(generatedInternalId: string) {
    try {
      const r = await fetch(
        `${USAS}/awards/${encodeURIComponent(generatedInternalId)}/`,
        { signal: AbortSignal.timeout(10_000) },
      );
      if (!r.ok) return null;
      type Resp = {
        piid?: string;
        description?: string;
        total_obligation?: number;
        base_and_all_options?: number;
        period_of_performance?: {
          start_date?: string;
          end_date?: string;
          potential_end_date?: string;
        };
        latest_transaction_contract_data?: {
          type_set_aside?: string;
          type_set_aside_description?: string;
          extent_competed?: string;
          number_of_offers_received?: string;
          naics?: string;
          naics_description?: string;
        };
        awarding_agency?: {
          toptier_agency?: { name?: string };
          subtier_agency?: { name?: string };
        };
        recipient?: { recipient_name?: string };
      };
      const json = (await r.json()) as Resp;
      const ltc = json.latest_transaction_contract_data ?? {};
      return {
        awardId: json.piid ?? "",
        recipient: json.recipient?.recipient_name ?? "",
        totalObligation: json.total_obligation ?? 0,
        baseAndAllOptions: json.base_and_all_options ?? 0,
        periodOfPerformance: {
          startDate: json.period_of_performance?.start_date ?? null,
          endDate: json.period_of_performance?.end_date ?? null,
          potentialEndDate: json.period_of_performance?.potential_end_date ?? null,
        },
        description: json.description ?? "",
        setAsideType: ltc.type_set_aside,
        setAsideDescription: ltc.type_set_aside_description,
        competitionExtent: ltc.extent_competed,
        numberOfOffers: ltc.number_of_offers_received,
        awardingAgency: json.awarding_agency?.toptier_agency?.name,
        awardingSubAgency: json.awarding_agency?.subtier_agency?.name,
        naicsCode: ltc.naics,
        naicsDescription: ltc.naics_description,
      };
    } catch {
      return null;
    }
  }

• src/server.ts:122-126 (schema)

  Zod input schema for usas_get_award_detail. Defines the 'generatedInternalId' parameter (string, described as coming from spending_by_award results, e.g. CONT_AWD_*).

  const UsasAwardDetailInput = z.object({
    generatedInternalId: z
      .string()
      .describe("From spending_by_award results — e.g. CONT_AWD_*"),
  });

• src/server.ts:712-715 (registration)

  Tool registration in the runTool switch statement. Parses the input with UsasAwardDetailInput and calls usas.getAwardDetail().

  case "usas_get_award_detail":
    return await usas.getAwardDetail(
      UsasAwardDetailInput.parse(args).generatedInternalId,
    );

• src/server.ts:362-367 (registration)

  Tool definition entry in the TOOLS array listing usas_get_award_detail with its description and inputSchema reference.

  {
    name: "usas_get_award_detail",
    description:
      "Fetch full detail for a single award by generatedInternalId (from usas_search_individual_awards). Returns period_of_performance (start/end/potential_end), base_and_all_options, set-aside type, competition extent, number_of_offers — the per-award fields the search endpoint omits.",
    inputSchema: UsasAwardDetailInput,
  },