Skip to main content
Glama

Primary Source Commodities

Bilateral Trade Flow

trade.flow
Read-onlyIdempotent

Import or export volume and value between two countries for one commodity and year, from UN Comtrade. Use for 'how much X did A sell to B'. Pass countries as ISO alpha-3 (IND, GHA) and partner=WLD for the world total. Call trade.codes-equivalent discovery via /v1/trade/codes for valid values. Annual data; the response says whether the rows reconcile with the upstream's own total.

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": {
      "commodity": "<commodity>",
      "reporter": "<reporter>",
      "year": "<year>"
    },
    "name": "trade.flow"
  }
}

Input Schema

NameRequiredDescriptionDefault
flowNoDirection from the reporter's view. Example: export.
yearYesFour-digit year. Example: 2023.
partnerNoPartner country, or WLD for the world total. Example: GHA.
reporterYesReporting country, ISO alpha-3 preferred. Example: IND.
commodityYesInstrument code with an HS heading. Example: ZR for rice.

Output Schema

NameRequiredDescriptionDefault
flowNo
yearYes
foundYesFalse when the upstream has no data for this cell
sourceNoseries_id is the canonical query; url re-runs it
hs_codeNoHarmonised System heading queried
partnerYes
completeNoWhether returned rows reconcile with the upstream's World total; null when there is nothing to compare
reporterYes
commodityYes
license_tagNo
net_weight_kgNo
shortfall_usdNo
primary_value_usdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavior: annual granularity, upstream provenance, and a reconciliation flag indicating whether returned rows match the upstream's own total — useful signal for trusting the numbers.

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 dense sentences, front-loaded with the resource and scope, and no filler. The '/v1/trade/codes' reference is slightly meta for an MCP description, but it is actionable and short.

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?

Five parameters, an output schema and full annotation coverage mean the description only needs to add source, granularity and trust cues — which it does. The gap is the optional flow parameter: the description never says whether omitting it returns both directions, which is the one call-shaping detail an agent still needs.

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 the baseline is 3; the schema already documents ISO alpha-3, partner=WLD, and the HS-heading commodity code. The description restates the ISO alpha-3 and WLD conventions without adding format or validation detail, and it does not explain what happens when the optional flow parameter is omitted.

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 (import/export volume and value between two countries, one commodity, one year) plus the upstream source (UN Comtrade). The final clause and the pointer to /v1/trade/codes separate it from the code-discovery sibling, so an agent can route without opening either schema.

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?

Gives a concrete use phrase, 'how much X did A sell to B', and instructs the agent to resolve valid values via the codes endpoint before calling. No explicit when-not-to-use or statement about the other trade siblings, so it stops short of full alternative routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources