Comtrade

Comtrade Top Partners

comtrade_top_partners

Read-onlyIdempotent

Find a country's top trading partners ranked by trade volume. Returns partner countries and total trade values. Defaults to ANNUAL; pass frequency="monthly" for a single month's ranking instead of the last full year's.

Input Schema

Name	Required	Description
`hs`	No	Alias for hs_code — HS commodity code. Use this OR hs_code, not both.
`flow`	Yes	Trade flow: "M" for imports, "X" for exports
`year`	Yes	Trade period. For frequency="annual" (default): a year, e.g. "2024". For frequency="monthly": year+month as YYYYMM, e.g. "202401".
`limit`	No	Number of top partners to return (default 20)
`hs_code`	No	Optional HS commodity code to filter by specific product (e.g. "2603" for copper ores) — omit for all commodities (TOTAL). Aliases accepted: commodity_code, commodity, hs, cmd_code (pass exactly one).
`cmd_code`	No	Alias for hs_code — HS commodity code. Use this OR hs_code, not both.
`commodity`	No	Alias for hs_code — HS commodity code. Use this OR hs_code, not both.
`frequency`	No	Data frequency: "annual" (default) or "monthly". Monthly coverage is thinner — not every reporter files monthly, and recent months lag; a reporter with no filing for the requested month is absent from the ranking, not shown at zero. When "monthly", pass `year` as YYYYMM.
`reporter_code`	Yes	Country name (e.g. "USA", "China") or UN numeric code (842=US). Names resolved automatically.
`commodity_code`	No	Alias for hs_code — HS commodity code (e.g. "2603" for copper ores). Use this OR hs_code, not both.

Output Schema

Name	Required	Description
`flow`	Yes	Trade flow type (Imports or Exports)
`year`	Yes	Trade year queried
`reporter`	Yes	Reporting country name
`top_partners`	Yes
`total_partners`	Yes	Total number of top partners returned

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedSep 29, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "flow": "X",
-    "limit": 10,
-    "reporter_code": "842",
-    "year": "2024"
-  },
-  {
-    "flow": "M",
-    "reporter_code": "156",
-    "year": "2023"
-  },
-  {
-    "flow": "X",
-    "frequency": "monthly",
-    "limit": 5,
-    "reporter_code": "682",
-    "year": "202401"
-  }
-]New value: +[
+  {
+    "flow": "X",
+    "limit": 10,
+    "reporter_code": "842",
+    "year": "2024"
+  },
+  {
+    "flow": "M",
+    "reporter_code": "156",
+    "year": "2023"
+  },
+  {
+    "flow": "X",
+    "frequency": "monthly",
+    "limit": 5,
+    "reporter_code": "682",
+    "year": "202401"
+  },
+  {
+    "commodity_code": "2603",
+    "flow": "M",
+    "limit": 5,
+    "reporter_code": "China",
+    "year": "2024"
+  }
+]

addedInput schema / properties / cmd_code

Added value: +{
+  "description": "Alias for hs_code — HS commodity code. Use this OR hs_code, not both.",
+  "type": "string"
+}

addedInput schema / properties / commodity

Added value: +{
+  "description": "Alias for hs_code — HS commodity code. Use this OR hs_code, not both.",
+  "type": "string"
+}

addedInput schema / properties / commodity_code

Added value: +{
+  "description": "Alias for hs_code — HS commodity code (e.g. \"2603\" for copper ores). Use this OR hs_code, not both.",
+  "type": "string"
+}

addedInput schema / properties / hs

Added value: +{
+  "description": "Alias for hs_code — HS commodity code. Use this OR hs_code, not both.",
+  "type": "string"
+}

changedInput schema / properties / hs_code / description

Previous value: -"Optional HS commodity code to filter by specific product"New value: +"Optional HS commodity code to filter by specific product (e.g. \"2603\" for copper ores) — omit for all commodities (TOTAL). Aliases accepted: commodity_code, commodity, hs, cmd_code (pass exactly one)."

Changed3 schema fields changedSep 8, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "flow": "X",
-    "limit": 10,
-    "reporter_code": "842",
-    "year": "2024"
-  },
-  {
-    "flow": "M",
-    "reporter_code": "156",
-    "year": "2023"
-  }
-]New value: +[
+  {
+    "flow": "X",
+    "limit": 10,
+    "reporter_code": "842",
+    "year": "2024"
+  },
+  {
+    "flow": "M",
+    "reporter_code": "156",
+    "year": "2023"
+  },
+  {
+    "flow": "X",
+    "frequency": "monthly",
+    "limit": 5,
+    "reporter_code": "682",
+    "year": "202401"
+  }
+]

