un-comtrade-mcp-server

Check Data Availability

comtrade_get_data_availability

Read-only

Check which reporter/period/classification combinations have published data before constructing expensive trade queries. Returns dataset records with period, classification, record count, and first/latest release dates. Call this before querying recent periods — annual data is typically published 3–12 months after the reference year and not all countries report every year. Omit filters to browse the availability index, 50 rows by default. Continue with nextOffset using the same filters and limit.

Input Schema

Name	Required	Description	Default
`freq`	No	Frequency: A=annual YYYY, M=monthly YYYYMM (01–12).	A
`limit`	No	Maximum datasets returned per page; defaults to 50.
`offset`	No	Number of matching datasets to skip; use nextOffset to continue.
`period`	No	Period to check: YYYY (annual) or YYYYMM (monthly). Omit to see all available periods for the reporter.
`type_code`	No	Trade type: C=commodities (goods), S=services.	C
`reporter_code`	No	M49 reporter code to check. Omit to browse availability across all reporters.
`classification`	No	Classification code filter (e.g. "HS", "H6", "EB10"). Omitted or blank defaults to HS for goods and EB10 for services.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of datasets returned on this page.
`notice`	No	Recovery hint when no availability records are found.
`offset`	No	Number of matching datasets skipped for this page.
`datasets`	No	Available datasets matching the query.
`truncated`	No	Whether this page contains only part of the matching dataset list.
`nextOffset`	No	Offset for the next page; absent when no rows remain.
`totalDatasets`	No	Total number of available dataset records.

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedNov 3, 2026

addedInput schema / properties / classification / allOf

Added value: +[
+  {
+    "pattern": "^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"
+  },
+  {
+    "pattern": "^(?:[A-Z][A-Z0-9]*)?$"
+  }
+]

changedInput schema / properties / freq / description

Previous value: -"Frequency: A=annual, M=monthly."New value: +"Frequency: A=annual YYYY, M=monthly YYYYMM (01–12)."

removedInput schema / properties / freq / enum
```
Removed value: -[
-  "A",
-  "M"
-]
```

addedInput schema / properties / limit

Added value: +{
+  "default": 50,
+  "description": "Maximum datasets returned per page; defaults to 50.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Number of matching datasets to skip; use nextOffset to continue.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / period / pattern
```
Added value: +"^[0-9]{4}(?:0[1-9]|1[0-2])?$"
```
changedInput schema / properties / reporter_code / maximum
```
Previous value: -9007199254740991New value: +999
```
changedInput schema / properties / reporter_code / minimum
```
Previous value: --9007199254740991New value: +0
```
removedInput schema / properties / type_code / enum
```
Removed value: -[
-  "C",
-  "S"
-]
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "datasets",
-      "totalDatasets"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "datasets",
+      "totalDatasets",
+      "truncated",
+      "offset",
+      "shown"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

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: `upstream_validation`: UN Comtrade rejects the availability query dimensions. `invalid_upstream_response`: UN Comtrade returns malformed availability data. Other values are possible when a failure originates below the handler."

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

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Offset for the next page; absent when no rows remain.",
+  "type": "number"
+}

addedOutput schema / properties / offset

Added value: +{
+  "description": "Number of matching datasets skipped for this page.",
+  "type": "number"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of datasets returned on this page.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "Whether this page contains only part of the matching dataset list.",
+  "type": "boolean"
+}

First observedOct 13, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: publication-lag characteristics and pagination semantics ('Continue with nextOffset using the same filters and limit'). The list of returned fields is partly redundant with the existing output schema, which keeps this from a 5.

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?

Four dense sentences, front-loaded with the purpose, then the return shape, then the timing rationale, then pagination. No filler or restatement of the name.

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 zero-required-parameter index browser with an output schema and read-only annotations, the description covers purpose, motivation, default page size, and continuation procedure. An agent has everything needed to call it correctly and to chain pages.

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 freq, period, reporter_code, classification, limit and offset are already documented, including the 'omit to browse' behavior. The description only restates omission and pagination at a high level, adding little syntax or meaning beyond the schema; baseline 3 applies.

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: 'Check which reporter/period/classification combinations have published data'. The framing as a pre-flight index check clearly separates it from the sibling query tools (comtrade_get_trade_flows, comtrade_get_top_partners, etc.).

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?

Gives explicit when-to-use guidance ('Call this before querying recent periods') plus the underlying reason (annual data published 3–12 months after reference year, not all countries report every year), and an alternative mode ('Omit filters to browse the availability index'). Nothing is left to inference.

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.