un-comtrade-mcp-server

Get Top Trading Partners

comtrade_get_top_partners

Read-only

Rank trading partners for a reporter by trade value for a given commodity and flow direction. Returns the top N partners sorted by descending value — answers "who does country X mainly export product Y to?" or "where does country X mainly import product Z from?" for a single period. Fetches a disaggregated breakdown across all partners then sorts locally. Omit cmd_code to rank partners for total trade.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of top partners to return; above 50 returns all retrieved partners.
`period`	Yes	Single period: annual YYYY or monthly YYYYMM, month 01–12; frequency is inferred.
`cmd_code`	No	Single HS commodity code (e.g. "84", "8471"). Omit or pass "TOTAL" to rank partners for total merchandise trade.
`flow_code`	Yes	Trade flow: M=imports, X=exports.
`reporter_code`	Yes	M49 numeric code of the reporting country (0–999).

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.
`cmdCode`	No	Commodity code queried (TOTAL when omitted).
`flowCode`	No	Flow direction queried.
`partners`	No	Top partners sorted by descending trade value.
`truncated`	No	True when API returned 500 records and results may be incomplete.
`reporterCode`	No	M49 reporter code.
`reporterDesc`	No	Reporter country name.
`totalPartners`	No	Total partners with non-zero trade value returned by API.
`totalValueUsd`	No	Sum of primary values across all returned partners (before limit truncation).
`referenceNotice`	No	Reference descriptions unavailable; codes and values retained.

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedNov 3, 2026

addedInput schema / properties / cmd_code / pattern

Added value: +"^(?:[A-Z0-9]+(?:\\.[A-Z0-9]+)*)?$"

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

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; frequency is inferred."

removedInput schema / properties / period / minLength
```
Removed value: -4
```
addedInput schema / properties / period / 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 / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `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. Other values are possible when a failure originates below the handler."

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

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

addedOutput schema / properties / referenceNotice

Added value: +{
+  "description": "Reference descriptions unavailable; codes and values retained.",
+  "type": "string"
+}

First observedOct 13, 2026

TDQS

A4.2/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 genuinely useful behavior beyond them: it fetches a disaggregated breakdown across all partners and sorts locally, which warns about data volume and implies the limit is applied client-side. It stops short of stating rate limits or what happens when no partners exist.

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?

Three sentences, front-loaded with the action and purpose, then the concrete question framing, then the execution note. No filler and nothing important buried.

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?

An output schema exists so return values need no explanation, and all five parameters are schema-documented at full coverage. The only meaningful gap is that it does not clarify how ties or missing partner data are handled, which for a ranking tool is a minor omission.

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 both the limit and cmd_code semantics ('Omit or pass TOTAL') are already fully documented in the schema. The description's 'top N' and 'Omit cmd_code' remarks largely restate that, adding little meaning beyond structured fields. 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 (rank) and resource (trading partners) with the scoping dimensions (reporter, commodity, flow), and the two quoted example questions make the output shape unambiguous. It is clearly distinguished from sibling comtrade_get_top_commodities, which does the inverse ranking.

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: single-period ranking, and 'Omit cmd_code to rank partners for total trade' gives a concrete decision rule. However, no sibling is named as an alternative, so an agent comparing this against comtrade_get_trade_flows or comtrade_get_top_commodities must infer the routing itself.

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.