un-comtrade-mcp-server

Get Trade Balance

comtrade_get_trade_balance

Read-only

Compute the trade balance for a country over one or more periods — total exports minus total imports — with optional HS or SITC commodity filter. Preview makes two paced requests per served period; authenticated calls batch periods. Returns the signed balance (USD), export value, import value, and coverage ratio (exports / imports). Note: mirror asymmetry is common — balance reflects values as reported by this country; the same flow may be recorded differently by the partner. Uses comtrade_lookup_countries to resolve reporter codes.

Input Schema

Name	Required	Description	Default
`freq`	No	Frequency: A=annual YYYY, M=monthly YYYYMM (01–12).	A
`period`	Yes	Annual periods (YYYY) or monthly periods (YYYYMM). Serves the first 12 and discloses the remainder; input ceiling 120.
`cmd_code`	No	HS or SITC commodity codes to restrict the balance calculation. Serves the first 20 and discloses the remainder; input ceiling 200. Omit to compute the overall trade balance across all commodities.
`partner_code`	No	M49 partner code (0–999); defaults to World (0). The balance uses the reporter’s values.
`reporter_code`	Yes	M49 numeric code of the reporting country (0–999).
`classification`	No	Goods classification: HS/H0–H6 or SITC S1–S4/SS.	HS

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Possible incompleteness of the balance when a preview response reaches its cap.
`periods`	No	Balance computation per period.
`cmdCodes`	No	Commodity codes used in the query (absent when querying all commodities).
`partnerCode`	No	M49 partner code used.
`partnerDesc`	No	Partner name supplied by the returned records, or its numeric code when unavailable.
`mirrorCaveat`	No	Standard caveat about mirror asymmetry — balance reflects this country's reported values.
`reporterCode`	No	M49 reporter code used.
`reporterDesc`	No	Reporter country name.
`referenceNotice`	No	Reference descriptions unavailable; codes and trade values retained.
`unservedPeriods`	No	Periods beyond the 12-period work cap; query them separately.
`unservedCmdCodes`	No	Commodity codes beyond the 20-code work cap; query them separately.

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedNov 3, 2026

removedInput schema / properties / classification / enum

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

addedInput schema / properties / cmd_code / items / pattern
```
Added value: +"^(?:[A-Z0-9]+(?:\\.[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 / partner_code

Added value: +{
+  "default": 0,
+  "description": "M49 partner code (0–999); defaults to World (0). The balance uses the reporter’s values.",
+  "maximum": 999,
+  "minimum": 0,
+  "type": "integer"
+}

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

changedInput schema / properties / reporter_code / description

Previous value: -"M49 numeric code of the reporting country."New value: +"M49 numeric code of the reporting country (0–999)."

changedInput schema / properties / reporter_code / maximum
```
Previous value: -9007199254740991New value: +999
```
changedInput schema / properties / reporter_code / minimum
```
Previous value: --9007199254740991New value: +0
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "periods",
-      "reporterCode",
-      "reporterDesc",
-      "mirrorCaveat"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "periods",
+      "reporterCode",
+      "reporterDesc",
+      "partnerCode",
+      "partnerDesc",
+      "mirrorCaveat"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_data`: No trade data available for the reporter and period combination. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `keyless_hs_edition_unsupported`: Explicit HS editions require authenticated data access. `invalid_reporter_filter`: Reporter omission lacks an explicit partner. `upstream_validation`: UN Comtrade rejects the query dimensions. `invalid_upstream_response`: UN Comtrade returns malformed trade data. `no_data`: No trade data available for the reporter and period combination. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "no_data"
-]New value: +[
+  "keyless_hs_edition_unsupported",
+  "invalid_reporter_filter",
+  "upstream_validation",
+  "invalid_upstream_response",
+  "no_data"
+]

addedOutput schema / properties / partnerCode

Added value: +{
+  "description": "M49 partner code used.",
+  "type": "number"
+}

addedOutput schema / properties / partnerDesc

Added value: +{
+  "description": "Partner name supplied by the returned records, or its numeric code when unavailable.",
+  "type": "string"
+}

First observedOct 13, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the request cost model ('preview makes two paced requests per served period; authenticated calls batch periods') and the truncation behavior for periods and commodity codes. It also flags the mirror-asymmetry caveat that the balance reflects only the reporter's own values, which is a substantive data-quality warning an agent could not infer from structured fields.

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?

Front-loaded with the computation and formula, then progressively adds cost model, return shape, and caveat. It is dense with four long sentences but nearly every clause carries operational value; the enumerated return fields are the only part that mildly duplicates the output schema.

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?

Given a six-parameter tool with a full input schema, an output schema, and safety annotations, the description covers the remaining gaps: request cost, batching, truncation, return composition, and the mirror-asymmetry interpretation risk. Nothing an agent needs to call or interpret the result correctly 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 every parameter is already documented with defaults and formats. The description adds only a light gloss on the commodity filter and reporter-code resolution, which is the expected baseline when the schema does the heavy lifting.

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 ('Compute the trade balance for a country over one or more periods') and defines the metric inline ('total exports minus total imports'), which distinguishes it from the raw-flow sibling comtrade_get_trade_flows. The optional commodity filter scope is also named.

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 correct usage context via the commodity-filter option and explicitly points to comtrade_lookup_countries for resolving reporter codes. It does not explicitly state when to prefer this over comtrade_get_trade_flows or comtrade_get_top_partners, so the routing guidance is inferred rather than stated.

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.