Recipe: Trade exposure

The task

You need a bilateral trade picture between two countries — import/export totals, commodity mix, tariff-revenue context — sourced from UN Comtrade and US government trade data rather than a news estimate.

Tools used: trade_bilateral_analysis (compound, one call, but see below), comtrade_trade_data, census_trade_balance, treasury_customs_revenue, treasury_exchange_rates for the manual/reliable path.

Copy-paste prompt

Give me the bilateral trade picture between <country A> and <country B> using Pipeworx:
total imports/exports (in USD), the trade balance, and any tariff-revenue context. Use
Census trade-balance data for the headline dollar totals — cite whichever specific tool
actually returned each number, not just "Comtrade" generically.

What a good answer looks like

census_trade_balance({ country: "China", year: "2024" })

returns (live call, 2026-08-06):

{
  "country": "CHINA",
  "country_code": "5700",
  "year": "2024",
  "total_imports_usd": 440319387970,
  "total_exports_usd": 143271716369,
  "trade_balance_usd": -297047671601,
  "deficit_or_surplus": "deficit"
}

A trustworthy answer has:

top-level total_imports_usd / total_exports_usd / trade_balance_usd as clean numbers, sourced from Census’s mirror of US trade data — this is the reliable source for headline dollar totals in this recipe (see the compound-tool caveat below).
a country_code you can cross-check ("5700" is Census’s own Schedule C code for China — not an ISO or UN Comtrade numeric code; don’t reuse it as a reporter_code/ partner_code elsewhere in this recipe).
awareness that Comtrade’s own total for the same pair, same year, differs: a live comtrade_top_commodities call for the identical US↔China/2024/imports slice returned $462.6B against Census’s $440.3B — a ~5% gap from different collection/valuation methodologies between the two US-side mirrors of the same trade flow. Neither is “wrong”; cite whichever one you pull the number from, and don’t average or reconcile them yourself.

The plausible-sounding failure here is the compound tool itself. trade_bilateral_analysis returns a fully-formed, confident-looking JSON object — but two of its four sub-blocks are silently empty on every call, for every country pair, because of a reproducible bug (not a transient rate limit) in how it invokes its own sub-tools:

trade_bilateral_analysis({ reporter_code: "842", partner_code: "156" })

Live result (trimmed):

{
  "analysis": "bilateral_trade",
  "year": "2025",
  "imports": { "count": 500, "records": [ /* 500 raw HS-code line items, not a total */ ] },
  "exports": { "count": 500, "records": [ /* same shape */ ] },
  "top_commodities_imported": {
    "total_commodities": 1,
    "top_commodities": [ { "rank": 1, "hs_code": "TOTAL", "trade_value_usd": 327476103023 } ]
  },
  "exchange_rates": { "results": [], "unavailable": true, "source": "treasury-fiscal.treasury_exchange_rates" },
  "us_trade_balance": { "results": [], "unavailable": true, "source": "census-trade.census_trade_balance" },
  "partial_failures": ["treasury-fiscal.treasury_exchange_rates", "census-trade.census_trade_balance"]
}

Three real problems live inside one clean-looking response:

exchange_rates and us_trade_balance are always unavailable: true. The compound tool calls treasury_exchange_rates and census_trade_balance internally without their required country argument — both fail deterministically, every call, not just under load. partial_failures names them, so check that array before assuming the response is complete. Filed as a fix task 2026-08-06 (fleet #137).
imports/exports are raw per-HS-code line items (count: 500, capped), not aggregate totals. There is no imports_usd/exports_usd field anywhere in this response — you have to sum records[].trade_value_usd yourself, or use census_trade_balance directly for the clean top-level total (as shown above).
top_commodities_imported collapses to one synthetic "TOTAL" row regardless of how many commodities actually traded, because the underlying comtrade_top_commodities call hardcodes a classification-level filter that suppresses the real per-HS-code breakdown. Filed as a fix task 2026-08-06 (fleet #136). Until it’s fixed, don’t call comtrade_top_commodities expecting a ranked commodity list — it can only return the aggregate.

None of this raises an error. The call returns 200, the JSON is well-formed, and a reader who doesn’t check partial_failures or notice top_commodities: [{hs_code: "TOTAL", ...}] is a single row would report exchange-rate and trade-balance context that was never actually retrieved.

Step-by-step tool calls

Reliable path: manual, one call per real number

// Headline totals — the one clean, aggregated source in this recipe
census_trade_balance({ country: "China", year: "2024" })

// Raw bilateral flow, line-item detail (500-row cap; sum trade_value_usd yourself for a total)
comtrade_trade_data({ reporter_code: "842", partner_code: "156", year: "2024", flow: "M" })  // M = imports, X = exports

// Tariff revenue (US Treasury, monthly)
treasury_customs_revenue({ year: 2024 })

// Exchange-rate context — country is REQUIRED, not optional
treasury_exchange_rates({ country: "China" })

treasury_exchange_rates and census_trade_balance both take a plain-English country name ("China", "Mexico"), not a numeric code and not a partner argument — a call with either of those instead returns a clear required-argument error rather than silently succeeding.

Country code reference (for Comtrade calls only)

Comtrade tools use ISO 3-digit numeric codes — Census and Treasury tools want the plain country name instead, per above. Don’t reuse one code space for the other tool.

Code	Country
842	United States
156	China
484	Mexico
124	Canada
392	Japan
276	Germany
410	South Korea

comtrade_country_codes({})
// → full list of reporter/partner codes, plus a "note" reminding you 0 = World aggregate

Compound path (fast, but see the three caveats above)

trade_bilateral_analysis({ reporter_code: "842", partner_code: "156" })

One call, but as shown above: use it for the raw import/export line items only, and pull exchange_rates/us_trade_balance/ranked commodities from the manual calls instead until the filed bugs land.

Citation pattern

US-China trade (2024): imports $440.3B, exports $143.3B, deficit $297.0B per Census trade balance (Comtrade’s own mirror of the same flow reports $462.6B imports for the same pair/year — a ~5% methodology gap, cite whichever source the number came from). Tariff/customs revenue context per Treasury.

Caveats

Comtrade data lags ~12 months. Most recent year is the last complete calendar year, not current.
Reporter vs. partner asymmetry, plus a Census-vs-Comtrade gap. Different collection methodologies mean the “same” bilateral flow can differ by several percent depending on which US-side mirror you query — see the worked example above. Cite the specific source, don’t reconcile the two yourself.
Comtrade tools want numeric country codes; Census/Treasury tools want plain country names. Passing the wrong ID space to either fails cleanly (a required-argument error) — it will not silently coerce.
Service trade not included. Comtrade and Census here are goods only. For services, use BEA-derived FRED series.
HS codes. The 4-digit HS heading is human-readable; 6-digit subheadings are more precise but verbose. comtrade_trade_data returns 6-digit commodity_codes by default.
trade_bilateral_analysis’s exchange_rates, us_trade_balance, and ranked top_commodities_imported are broken as of this writing — see “What a good answer looks like” above for the live evidence and filed task numbers (#136, #137). Use the manual path for those three pieces until fixed.

Use the prompt

prompts/get({
  name: "trade_exposure",
  arguments: { reporter: "842", partner: "156" }
})

Returns a substituted prompt that orchestrates a sequence and produces a forward-looking risk note (tariff exposure, supply-chain concentration, exchange-rate sensitivity) — but inherits the same trade_bilateral_analysis gaps described above if it leans on that tool internally.