usda_nass_get_data
Fetches USDA NASS Quick Stats estimates for filtered queries. It pre-counts results and splits by year to handle data over the 50,000-record limit.
Instructions
Fetch published Quick Stats estimates for a set of filters, up to 50,000 records a call.
Without split_by_year, calls get_counts first: a count of zero returns an empty
result without a second call, and a count above 50,000 raises QueryTooLarge with
the count and a hint (narrower filters, or split_by_year) before anything is
fetched. With split_by_year, a two-sided year range is fetched year by year, each
year counted first and no count of the range sent; year__GE alone is counted
first and split by year only when that count is above 50,000; year is counted
first, and above 50,000 still raises QueryTooLarge. meta.total is the count
get_counts reported, 0 for the empty result, and the yearly counts summed for
a split. Each record carries every Quick Stats column;
value is the published figure as a string ("510,000", or a suppression code
such as "(D)") and value_number the parsed number.
Args:
filters: Quick Stats columns, optionally suffixed with an operator, mapped to
values; the same shape and the same checks as for get_counts: an
unknown value of a packaged parameter raises UnknownCode naming the
list, its fetch date and the closest known values, or pointing at
list_param_values (the tool usda_nass_list_param_values) when none
is close. A query that stays well under the limit names the commodity, the
statistic, the level and the time, e.g.
{"commodity_desc": "CORN", "statisticcat_desc": "AREA PLANTED", "agg_level_desc": "STATE", "state_alpha": "VA", "year": 2012}. Quick Stats
keeps one bound on year per query (recorded 2026-10-28): it counts
year__GE with year__LE as year__GE alone, in either order, and
drops year__GE beside year__LT, so a two-sided year range is served
only by split_by_year.
split_by_year: True fetches the years one at a time where one call cannot serve
them, splitting one call into at most 20 years in Python and over HTTP and 5 by
default on the MCP server, whose --split-years sets 1 to 20. The filters
bound the years in one of three forms, checked before any call: year
(2022), year__GE with year__LE (2020 and 2023), or
year__GE alone, up to the current UTC year. Another year filter
(year__LE alone, year__GT, year__NE, ...), a mix or none raises
InvalidRequestError naming the three forms, and a year__GE or
year__LE past the current UTC year raises it naming that year. year is
counted and fetched once, as without the flag; over the limit it raises
QueryTooLarge naming the year. year__GE with year__LE is always
split, without a count of the range, which Quick Stats would count as
year__GE alone; more years than the ceiling raise InvalidRequestError
naming it before any call. year__GE alone is counted first and fetched once
when the count is within the limit, however far back it starts; over the limit
it is split, and more years than the ceiling raise InvalidRequestError
naming it after that count, before the split. A split counts each year with
year=<y> in place of the year filters, every year before the first fetch, so
a year over 50,000 on its own raises QueryTooLarge naming it before anything
is fetched; it then fetches each year holding records, the records in year
order, each year's in upstream's order. A year counting 0 is skipped: it has no
records, or none published yet, which Quick Stats does not tell apart;
meta.vintage stays None, since Quick Stats names no release. Cost: up to
two keyed calls per year, plus the first count for year__GE alone, paced at
30 a minute, so 5 years take up to 11 calls and 20 years up to 41, about 80
seconds. meta.request carries split_by_year beside the filters.
False, the default, never splits.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"filters": "<filters>"
},
"name": "usda_nass_get_data"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | Yes | ||
| split_by_year | No |