xippios-mcp

Overview Schema Source Related Servers Discussions Admin

usda_nass_get_grain_stocks

Read-onlyIdempotent

Retrieve quarterly on-farm, off-farm, and total grain stocks in bushels by commodity and year for national or state estimates.

Instructions

Quarterly grain stocks of a commodity in a year, on farm, off farm and in total, in bushels.

The NASS Grain Stocks estimates (statisticcat_desc STOCKS, unit_desc BU, domain_desc TOTAL, freq_desc POINT IN TIME, source_desc SURVEY), state or national, every stocks day of the year together: one row per day, position and class, sorted by day (begin_code, then reference_period_desc), then util_practice_desc, then class_desc. reference_period_desc names the day, FIRST OF MAR, FIRST OF JUN, FIRST OF SEP or FIRST OF DEC, and begin_code its month (03 ... 12). util_practice_desc tells the position as upstream spells it for the commodity: for corn GRAIN (the total), ON FARM, GRAIN and OFF FARM, GRAIN; for soybeans and wheat ALL UTILIZATION PRACTICES (the total), ON FARM and OFF FARM. class_desc is ALL CLASSES; wheat's durum comes as rows of its own, class_desc SPRING, DURUM, where NASS publishes it, as in the national estimates. value is the quantity in bushels as published and value_number its parsed form.

Args: commodity: Upstream commodity_desc, e.g. "CORN", "SOYBEANS", "WHEAT"; list_param_values("commodity_desc") lists them. year: Year of the stocks days, e.g. 2024 for the stocks on 1 March, 1 June, 1 September and 1 December 2024; the current year returns only the stocks days published so far. state: Two-letter state code for the state estimates, e.g. "IA", "ND"; None returns the national US TOTAL estimates.

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": {
      "commodity": "<commodity>",
      "year": "<year>"
    },
    "name": "usda_nass_get_grain_stocks"
  }
}

Input Schema

Name	Required	Description	Default
`year`	Yes
`state`	No
`commodity`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 12, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent, open-world and non-destructive, but the description goes well beyond them: it discloses the exact row grain (one row per day/position/class), the sort order (begin_code, reference_period_desc, util_practice_desc, class_desc), the meaning of reference_period_desc and begin_code values, and that value/value_number are the raw and parsed quantities. It also discloses that the current year returns only stocks days published so far, which is behavior an agent could not infer 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?

The purpose leads the description, followed by a dense but information-bearing block on row structure and then a clean Args section. The middle paragraph is heavy with backticked NASS codes and parenthetical enumerations, which makes it slow to read, but almost every clause carries data the agent needs given the absence of an output schema.

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

Completeness4/5

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

With no output schema, the description must explain return shape, and it does so thoroughly (columns, grain, sorting, units). All three parameters are documented despite zero schema coverage. The one gap is comparative guidance against sibling retrieval tools, which keeps it short of full completeness.

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

Parameters5/5

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

Schema coverage is 0%, so the description carries the full burden, and it does: commodity is tied to upstream commodity_desc with concrete examples and a discovery path, year is explained with a concrete example and the partial-current-year caveat, and state is documented as a two-letter code with None meaning national US TOTAL. This resolves exactly the ambiguities the bare schema leaves open.

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

Purpose4/5

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

The opening sentence names a specific verb and resource with scope: quarterly grain stocks for a commodity in a year, split on-farm/off-farm/total, in bushels. It distinguishes itself from siblings such as get_production or get_data by naming the exact NASS filters (statisticcat_desc STOCKS, unit_desc BU, freq_desc POINT IN TIME), though it never routes the agent away from those siblings explicitly.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the agent learns what data to expect and is told list_param_values("commodity_desc") enumerates valid commodities. There is no explicit when-to-use-this vs. when-to-use-get_data or get_production guidance, and no prerequisites or exclusions, so the agent must infer the choice from the filter codes.

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

Deploy Server