Ava Advisor

Trade Flows & Rankings

trade

Read-only

International TRADE STATISTICS — countries' import/export flows, partners, rankings and balances from UN Comtrade (official customs data). NOT securities trading: it never places, routes or executes an order. Pick mode; each mode reads a subset of the params (see each param's note).

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": {
      "mode": "<mode>"
    },
    "name": "trade"
  }
}

Input Schema

Name	Required	Description
`flow`	No	export/import/both. Defaults: flows/top_partners=export, top_traders=import.
`freq`	No	annual (default) \| monthly (YYYYMM, goods only). flows only.
`mode`	Yes	flows = one country's trade of a product over time · top_partners = a country's biggest trading partners for a product · top_traders = rank COUNTRIES by trade of a product (world/region) · balance = a country's trade balance (surplus/deficit).
`type`	No	goods (default, HS) \| services (EBOPS, value-only). flows/top_partners.
`codes`	No	Product: HS code(s) OR a plain-English product ('copper','cars'), server-resolved. REQUIRED for flows/top_partners/top_traders; omit for balance → TOTAL (all goods).
`limit`	No	top_partners/top_traders: top-N (default 10, max 50).
`order`	No	top_traders only: desc (default) / asc; for streak = run direction.
`scope`	No	top_traders only: world (default) / continent / subregion / econ group (asean/eu/g7) / CSV ISO-2.
`mirror`	No	Also return the partner-reported figure + discrepancy (China esp.). flows only, goods.
`period`	No	Year '2023' / list '2020,2021' / range '2015:2024' / 'lastN' / 'latest'. DYNAMIC — never hardcode. Defaults vary by mode.
`context`	No	OPTIONAL but RECOMMENDED — the user's FULL request VERBATIM (any language). Used to pick the right code + SUPPLY STAGE (ore vs concentrate vs refined) and leaf-vs-family granularity for a `codes` concept.
`partner`	No	Partner country, or 'World' (default). flows/balance only.
`rank_by`	No	top_traders only: value (default) / growth (CAGR) / streak.
`reporter`	No	Reporting country — name/ISO/M49 ('Thailand'/'THA'/'764'), server-resolved. REQUIRED for flows/top_partners/balance.
`min_value_usd`	No	top_traders only: floor to drop tiny-base noise.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A4.2/5.0

Behavior4/5

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

readOnlyHint already covers safety, and the description adds real context beyond that: the data provenance (official UN Comtrade customs data) and the important behavioral trait that each mode reads only a subset of the 15 params. It omits anything about response shape, latency, or failure modes, which matters for a tool with no output schema.

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, all front-loaded: domain and source first, the critical negative disambiguation second, the dispatch mechanism last. Nothing is redundant with the title and every clause earns its place.

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?

For a 15-param mode-dispatched tool the description correctly establishes the mental model (one mode at a time, per-mode param subsets) and leans on the schema for the rest. The gap is return shape: with no output schema, an agent cannot tell what `flows` versus `balance` actually emits, and the description does not sketch 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% and every parameter carries a per-mode applicability note, so the description correctly defers with "each mode reads a subset of the params (see each param's note)". It adds no meaning beyond the schema — no worked example of mode/param combinations, no note on what happens when an inapplicable param is passed.

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 resource with a domain qualifier: "International TRADE STATISTICS — countries' import/export flows, partners, rankings and balances from UN Comtrade". It explicitly negates the most likely confusion (securities trading) in a toolset dominated by finance siblings, and enumerates the four analytical shapes the tool returns.

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 strong when-not ("it never places, routes or executes an order") that disambiguates against the trading-sounding name, and routes the agent to `mode` as the selector. It does not, however, distinguish itself from the other macro/series data siblings (fred_series, wb_series, financials), so the agent gets no guidance on which economic-data tool to pick.

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

All Ava Advisor 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.