Census Trade

Census Imports

census_imports

Read-onlyIdempotent

Search US import data by HS commodity code and/or country. Returns import values, quantities, and commodity details. Pass country as a plain English name (e.g. "China"). Omit hs_code for total imports from a country; omit country for all countries combined.

Input Schema

TableJSON Schema

Name	Required	Description
`year`	Yes	Trade year (e.g., "2024")
`limit`	No	Maximum number of records to return (default 20)
`month`	No	Trade month 01-12 (e.g., "06" for June). Optional — omit for annual data.
`country`	No	Country name in plain English (e.g., "Mexico", "South Korea", "European Union"). Preferred over country_code — this is resolved for you. Optional — omit for all countries combined.
`hs_code`	No	HS commodity code at 2, 4, or 6 digit level (e.g., "8471" for computers, "87" for vehicles). Optional — omit for total imports across all commodities.
`country_code`	No	Census Schedule C country code if you already have one (e.g., "5700" China, "2010" Mexico). NOT an ISO code — "MX" and "CN" will not work. Prefer `country` and pass a name instead. Optional.

Output Schema

TableJSON Schema

Name	Required	Description
`type`	Yes	Trade direction indicator
`count`	Yes	Number of records returned
`period`	Yes	Trade period (year or year-month)
`hs_code`	Yes	HS commodity code queried
`records`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedAug 1, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "hs_code": "8471",
-    "year": "2024"
-  },
-  {
-    "country_code": "5700",
-    "hs_code": "87",
-    "limit": 50,
-    "month": "06",
-    "year": "2023"
-  }
-]New value: +[
+  {
+    "country": "European Union",
+    "hs_code": "30",
+    "year": "2024"
+  },
+  {
+    "hs_code": "8471",
+    "year": "2024"
+  },
+  {
+    "country_code": "5700",
+    "hs_code": "87",
+    "limit": 50,
+    "month": "06",
+    "year": "2023"
+  }
+]

addedInput schema / properties / country

Added value: +{
+  "description": "Country name in plain English (e.g., \"Mexico\", \"South Korea\", \"European Union\"). Preferred over country_code — this is resolved for you. Optional — omit for all countries combined.",
+  "type": "string"
+}

changedInput schema / properties / country_code / description

Previous value: -"Census country code (e.g., \"5700\" for China, \"2010\" for Mexico). Optional — omit for all countries."New value: +"Census Schedule C country code if you already have one (e.g., \"5700\" China, \"2010\" Mexico). NOT an ISO code — \"MX\" and \"CN\" will not work. Prefer `country` and pass a name instead. Optional."

Changed2 schema fields changedAug 1, 2026

changedInput schema / properties / hs_code / description

Previous value: -"HS commodity code at 2, 4, or 6 digit level (e.g., \"8471\" for computers, \"87\" for vehicles)"New value: +"HS commodity code at 2, 4, or 6 digit level (e.g., \"8471\" for computers, \"87\" for vehicles). Optional — omit for total imports across all commodities."

changedInput schema / required

Previous value: -[
-  "hs_code",
-  "year"
-]New value: +[
+  "year"
+]

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Number of records returned",
+      "type": "number"
+    },
+    "hs_code": {
+      "description": "HS commodity code queried",
+      "type": "string"
+    },
+    "period": {
+      "description": "Trade period (year or year-month)",
+      "type": "string"
+    },
+    "records": {
+      "items": {
+        "properties": {
+          "commodity_code": {
+            "description": "HS commodity code",
+            "type": "string"
+          },
+          "country_code": {
+            "description": "Census country code",
+            "type": "string"
+          },
+          "country_name": {
+            "description": "Country name",
+            "type": "string"
+          },
+          "import_value_usd": {
+            "description": "Import value in USD",
+            "type": "number"
+          },
+          "period": {
+            "description": "Trade period",
+            "type": "string"
+          },
+          "quantity": {
+            "description": "Import quantity",
+            "type": "number"
+          }
+        },
+        "required": [
+          "commodity_code",
+          "country_code",
+          "country_name",
+          "import_value_usd",
+          "quantity",
+          "period"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "type": {
+      "description": "Trade direction indicator",
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "hs_code",
+    "period",
+    "count",
+    "records"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "hs_code": "8471",
+    "year": "2024"
+  },
+  {
+    "country_code": "5700",
+    "hs_code": "87",
+    "limit": 50,
+    "month": "06",
+    "year": "2023"
+  }
+]

First observedApr 22, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful behavior: it returns 'import values, quantities, and commodity details,' and clarifies that country should be a plain English name. It does not cover pagination or limit defaults, but the output schema and schema descriptions fill those gaps. No contradiction with 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, front-loaded with the core purpose. The first sentence states exactly what the tool does; the second gives two critical usage examples. No fluff or redundancy.

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?

Given the annotations, output schema, and well-documented parameters, the description covers the essential search patterns. It could have mentioned month/limit filtering or noted the availability of monthly data, but these are already in the schema. The description is complete for its role of guiding initial selection and invocation.

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 description coverage is 100%, so baseline is 3. The description adds value by explaining combined vs. separate usage of hs_code and country, and clarifies the meaning of omitting each parameter. It also reinforces that country is resolved to a code, which complements the schema's caution about country_code not being ISO. This goes beyond simple property descriptions.

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 clearly states the tool's function: 'Search US import data by HS commodity code and/or country.' It identifies the specific resource (US import data), the verb (search), and the key filters. It also distinguishes from sibling tools like census_exports by focusing on imports, and from census_trade_balance/trends by offering detail-level data.

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

Usage Guidelines4/5

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

The description gives clear context on how to use the tool and different modes: 'Omit hs_code for total imports from a country; omit country for all countries combined.' It also advises on passing 'country' as plain English. However, it does not explicitly name sibling alternatives or state when to prefer census_exports or census_trade_trends, so it stops short of full exclusion 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.