Nass

Nass Query

nass_query

Read-onlyIdempotent

Search USDA agricultural statistics by commodity, statistic, geography, and year. Returns production, yield, acreage, prices, and livestock data (e.g., commodity="CORN", state_fips="06" for California).

Input Schema

Name	Required	Description
`freq`	No	Frequency: "ANNUAL", "MONTHLY", or "WEEKLY" (optional)
`year`	No	Year or range, e.g., "2024" or "2020:2025" (optional)
`group`	No	Commodity group, e.g., "FIELD CROPS", "FRUIT & TREE NUTS", "VEGETABLES" (optional)
`state`	No	State name, e.g., "IOWA", "ILLINOIS", "CALIFORNIA" (optional)
`sector`	No	Sector: "CROPS", "ANIMALS & PRODUCTS", "ECONOMICS", "DEMOGRAPHICS", "ENVIRONMENTAL" (optional)
`source`	No	Data source: "SURVEY" or "CENSUS" (optional, defaults to all)
`_apiKey`	Yes	NASS API key (free from quickstats.nass.usda.gov/api)
`agg_level`	No	Aggregation level: "NATIONAL", "STATE", or "COUNTY" (optional)
`commodity`	Yes	Commodity name, e.g., "CORN", "SOYBEANS", "WHEAT", "CATTLE", "MILK", "COTTON"
`stat_category`	No	Statistic category, e.g., "YIELD", "PRODUCTION", "AREA PLANTED", "AREA HARVESTED", "PRICE RECEIVED", "INVENTORY"

Output Schema

Name	Required	Description
`data`	Yes	Array of up to 200 agricultural records
`count`	Yes	Number of records returned
`truncated`	Yes	True if results exceed 200 records and were truncated

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 27, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "_apiKey": "your-nass-api-key",
-    "commodity": "CORN",
-    "stat_category": "YIELD",
-    "state": "IOWA",
-    "year": "2024"
-  },
-  {
-    "_apiKey": "your-nass-api-key",
-    "agg_level": "NATIONAL",
-    "commodity": "SOYBEANS",
-    "stat_category": "PRODUCTION",
-    "year": "2020:2025"
-  }
-]New value: +[
+  {
+    "commodity": "CORN",
+    "stat_category": "YIELD",
+    "state": "IOWA",
+    "year": "2024"
+  },
+  {
+    "agg_level": "NATIONAL",
+    "commodity": "SOYBEANS",
+    "stat_category": "PRODUCTION",
+    "year": "2020:2025"
+  }
+]

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of records returned",
+      "type": "integer"
+    },
+    "data": {
+      "description": "Array of up to 200 agricultural records",
+      "items": {
+        "properties": {
+          "agg_level": {
+            "description": "Aggregation level (NATIONAL, STATE, COUNTY)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "commodity": {
+            "description": "Commodity name (e.g., CORN, SOYBEANS)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "county": {
+            "description": "County name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "description": {
+            "description": "Short description of the statistic",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "frequency": {
+            "description": "Frequency (ANNUAL, MONTHLY, WEEKLY)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "period": {
+            "description": "Reference period description",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "stat_category": {
+            "description": "Statistical category (e.g., YIELD, PRODUCTION)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "state": {
+            "description": "State name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "unit": {
+            "description": "Unit of measurement",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "value": {
+            "description": "Numeric or categorical value",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "year": {
+            "description": "Year of the record",
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "truncated": {
+      "description": "True if results exceed 200 records and were truncated",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "count",
+    "data",
+    "truncated"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "_apiKey": "your-nass-api-key",
+    "commodity": "CORN",
+    "stat_category": "YIELD",
+    "state": "IOWA",
+    "year": "2024"
+  },
+  {
+    "_apiKey": "your-nass-api-key",
+    "agg_level": "NATIONAL",
+    "commodity": "SOYBEANS",
+    "stat_category": "PRODUCTION",
+    "year": "2020:2025"
+  }
+]

First observedApr 22, 2026

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds the data-type scope of the response and a usage example, but it does not disclose rate limits, empty-result behavior for invalid parameter combinations, or data freshness. Shows no contradiction with the 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 description is compact (~30 words), front-loaded with the core purpose, and contains no filler. The inline parenthetical example is grammatically clunky and cites a non-existent parameter, a minor structural blemish in an otherwise tight definition.

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

Completeness3/5

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

For a 10-parameter tool with no enums, the 100%-documented schema plus examples and an output schema carry much of the load. However, the description adds no guidance on the general-vs-specialized sibling decision, does not warn that not every commodity supports every stat_category, and its sole example is not directly callable as written — a meaningful gap at this complexity level.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3 and the description is not obligated to repeat parameter meaning. Its one attempt to add value, the example 'commodity="CORN", state_fips="06"', references a parameter ('state_fips') that does not exist in the schema — the actual field is 'state' (a state name) — which slightly erodes the contribution.

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 description states a specific verb and resource ('Search USDA agricultural statistics'), scopes by commodity, statistic, geography, and year, and enumerates the return data types (production, yield, acreage, prices, livestock). It stops short of a 5 because it does not explicitly differentiate from the four overlapping NASS siblings (nass_prices, nass_livestock, nass_crop_production, nass_crop_progress), which cover exactly the data types this description lists.

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

Usage Guidelines2/5

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

There is no guidance on when to use this general query tool versus the specialized NASS siblings, no exclusions, and no mention of alternatives. Given the sibling set contains multiple tools that retrieve the same data types, an agent has no basis for choosing between nass_query and nass_prices or nass_livestock.

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

All Nass 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.