usas_get_agency_budget_function
Retrieve a federal agency's budget breakdown by program area for a specified fiscal year using its toptier code, showing spending amounts per program.
Instructions
Budget function breakdown for an agency × fiscal year. Returns the agency's spending by program area (e.g. VA: 'Income security for veterans' $204B, 'Hospital and medical care for veterans' $126B).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| toptierCode | Yes | 3-4 digit toptier code from usas_lookup_agency (e.g. '036' for VA) | |
| fiscalYear | No | ||
| limit | No |
Implementation Reference
- src/usaspending.ts:661-694 (handler)Core handler function `getAgencyBudgetFunction` that calls the USAspending API endpoint `agency/{toptier_code}/budget_function/` and returns budget function breakdown with programs (name, obligated amount, outlays).
export async function getAgencyBudgetFunction(args: { toptierCode: string; fiscalYear?: number; limit?: number; }) { const fy = args.fiscalYear ?? new Date().getUTCFullYear(); type Resp = { toptier_code?: string; fiscal_year?: number; results?: { name?: string; children?: { name?: string; obligated_amount?: number; gross_outlay_amount?: number; }[]; }[]; }; const json = await getUsas<Resp>( `agency/${args.toptierCode}/budget_function/?fiscal_year=${fy}&limit=${args.limit ?? 10}`, ); return { toptierCode: json.toptier_code, fiscalYear: json.fiscal_year, functions: (json.results ?? []).map((r) => ({ name: r.name ?? "", programs: (r.children ?? []).map((c) => ({ name: c.name ?? "", obligated: c.obligated_amount ?? 0, outlays: c.gross_outlay_amount ?? 0, })), })), }; } - src/server.ts:170-173 (schema)Input schema `UsasAgencyBudgetInput` extending agency profile input with optional fiscalYear (min 2007) and limit (1-20).
const UsasAgencyBudgetInput = UsasAgencyProfileInput.extend({ fiscalYear: z.number().int().min(2007).optional(), limit: z.number().min(1).max(20).optional(), }); - src/server.ts:419-424 (registration)Tool registration in the tools array: name 'usas_get_agency_budget_function', description explaining it returns budget function breakdown by program area.
{ name: "usas_get_agency_budget_function", description: "Budget function breakdown for an agency × fiscal year. Returns the agency's spending by program area (e.g. VA: 'Income security for veterans' $204B, 'Hospital and medical care for veterans' $126B).", inputSchema: UsasAgencyBudgetInput, }, - src/server.ts:741-744 (registration)Handler dispatch case in the main switch statement: parses args with UsasAgencyBudgetInput and delegates to usas.getAgencyBudgetFunction.
case "usas_get_agency_budget_function": return await usas.getAgencyBudgetFunction( UsasAgencyBudgetInput.parse(args), ); - dist/usaspending.d.ts:257-272 (helper)TypeScript type declaration for getAgencyBudgetFunction showing return type: {toptierCode, fiscalYear, functions: {name, programs: {name, obligated, outlays}[]}[]}.
export declare function getAgencyBudgetFunction(args: { toptierCode: string; fiscalYear?: number; limit?: number; }): Promise<{ toptierCode: string | undefined; fiscalYear: number | undefined; functions: { name: string; programs: { name: string; obligated: number; outlays: number; }[]; }[]; }>;