un-comtrade-mcp-server

Get Top Trade Commodities

comtrade_get_top_commodities

Read-only

Rank HS chapters (2-digit) or headings (4-digit) by trade value for one reporter, flow, and annual or monthly period. Retrieves matching TOTAL and the reporter’s HS edition, then queries explicit commodity codes in chunks; capped chunks are subdivided. Shares use matching TOTAL. Incomplete coverage returns available categories without ranks or shares and identifies unresolved codes. Defaults to World; optionally select one bilateral partner. Counterpart to comtrade_get_top_partners.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of top commodity categories to return; above 50 returns all retrieved categories.
`period`	Yes	Single period: annual (YYYY) or monthly (YYYYMM, month 01–12).
`flow_code`	Yes	Trade flow: M=imports, X=exports.
`aggr_level`	No	HS aggregation level: 2 = chapter (broader), 4 = heading (more specific).
`partner_code`	No	M49 partner code for a bilateral relationship; omit for World aggregate (0).
`reporter_code`	Yes	M49 numeric code of the reporting country.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Recovery hint when no data is returned.
`period`	No	Period queried.
`flowCode`	No	Flow direction queried.
`aggrLevel`	No	HS aggregation level used.
`truncated`	No	True when complete commodity-code coverage could not be established.
`commodities`	No	Top commodity categories sorted by descending trade value.
`missingCodes`	No	Codes whose retrieval failed or remained capped; empty when the code universe is unavailable.
`reporterCode`	No	M49 reporter code.
`reporterDesc`	No	Reporter country name.
`totalValueUsd`	No	Sum of primary values across all returned categories (before limit).
`coverageNotice`	No	Explanation of coverage and ranking availability.
`coverageComplete`	No	Whether every code in the matching HS edition was queried without a capped response.
`totalCommodities`	No	Total commodity categories returned by API.
`classificationCode`	No	HS edition identified by matching TOTAL.
`denominatorValueUsd`	No	Matching TOTAL value used as the share denominator, separate from the retrieved-category sum.

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedNov 3, 2026

removedInput schema / properties / flow_code / enum
```
Removed value: -[
-  "M",
-  "X"
-]
```

changedInput schema / properties / partner_code / description

Previous value: -"M49 partner code to filter to a specific bilateral relationship. Omit to rank commodities across all partners."New value: +"M49 partner code for a bilateral relationship; omit for World aggregate (0)."

changedInput schema / properties / period / description

Previous value: -"Single period: annual (YYYY) or monthly (YYYYMM)."New value: +"Single period: annual (YYYY) or monthly (YYYYMM, month 01–12)."

removedInput schema / properties / period / minLength
```
Removed value: -4
```
addedInput schema / properties / period / pattern
```
Added value: +"^[0-9]{4}(?:0[1-9]|1[0-2])?$"
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "commodities",
-      "reporterCode",
-      "reporterDesc",
-      "period",
-      "flowCode",
-      "aggrLevel",
-      "totalCommodities",
-      "truncated"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "commodities",
+      "reporterCode",
+      "reporterDesc",
+      "period",
+      "flowCode",
+      "aggrLevel",
+      "totalCommodities",
+      "truncated",
+      "coverageComplete",
+      "coverageNotice",
+      "missingCodes"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / classificationCode

Added value: +{
+  "description": "HS edition identified by matching TOTAL.",
+  "type": "string"
+}

changedOutput schema / properties / commodities / items / properties / rank / description

Previous value: -"Rank (1 = largest trade value)."New value: +"Rank (1 = largest trade value), only with complete code coverage and known values."

changedOutput schema / properties / commodities / items / properties / sharePercent / description

Previous value: -"Share of total trade value among returned commodities, as a percentage."New value: +"Share of matching TOTAL trade value, only with complete code coverage."

changedOutput schema / properties / commodities / items / required

Previous value: -[
-  "rank",
-  "cmdCode",
-  "cmdDesc",
-  "aggrLevel"
-]New value: +[
+  "cmdCode",
+  "cmdDesc",
+  "aggrLevel"
+]

addedOutput schema / properties / coverageComplete

Added value: +{
+  "description": "Whether every code in the matching HS edition was queried without a capped response.",
+  "type": "boolean"
+}

addedOutput schema / properties / coverageNotice

Added value: +{
+  "description": "Explanation of coverage and ranking availability.",
+  "type": "string"
+}

addedOutput schema / properties / denominatorValueUsd

Added value: +{
+  "description": "Matching TOTAL value used as the share denominator, separate from the retrieved-category sum.",
+  "type": "number"
+}

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: `keyless_hs_edition_unsupported`: An explicit HS edition requires authenticated access. `upstream_validation`: UN Comtrade rejects the supplied query dimensions. `invalid_upstream_response`: UN Comtrade returns a malformed response. `invalid_reporter_filter`: The query omits required reporter filtering. Other values are possible when a failure originates below the handler."

addedOutput schema / properties / error / properties / data / properties / reason / examples

Added value: +[
+  "keyless_hs_edition_unsupported",
+  "upstream_validation",
+  "invalid_upstream_response",
+  "invalid_reporter_filter"
+]

addedOutput schema / properties / missingCodes

Added value: +{
+  "description": "Codes whose retrieval failed or remained capped; empty when the code universe is unavailable.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / truncated / description

Previous value: -"True when API returned 500 records and results may be incomplete."New value: +"True when complete commodity-code coverage could not be established."

First observedOct 13, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses meaningful internals: matching TOTAL retrieval, chunked code queries, subdivision of capped chunks, and shares computed from the matching TOTAL. It also discloses degraded behavior (unranked categories and unresolved codes on incomplete coverage). Minor gap: no indication of failure or rate-limit behavior for the multi-chunk fan-out.

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 primary action is front-loaded in sentence one and each subsequent sentence adds distinct operational detail. It is dense to the point of being terse in the middle clauses, but no sentence is redundant filler.

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 6 parameters, partial-coverage risk, and chunked retrieval, the description covers inputs, ranking semantics, and partial-result behavior; the output schema carries return shape, so nothing essential is missing. An agent can call it correctly and interpret degraded responses from the description alone.

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 coverage is 100%, so the baseline is 3; the description adds value by clarifying that reporter, flow, and period define a single ranking context and that omitting the bilateral reporter selects World. The limit/truncation interaction with chunking is also implied by the coverage caveat, though the exact threshold lives only in the schema.

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 first sentence states a specific verb (rank), resource (HS chapters/headings), and scope (one reporter, flow, and annual or monthly period). Naming comtrade_get_top_partners as the counterpart lets an agent separate this tool from its closest sibling without opening either schema.

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?

Usage context is clear: default to World unless a single bilateral partner is supplied, and the counterpart pointer implicitly routes partner-level ranking to comtrade_get_top_partners. It stops short of explicit when-not guidance against the other siblings such as comtrade_search_commodities, so it is not a 5.

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.