Skip to main content
Glama
Sign In
xippios-mcp

xippios-mcp

by xippios
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

comtrade_get_data

Read-onlyIdempotent

Fetch UN Comtrade final trade data for one query, validating codes and checking counts first to avoid empty results or silent truncation above 100,000 records.

Instructions

Fetch UN Comtrade final trade data for one query, up to 100,000 records.

Counts first (one extra call, as get_counts): a count of 0 returns an empty list without fetching, since no matching data is an answer, not an error; a count above 100,000 raises QueryTooLarge with the count before anything is fetched, because upstream would cut the answer at 100,000 rows without saying so. Each row carries every field of upstream's TradeDataRecord under its snake_case name; primary_value is upstream's primary trade value (taken from the CIF or FOB value, in cifvalue/fobvalue). Leaving out partner2_code, customs_code and mot_code returns every breakdown upstream holds (32 rows for Switzerland's 2023 exports to the World); the row with partner2_code 0, customs_code "C00" and mot_code 0 is the total, and pinning those three (or breakdown_mode="classic") returns that row alone. Arguments are checked before any call; an unknown reporter, partner, customs or transport code raises UnknownCode, an InvalidRequestError naming the packaged list and the closest code, another mistake InvalidRequestError naming the closest valid value.

Args: type_code: "C" goods or "S" services. freq_code: "A" annual or "M" monthly. cl_code: Product classification: "HS" (all HS editions as reported; prefer it), an edition "H0" to "H5", SITC "SS", "S1" to "S4", BEC "B4", "B5", for services EBOPS "EB", "EB02", "EB10", "EB10S"; also "BE" and "TM", which the spec lists and upstream accepts. "H6" is valid but upstream answered HTTP 500 to all five tries on 2026-10-23 (two reporters, two product codes); "HS" rows carry the edition the reporter used, e.g. classification_code "H6" for Switzerland 2023. reporter_code: Reporting areas as UN Comtrade's numeric codes, comma-separated, e.g. "757" Switzerland, "842" USA, "276" Germany, "156" China, "757,842", as list_reporters lists them. Some differ from ISO numeric codes: Switzerland is 757, not 756. Omit for every reporter. partner_code: Partner areas, comma-separated, as list_partners lists them: "0" World (the total over all partners), "276" Germany. Omit for every partner, one row each. partner2_code: Second partner (consignment) areas, comma-separated, codes of list_partners; "0" is the total. period: Years "2023" (annual) or months "202305" (monthly), at most 12 comma-separated, e.g. "2021,2022,2023". cmd_code: Product codes of cl_code, comma-separated, as list_commodities(cl_code) lists them: "TOTAL" for all goods, "AG2", "AG4", "AG6" for every code at that level, codes such as "0901" or "090111", wildcards such as "27??" (every four-digit code under 27) or "27*". For services the classification files name "200" (EB, EB02, EB10) or "S" (EB10S) as the total; recorded counts confirm "200" on EB10 and EB02, where "TOTAL" counted 0 (EB10). A code upstream does not have counts 0 too, so a 0 does not prove that a code exists. flow_code: Trade flows, comma-separated: "X" exports, "M" imports, "RX" re-exports, "RM" re-imports, also "DX", "FM", "MIP", "MOP", "XIP", "XOP", "MIF", "XIF"; e.g. "M,X". mot_code: Modes of transport, comma-separated: "0" the total, "1000" air, "2100" sea, "3100" railway, "3200" road, "9100" pipelines and cables. Omit for every mode, one row each. customs_code: Customs procedures, comma-separated: "C00" the total, "C01" clearance for home use, "C03" outright exportation. Omit for every procedure, one row each. aggregate_by: Upstream parameters to aggregate the results over, comma-separated from cmdCode, period, partnerCode, partner2Code, reporterCode, customsCode, motCode; e.g. "cmdCode" sums the products of "AG2" into one row per remaining breakdown. The aggregated parameters come back as -2 (cmd_code "-2", partner_code -2) with classification_code "GG"; the count matches the rows. breakdown_mode: "plus", upstream's default (omitting it gives the same rows): every customs procedure, mode of transport and second partner; "classic": only the total row (partner2_code 0, customs_code "C00", mot_code 0). include_desc: Upstream's includeDesc, "Include descriptions of data variables": fills reporter_iso/reporter_desc, the partner and second partner ones, flow_desc, cmd_desc, customs_desc, mot_desc, the quantity unit abbreviations, aggr_level and is_leaf; without it they are None.

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": {
      "type_code": "<type_code>",
      "freq_code": "<freq_code>",
      "cl_code": "<cl_code>"
    },
    "name": "comtrade_get_data"
  }
}

Input Schema

NameRequiredDescriptionDefault
periodNo
cl_codeYes
cmd_codeNo
mot_codeNo
flow_codeNo
freq_codeYes
type_codeYes
aggregate_byNo
customs_codeNo
include_descNo
partner_codeNo
partner2_codeNo
reporter_codeNo
breakdown_modeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

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

Far exceeds the annotations: it discloses the 100,000-row cap and that exceeding it raises QueryTooLarge before any fetch, that a count of 0 returns an empty list rather than an error, that upstream silently truncates, the pre-flight validation errors (UnknownCode, InvalidRequestError), and that H6 currently fails upstream with HTTP 500. These are exactly the failure modes an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the size/error behavior are front-loaded, and the Args block is well ordered against the schema. But the prose is dense and overgrown, with parenthetical asides (the dated H6 HTTP 500 investigation, repeated 'one row each', the Switzerland 32-row example) that cost reading effort without changing how the tool is called.

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 14-parameter, no-output-schema tool with zero schema descriptions, the definition supplies the full burden: every parameter, the default breakdown behavior, the count-first workflow, aggregation semantics and error conditions. An agent could invoke it correctly from this text alone.

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?

Schema coverage is 0% across 14 parameters, and the description documents every one with codes, examples and traps: reporter codes differ from ISO numeric (Switzerland 757, not 756), '200' vs 'TOTAL' for services totals, wildcard syntax for cmd_code, and aggregate_by returning -2 with classification_code 'GG'. This fully compensates for the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb, resource and scope: 'Fetch UN Comtrade final trade data for one query, up to 100,000 records.' The word 'final' implicitly separates it from mirror/live-update siblings, but no sibling is named, so the agent must infer the boundary against comtrade_get_bilateral_data or comtrade_get_mirror_flows.

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 real conditional guidance on mechanics: run get_counts first, use breakdown_mode='classic' to get the total row alone, prefer cl_code='HS'. However, it never states when to call this tool rather than the many sibling data tools, which is the main selection decision an agent faces.

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

Deploy Server

Other Tools