un-comtrade-mcp-server

Search Commodity Codes

comtrade_search_commodities

Read-only

Find HS or SITC commodity codes by keyword, partial description, or code prefix in the selected classification. Returns descriptions, native aggregation levels, parents, leaf status, and recommendedQueryCode for subsequent trade queries. HS uses levels 2 (chapter), 4 (heading), and 6 (subheading); SITC uses levels 1–5. Select the edition matching the trade records when interpreting historical codes.

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of results to return; above 200 returns all matching codes.
`query`	Yes	Keyword, partial description, or commodity code prefix. Examples: "motor vehicles", "8471", "coffee", "84" (HS chapter 84 = machinery).
`aggr_level`	No	Native aggregation level: HS uses 2 (chapter), 4 (heading), 6 (subheading); SITC uses 1–5. Omit to return all matching levels.
`classification`	No	Goods reference catalog: HS uses the default HS.json discovery catalog, whose total identifies H6; it is not an authoritative historical-edition reference. Select H0–H6 for an explicit HS edition, or SS/S1–S4 for SITC.	HS

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of codes returned in this response.
`notice`	No	Recovery hint when no matches are found or results are truncated. Absent when results are non-empty and not truncated.
`matches`	No	Commodity codes matching the query in the selected classification.
`truncated`	No	True when matches were capped at the limit (totalMatches exceeds shown).
`totalMatches`	No	Total matching codes (before limit truncation).
`classification`	No	Reference catalog used for the search.

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedNov 3, 2026

changedInput schema / properties / aggr_level / anyOf

Previous value: -[
-  {
-    "const": 2,
-    "type": "number"
-  },
-  {
-    "const": 4,
-    "type": "number"
-  },
-  {
-    "const": 6,
-    "type": "number"
-  }
-]New value: +[
+  {
+    "const": 1,
+    "type": "number"
+  },
+  {
+    "const": 2,
+    "type": "number"
+  },
+  {
+    "const": 3,
+    "type": "number"
+  },
+  {
+    "const": 4,
+    "type": "number"
+  },
+  {
+    "const": 5,
+    "type": "number"
+  },
+  {
+    "const": 6,
+    "type": "number"
+  }
+]

changedInput schema / properties / aggr_level / description

Previous value: -"Aggregation level: 2 = HS chapter (most general), 4 = heading, 6 = subheading (most specific). Omit to return all matching levels."New value: +"Native aggregation level: HS uses 2 (chapter), 4 (heading), 6 (subheading); SITC uses 1–5. Omit to return all matching levels."

changedInput schema / properties / classification / description

Previous value: -"HS classification version. \"HS\" covers the combined dataset across all editions (H0–H6). Use a specific edition (e.g. \"H6\") for version-specific lookups."New value: +"Goods reference catalog: HS uses the default HS.json discovery catalog, whose total identifies H6; it is not an authoritative historical-edition reference. Select H0–H6 for an explicit HS edition, or SS/S1–S4 for SITC."

changedInput schema / properties / classification / enum

Previous value: -[
-  "HS",
-  "H0",
-  "H1",
-  "H2",
-  "H3",
-  "H4",
-  "H5",
-  "H6"
-]New value: +[
+  "HS",
+  "H0",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "SS",
+  "S1",
+  "S2",
+  "S3",
+  "S4"
+]

changedInput schema / properties / query / description

Previous value: -"Keyword, partial description, or HS code prefix to search for. Examples: \"motor vehicles\", \"8471\", \"coffee\", \"84\" (chapter 84 = machinery)."New value: +"Keyword, partial description, or commodity code prefix. Examples: \"motor vehicles\", \"8471\", \"coffee\", \"84\" (HS chapter 84 = machinery)."

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "matches",
-      "totalMatches",
-      "shown",
-      "truncated"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "classification",
+      "matches",
+      "totalMatches",
+      "shown",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / classification

Added value: +{
+  "description": "Reference catalog used for the search.",
+  "type": "string"
+}

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_aggregation_level`: The requested level does not belong to the selected classification family. Other values are possible when a failure originates below the handler."

addedOutput schema / properties / error / properties / data / properties / reason / examples
```
Added value: +[
+  "invalid_aggregation_level"
+]
```

changedOutput schema / properties / matches / description

Previous value: -"HS codes matching the query."New value: +"Commodity codes matching the query in the selected classification."

changedOutput schema / properties / matches / items / description

Previous value: -"A single HS commodity code entry."New value: +"A commodity entry from the selected catalog."

changedOutput schema / properties / matches / items / properties / aggrLevel / description

Previous value: -"Aggregation level: 2 (chapter), 4 (heading), 6 (subheading)."New value: +"Native aggregation level in the selected HS or SITC catalog."

changedOutput schema / properties / matches / items / properties / id / description

Previous value: -"HS code string (e.g. \"84\", \"8471\", \"847130\")."New value: +"Commodity code in the selected classification, preserving leading zeros."

changedOutput schema / properties / matches / items / properties / parent / description

Previous value: -"Parent HS code (chapter for headings; heading for subheadings)."New value: +"Parent commodity code in the selected classification."

changedOutput schema / properties / matches / items / properties / recommendedQueryCode / description

Previous value: -"Best code to pass as cmd_code in trade data queries for this commodity. Uses the most specific level that returns meaningful data."New value: +"Code to pass as cmd_code with the same classification in trade data queries."

First observedOct 13, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new context: the caveat that the default HS catalog is a discovery catalog rather than an authoritative historical-edition reference, and the hierarchy/leaf-status semantics that shape interpretation of results.

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?

Three tight sentences with the core capability front-loaded and the caveat placed last where it belongs. Some content (the HS 2/4/6 and SITC 1–5 level mapping) duplicates the schema verbatim and could be trimmed.

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 an output schema present and full parameter documentation, the description need not explain return values, and it correctly focuses on classification-edition semantics. It could go one step further by stating the explicit handoff to comtrade_get_trade_flows using recommendedQueryCode, but nothing essential for correct invocation 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 description coverage is 100%, so the schema already documents all four parameters, including the aggr_level level mapping and the classification enum caveats. The description restates the level scheme and adds only the edition-matching heuristic, so it adds marginal meaning beyond structured fields.

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?

States a specific verb and resource ("Find HS or SITC commodity codes") plus the three search modes (keyword, partial description, code prefix) and the scoping constraint ("in the selected classification"). This is clearly distinguishable from siblings like comtrade_lookup_countries or comtrade_get_top_commodities.

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?

Implies the workflow position by noting it returns "recommendedQueryCode for subsequent trade queries," and gives edition-selection guidance ("Select the edition matching the trade records when interpreting historical codes"). It stops short of explicit when-not guidance or naming a specific sibling as an alternative.

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

All un-comtrade-mcp-server 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.