Census Trade

Census Trade Trends

census_trade_trends

Read-onlyIdempotent

Monthly US trade trends with ONE trading partner — month-by-month imports and exports for a country, optionally narrowed to an HS commodity, to show seasonality and shifts. A country is required: an unfiltered monthly query spans every partner and the Census API cannot return it in time. For all-countries totals use census_imports / census_exports instead.

Input Schema

TableJSON Schema

Name	Required	Description
`country`	No	Country name in plain English (e.g., "Mexico"). Preferred — resolved for you. REQUIRED unless you pass country_code.
`hs_code`	No	HS commodity code. Optional — omit for aggregate trade.
`end_year`	No	End year (e.g., "2024"). Optional — defaults to the last fully-published year (last calendar year; Census publishes on a lag).
`start_year`	No	Start year (e.g., "2022"). Optional — defaults to the same year as end_year, i.e. a single year. Maximum span 3 years.
`country_code`	No	Census Schedule C country code (e.g. "5700" China, "2010" Mexico). NOT an ISO code. Prefer `country`. Satisfies the country requirement.

Output Schema

TableJSON Schema

Name	Required	Description
`months`	Yes	Number of monthly data points
`trends`	Yes
`country`	Yes	Resolved country name as Census reports it, or 'all' for all countries
`hs_code`	Yes	HS commodity code or 'all' for aggregate
`end_year`	Yes	End year of trend range
`start_year`	Yes	Start year of trend range
`country_code`	Yes	Census country code or 'all' for all countries

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedAug 27, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "end_year": "2024",
-    "start_year": "2022"
-  },
-  {
-    "country_code": "5700",
-    "end_year": "2024",
-    "hs_code": "8471",
-    "start_year": "2021"
-  }
-]New value: +[
+  {
+    "country": "China",
+    "end_year": "2024",
+    "start_year": "2024"
+  },
+  {
+    "country": "China",
+    "end_year": "2025",
+    "hs_code": "85",
+    "start_year": "2025"
+  }
+]

changedInput schema / properties / country / description

Previous value: -"Country name in plain English (e.g., \"Mexico\"). Preferred — resolved for you. Optional — omit for all countries."New value: +"Country name in plain English (e.g., \"Mexico\"). Preferred — resolved for you. REQUIRED unless you pass country_code."

changedInput schema / properties / country_code / description

Previous value: -"Census Schedule C country code. NOT an ISO code. Prefer `country`. Optional."New value: +"Census Schedule C country code (e.g. \"5700\" China, \"2010\" Mexico). NOT an ISO code. Prefer `country`. Satisfies the country requirement."

changedInput schema / properties / end_year / description

Previous value: -"End year (e.g., \"2024\"). Optional — defaults to the last fully-published year if omitted."New value: +"End year (e.g., \"2024\"). Optional — defaults to the last fully-published year (last calendar year; Census publishes on a lag)."

changedInput schema / properties / start_year / description

Previous value: -"Start year (e.g., \"2022\"). Optional — defaults to a 3-year window ending at the last fully-published year if omitted."New value: +"Start year (e.g., \"2022\"). Optional — defaults to the same year as end_year, i.e. a single year. Maximum span 3 years."

Changed2 schema fields changedAug 13, 2026

addedOutput schema / properties / country

Added value: +{
+  "description": "Resolved country name as Census reports it, or 'all' for all countries",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "start_year",
-  "end_year",
-  "hs_code",
-  "country_code",
-  "months",
-  "trends"
-]New value: +[
+  "start_year",
+  "end_year",
+  "hs_code",
+  "country",
+  "country_code",
+  "months",
+  "trends"
+]

Changed3 schema fields changedAug 6, 2026

changedInput schema / properties / end_year / description

Previous value: -"End year (e.g., \"2024\")"New value: +"End year (e.g., \"2024\"). Optional — defaults to the last fully-published year if omitted."

changedInput schema / properties / start_year / description

Previous value: -"Start year (e.g., \"2022\")"New value: +"Start year (e.g., \"2022\"). Optional — defaults to a 3-year window ending at the last fully-published year if omitted."

changedInput schema / required

Previous value: -[
-  "start_year",
-  "end_year"
-]New value: +[]

Changed2 schema fields changedAug 1, 2026

addedInput schema / properties / country

Added value: +{
+  "description": "Country name in plain English (e.g., \"Mexico\"). Preferred — resolved for you. Optional — omit for all countries.",
+  "type": "string"
+}

changedInput schema / properties / country_code / description

Previous value: -"Census country code. Optional — omit for all countries."New value: +"Census Schedule C country code. NOT an ISO code. Prefer `country`. Optional."

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "country_code": {
+      "description": "Census country code or 'all' for all countries",
+      "type": "string"
+    },
+    "end_year": {
+      "description": "End year of trend range",
+      "type": "string"
+    },
+    "hs_code": {
+      "description": "HS commodity code or 'all' for aggregate",
+      "type": "string"
+    },
+    "months": {
+      "description": "Number of monthly data points",
+      "type": "number"
+    },
+    "start_year": {
+      "description": "Start year of trend range",
+      "type": "string"
+    },
+    "trends": {
+      "items": {
+        "properties": {
+          "balance_usd": {
+            "description": "Trade balance in USD for period",
+            "type": "number"
+          },
+          "exports_usd": {
+            "description": "Export value in USD for period",
+            "type": "number"
+          },
+          "imports_usd": {
+            "description": "Import value in USD for period",
+            "type": "number"
+          },
+          "period": {
+            "description": "Month-year period",
+            "type": "string"
+          }
+        },
+        "required": [
+          "period",
+          "imports_usd",
+          "exports_usd",
+          "balance_usd"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "start_year",
+    "end_year",
+    "hs_code",
+    "country_code",
+    "months",
+    "trends"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "end_year": "2024",
+    "start_year": "2022"
+  },
+  {
+    "country_code": "5700",
+    "end_year": "2024",
+    "hs_code": "8471",
+    "start_year": "2021"
+  }
+]

First observedApr 22, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations: the performance constraint that an unfiltered monthly query spans every partner and cannot return in time, plus the month-by-month granularity. It does not contradict 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.

Conciseness5/5

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

Two sentences carry all essential information with no filler. The primary scope, the required-country constraint, and the sibling alternatives are front-loaded and clearly stated.

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 tool with an output schema and a full input schema, the description covers the essential operational context: single-partner scope, optional HS narrowing, the performance reason for the country requirement, and the correct alternative for broader queries. Nothing important is missing.

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 coverage is 100%, so the schema already documents all five parameters. The description reinforces the country requirement and explains the HS narrowing's purpose, but it does not add substantial per-parameter detail beyond what the schema provides. Baseline 3 is appropriate.

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?

The description uses a specific verb+resource: it reports monthly US trade trends for one partner, with imports/exports and optional HS narrowing. It clearly distinguishes itself from census_imports/census_exports by stating the one-partner scope, so an agent can select it correctly without opening the schema.

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?

The description explicitly explains when to use this tool: when analyzing a single trading partner, and warns that a country is required because an unfiltered query cannot complete. It also names the alternatives for all-countries totals: 'use census_imports / census_exports instead.' This is clear routing guidance.

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

All Census Trade 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.