addedInput schema / properties / frequency

Added value: +{
+  "description": "Data frequency: \"annual\" (default) or \"monthly\". Monthly coverage is thinner — not every reporter files monthly, and recent months lag; a reporter with no filing for the requested month is absent from the ranking, not shown at zero. When \"monthly\", pass `year` as YYYYMM.",
+  "type": "string"
+}

changedInput schema / properties / year / description

Previous value: -"Trade year (e.g., \"2024\")"New value: +"Trade period. For frequency=\"annual\" (default): a year, e.g. \"2024\". For frequency=\"monthly\": year+month as YYYYMM, e.g. \"202401\"."

Changed1 schema field changedJul 7, 2026

changedInput schema / properties / reporter_code / description

Previous value: -"ISO numeric country code (e.g., \"842\" for US)"New value: +"Country name (e.g. \"USA\", \"China\") or UN numeric code (842=US). Names resolved automatically."

Changed1 schema field changedJun 26, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "flow": "X",
-    "limit": 10,
-    "reporter_code": "840",
-    "year": "2024"
-  },
-  {
-    "flow": "M",
-    "reporter_code": "156",
-    "year": "2023"
-  }
-]New value: +[
+  {
+    "flow": "X",
+    "limit": 10,
+    "reporter_code": "842",
+    "year": "2024"
+  },
+  {
+    "flow": "M",
+    "reporter_code": "156",
+    "year": "2023"
+  }
+]

Changed3 schema fields changedMay 24, 2026
- removedOutput schema / properties / top_partners / description
```
Removed value: -"List of top trading partners ranked by trade value"
```
- changedOutput schema / properties / top_partners / items / properties / partner_code / description
```
Previous value: -"ISO numeric country code"New value: +"Partner ISO numeric country code"
```
- changedOutput schema / properties / top_partners / items / properties / trade_value_usd / description
```
Previous value: -"Trade value with this partner in USD"New value: +"Trade value in USD"
```

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "flow": {
+      "description": "Trade flow type (Imports or Exports)",
+      "type": "string"
+    },
+    "reporter": {
+      "description": "Reporting country name",
+      "type": "string"
+    },
+    "top_partners": {
+      "description": "List of top trading partners ranked by trade value",
+      "items": {
+        "properties": {
+          "commodity": {
+            "description": "Commodity code or description",
+            "type": "string"
+          },
+          "partner": {
+            "description": "Partner country name",
+            "type": "string"
+          },
+          "partner_code": {
+            "description": "ISO numeric country code",
+            "type": "number"
+          },
+          "rank": {
+            "description": "Partner rank by trade value",
+            "type": "number"
+          },
+          "trade_value_usd": {
+            "description": "Trade value with this partner in USD",
+            "type": "number"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total_partners": {
+      "description": "Total number of top partners returned",
+      "type": "number"
+    },
+    "year": {
+      "description": "Trade year queried",
+      "type": "string"
+    }
+  },
+  "required": [
+    "reporter",
+    "year",
+    "flow",
+    "total_partners",
+    "top_partners"
+  ],
+  "type": "object"
+}

Changed1 schema field changedMay 6, 2026

addedInput schema / examples

Added value: +[
+  {
+    "flow": "X",
+    "limit": 10,
+    "reporter_code": "840",
+    "year": "2024"
+  },
+  {
+    "flow": "M",
+    "reporter_code": "156",
+    "year": "2023"
+  }
+]

First observedApr 22, 2026

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds the useful behavioral fact that the result is a ranked list of partner countries with total trade values, but omits other traits it could have surfaced, such as how ties or missing reporters are handled.

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 short sentences, front-loaded with purpose before the frequency caveat. Slightly wasteful in that the return-value sentence partially duplicates the output schema, but there is no filler or padding.

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 and schema coverage is full, so the description only needs to carry defaults and mode selection, which it does. The remaining gap is sibling-level routing guidance, which matters given how many Comtrade tools sit alongside it.

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 coverage is 100%, so all ten parameters (including the alias cluster for hs_code) are already documented in the schema. The description's only added parameter detail is the frequency/month pairing, which the schema also states. Baseline 3 is appropriate.

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 a country's top trading partners ranked by trade volume') and makes the ranking semantics explicit. It is clearly distinguishable from siblings like comtrade_top_commodities (commodities, not partners) and comtrade_trade_data (raw flows, not a ranked partner list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete guidance on the annual-vs-monthly choice and the default, which is genuinely useful. However, it never says when to prefer this tool over the closely related siblings comtrade_top_commodities or comtrade_trade_data, so the routing decision 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 Comtrade 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.

Comtrade Top Partners

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources