xippios-mcp

Overview Schema Source Related Servers Discussions Admin

comtrade_get_top_partners

Read-onlyIdempotent

Returns a reporter's N trade partners ranked by primary value for a chosen commodity, period, and flow from UN Comtrade data.

Instructions

A reporter's n largest partners in one product and period, by primary value.

One data/v1/get call for goods (typeCode C) without partnerCode (every partner), pinned to the total of every breakdown (partner2Code 0, customsCode C00, motCode 0, breakdownMode classic), with descriptions (includeDesc). The rows are sorted by primary_value, largest first, here rather than upstream; partner 0, World, is dropped because it is the total over all partners, not a partner; the first n rows are returned and nothing else is changed. Areas that are not countries, such as 490 "Other Asia, nes", stay in the ranking where the reporter reported them. Bounded by construction at one row per partner (310 in the packaged partnerAreas.json), so there is no count call. Arguments are resolved and checked before the call; an unknown reporter raises UnknownCode, an InvalidRequestError naming the packaged list and the closest area, another mistake InvalidRequestError naming the closest valid value. meta.request holds the get_data arguments that were sent, and n.

Args: reporter: The reporting area, as UN Comtrade's code or its ISO alpha-3 code: "757" or "CHE" Switzerland, "842" or "USA", "276" or "DEU" Germany, "156" or "CHN" China; list_reporters(search=...) finds them. Codes are UN Comtrade's, not ISO numeric (Switzerland is 757, not 756). An alpha-3 code that several codes share resolves to the one still in use ("DEU" is 276, not 280 Fed. Rep. of Germany until 1990). commodity: One product code of cl_code: "TOTAL" all goods, an HS chapter "27", heading "3004" or subheading "300490". list_commodities("HS", search="medicament") finds codes. period: One year "2023" (annual data) or month "202305" (monthly data). flow: One trade flow: "X" exports, "M" imports, "RX" re-exports, "RM" re-imports. n: How many partners, at least 1, e.g. 10; fewer come back when fewer partners have a row. cl_code: Product classification, "HS" by default: all HS editions as each reporter reported them (rows name the edition in classification_code, e.g. "H6"); an edition "H0" to "H5", SITC "SS" or "S1" to "S4", BEC "B4", "B5" also work. "H6" is valid but upstream answered HTTP 500 to every try on 2026-10-23, so "HS" stays the default. EBOPS "EB", "EB02", "EB10", "EB10S" (services), "BE" and "TM" are accepted but untested with the pinned typeCode C.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "reporter": "<reporter>",
      "commodity": "<commodity>",
      "period": "<period>",
      "flow": "<flow>",
      "n": "<n>"
    },
    "name": "comtrade_get_top_partners"
  }
}

Input Schema

Name	Required	Default
`n`	Yes
`flow`	Yes
`period`	Yes
`cl_code`	No	HS
`reporter`	Yes
`commodity`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 12, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses exactly what the tool changes versus upstream (local sort by primary_value, World partner 0 dropped, other non-country areas kept), the bound of 310 partners, and the validation failures (UnknownCode, InvalidRequestError naming the closest valid value or packaged list). It also says meta.request echoes the sent get_data arguments plus n, which is behavior no annotation could convey.

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 core purpose, then mechanism, then a clear Args block. Some material is marginal for an agent deciding how to call it — the pinned breakdownMode/customsCode/motCode plumbing and the untested EBOPS list — but nothing is redundant and the density is justified by the 0% schema coverage.

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 six-parameter, five-required read tool with no output schema and no parameter descriptions, the definition covers inputs, error modes, and the shape of the return (sorted rows plus meta.request and n) in enough detail to call it correctly without further lookup.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description carries the full burden and does: every one of the six parameters is documented with concrete examples and traps (codes are UN Comtrade's, not ISO numeric — 757 not 756; alpha-3 collisions resolve to the code in use; cl_code defaults to HS with edition and SITC/BEC/EBOPS variants; H6 currently 500s upstream; n must be at least 1 and fewer rows may return).

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 gives a precise verb-equivalent, resource, and scope: 'A reporter's n largest partners in one product and period, by primary value.' It is immediately distinguishable from comtrade_get_data (raw rows) and comtrade_get_bilateral_data (pairwise), because the ranking and top-n truncation are named up front.

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?

It states context for use — one upstream call, no separate count call needed because the result is bounded at one row per partner — and points at list_reporters and list_commodities for resolving codes. It does not explicitly say when to prefer a sibling such as comtrade_get_world_share or comtrade_get_bilateral_data instead, so there is no exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server