USASpending.gov

spending_over_time

Read-only

Aggregate spending amounts over time, grouped by fiscal year, quarter, or month.

Use this to visualize spending trends, identify fiscal-year-end spikes,
or compare spending patterns across years.

Note: The API returns fiscal_year as a STRING. Cast to int for numeric
comparisons. quarter and month are FISCAL periods (month 1 = October,
quarter 1 = October-December). Buckets are clipped to the window, so a
calendar-2025 window returns a partial fiscal_year '2025' (January-
September only) and a partial '2026' (October-December); neither is
that whole fiscal year.

DoD contract actions are published 90 days late, so when the window
reaches into the last 90 days and DoD is in scope the answer carries a
data_note: those months are understated, so don't read them as a drop.

awarding_agency must be a TOPTIER agency name ('Department of Defense').
Military departments are subtiers: pass
awarding_subagency='Department of the Navy'. A non-toptier name in
awarding_agency (or a subagency that does not belong to the given
toptier) silently returns all-zero aggregates.

At least one filter is required (the API rejects empty filter sets with HTTP 400).
Typical usage: pass time_period_start + time_period_end.

date_type controls the transaction date window. Omitted (the default)
or 'action_date', it selects transaction actions inside the window.
'date_signed' selects the associated award's first signing date;
'last_modified_date' selects transaction update dates. 'new_awards_only'
retains in-window actions associated with awards first signed in the
window. These are transaction obligation totals, not new-award counts:
use new_awards_over_time for counts. Award search/count tools use a
different default interval-overlap rule.
date_type needs time_period_start and/or time_period_end.

program_numbers filters assistance awards by assistance listing (CFDA)
number, e.g. ['93.778'] for Medicaid; use it with award_type='grants',
'loans', 'direct_payments', or 'other'. autocomplete_cfda() finds numbers
by program name.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "spending_over_time"
  }
}

Input Schema

Name	Required	Default
`group`	No	fiscal_year
`keywords`	No
`date_type`	No
`def_codes`	No
`psc_codes`	No
`award_type`	No
`naics_codes`	No
`funding_agency`	No
`recipient_name`	No
`awarding_agency`	No
`program_numbers`	No
`time_period_end`	No
`time_period_start`	No
`awarding_subagency`	No
`extent_competed_type_codes`	No
`contract_pricing_type_codes`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 21, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the readOnly/openWorld annotations: discloses that fiscal_year is a string, that quarter/month are fiscal periods offset from October, that buckets are clipped to the window, that DoD has a 90-day publication lag surfaced via data_note, and that a non-toptier awarding_agency silently returns all-zero aggregates. This is exactly the kind of silent-failure context an agent cannot get from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose then usage then caveats, and virtually every sentence carries operational information. It is long, but the length is driven by genuinely non-obvious API behavior rather than padding; the agent-facing warnings could be grouped more tightly, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter aggregation tool with an output schema (so return values needn't be described), the description covers the traps that would cause wrong answers: fiscal-vs-calendar period confusion, clipped partial years, silently empty agency filters, and lagged DoD data. Nothing critical to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the load; it does so for the highest-risk parameters (date_type with all four modes and its dependency on time_period_start/end, awarding_agency vs awarding_subagency hierarchy, program_numbers with a concrete CFDA example and required award_type pairing, group). It leaves roughly half the filter parameters (def_codes, psc_codes, naics_codes, extent_competed_type_codes, contract_pricing_type_codes, keywords, funding_agency, recipient_name) with no explanation beyond their names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb + resource + grouping axis ('Aggregate spending amounts over time, grouped by fiscal year, quarter, or month'), which immediately distinguishes it from siblings like spending_by_category or spending_by_geography. The description also names the sibling it is not (new_awards_over_time) for the count case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use scenarios ('visualize spending trends, identify fiscal-year-end spikes, compare across years'), names the alternative for counts ('use new_awards_over_time for counts'), states the minimum viable call ('pass time_period_start + time_period_end'), and warns that empty filter sets get HTTP 400.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All USASpending.gov tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.