Recipe: Trade exposure

This recipe builds a bilateral trade analysis between two countries — flows, top commodities by HS code, year-over-year shifts, and tariff revenue context — using the compound trade_bilateral_analysis tool.

Tools used: trade_bilateral_analysis (primary), comtrade_top_commodities and treasury_customs_revenue for drilldowns.

Calls: 1 (compound) for the headline brief; 2–3 for drilldowns.

Fast path

trade_bilateral_analysis({
  reporter_code: "842",  // United States
  partner_code:  "156"   // China
})

Returns:

{
  "reporter": { "code": "842", "name": "United States" },
  "partner":  { "code": "156", "name": "China" },
  "year": 2024,
  "imports_usd":     427_000_000_000,
  "exports_usd":     147_000_000_000,
  "trade_balance_usd": -280_000_000_000,
  "top_imports": [
    { "hs_code": "8517", "label": "Telephone sets", "value_usd": 51_400_000_000 },
    { "hs_code": "8471", "label": "Computers",       "value_usd": 38_900_000_000 },
    ...
  ],
  "top_exports": [...],
  "exchange_rate": { "pair": "USDCNY", "rate": 7.21, "as_of": "2025-04-30" },
  "_meta": { "sources": ["UN Comtrade", "Census Trade", "Treasury", "FRED"] }
}

One call wraps Comtrade flows, Census reciprocal data, and exchange-rate context.

Country code reference

The tool uses ISO 3-digit numeric country codes:

For other codes:

comtrade_country_codes({})
// → full list of reporter/partner codes

Manual path

// Comtrade flows
comtrade_trade_data({
  reporter_code: "842",
  partner_code:  "156",
  year: "2024",
  flow: "M"   // M = imports, X = exports
})

// Top commodities
comtrade_top_commodities({
  reporter_code: "842",
  partner_code:  "156",
  flow: "M"
})

// US-side mirror data (Census)
census_trade_balance({ partner: "China", year: 2024 })

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

// Exchange-rate context
get_exchange_rate({ from: "USD", to: "CNY" })

Citation pattern

US-China trade (2024): imports $427B, exports $147B, deficit $280B per UN Comtrade. Top imported categories: phones (HS 8517, $51.4B), computers (HS 8471, $38.9B). USDCNY closed 2024 at 7.21 (FRED DEXCHUS).

Use the prompt

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

Returns a substituted prompt that orchestrates the full sequence and produces a forward-looking risk note (tariff exposure, supply-chain concentration, exchange-rate sensitivity).

Caveats

• Comtrade data lags ~12 months. Most recent year is the last complete calendar year, not current.
• Reporter vs. partner asymmetry. Comtrade has both sides — they don’t perfectly match (different valuation methods). The tool defaults to reporter-side data; pass flow: "X" for the export view.
• Service trade not included. Comtrade is 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. Default is 4-digit.