usas_search_agency_spending

Instructions

Implementation Reference

• src/server.ts:399-404 (registration)

  Tool registration in the TOOLS array — defines the tool name, description, and input schema binding.

  {
    name: "usas_search_agency_spending",
    description:
      "Spending broken down by awarding agency. Use for 'which agencies spend the most on NAICS 541512' — top buyers by $.",
    inputSchema: UsasAgencySpendingInput,
  },

• src/server.ts:149-156 (schema)

  Input schema (Zod) for usas_search_agency_spending — accepts optional naics, fiscalYear, setAside, limit.

  const UsasAgencySpendingInput = z.object({
    naics: z.string().optional(),
    fiscalYear: z.number().int().min(2007).optional(),
    setAside: z
      .enum(["SBA", "8A", "HZS", "SDVOSBC", "WOSB", "EDWOSB", "VSA", "VSS"])
      .optional(),
    limit: z.number().min(1).max(50).optional(),
  });

• src/usaspending.ts:559-586 (handler)

  Handler function — POSTs to USAspending API v2 search/spending_by_category/awarding_agency, returns agencies sorted by total $.

  export async function searchAgencySpending(args: {
    naics?: string;
    fiscalYear?: number;
    setAside?: string;
    limit?: number;
  }) {
    const filters = buildFilters(args);
    type Resp = {
      results?: {
        name?: string;
        code?: string;
        amount?: number;
        agency_slug?: string;
      }[];
    };
    const json = await postUsas<Resp>(
      "search/spending_by_category/awarding_agency",
      { filters, limit: args.limit ?? 10, page: 1 },
    );
    return {
      agencies: (json.results ?? []).map((r) => ({
        name: r.name ?? "",
        code: r.code ?? "",
        slug: r.agency_slug ?? "",
        amount: r.amount ?? 0,
      })),
    };
  }

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

  Helper that builds the common USAspending filter object used by searchAgencySpending (and other tools) — handles agency, naics, fiscalYear, setAside.

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

• src/usaspending.ts:69-83 (helper)

  Generic HTTP POST helper for USAspending API calls with 15s timeout — used by searchAgencySpending to call the awarding_agency endpoint.

  async function postUsas<T>(
    endpoint: string,
    body: Record<string, unknown>,
  ): Promise<T> {
    const r = await fetch(`${USAS}/${endpoint}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(15_000),
    });
    if (!r.ok) {
      throw new Error(`USAspending POST ${endpoint} returned ${r.status}`);
    }
    return (await r.json()) as T;
  }