io.github.Baneado98/freight-pulse

Official47 tools

by Baneado98 · Dockerfile

Ocean & multimodal freight intelligence: rates, landed cost, transit, customs, risk, ship decisions

freight-pulse 🚢 (MCP Server)

Ocean & multimodal freight intelligence suite for AI agents. This MCP server provides answers to shipping questions such as spot rates, total landed cost including duty, transit reliability, customs details, risk, emissions, and a unified ship decision. It exposes 47 tools to support importer, CFO, and supply-chain workflows.

🛠️ Key Features

Ocean & multimodal freight intelligence
Covers rates, landed cost, transit reliability, customs, risk, and emissions
Unified ship decision capability
47 tools for shipping data and calculations

🚀 Use Cases

“What’s the spot rate Shanghai → LA?”
“What’s my total landed cost with duty?”
“Should I book this lane now or wait?”

⚡ Developer Benefits

One MCP server providing responses across 47 tools
Cross-validated answers with a confidence read for shipping queries

⚠️ Limitations

Source description does not specify supported transport modes beyond ocean & multimodal, or any input/output schema details.

Captured live from the server via tools/list.

get_spot_rate

Get the CURRENT ocean container spot rate for a lane (origin port → destination port) so you can answer 'should I book this shipment now or wait?'. Returns ONE normalized USD figure for the requested container size, a CONFIDENCE SCORE, and the MARKET DIRECTION (rising / falling / stable). Unlike calling a single freight API, this CROSS-VALIDATES multiple live indices — Drewry's World Container Index (WCI) and the Freightos Baltic Index (FBX), read server-side, plus your own SeaRates key if you supply one — and reconciles them into a single number with an agreement/confidence read, so you know how much to trust it. Port names are normalized via UN/LOCODE: 'Shanghai', 'CNSHA' and 'Shanghai, China' all resolve to the same lane. Container types: 20ft, 40ft, 40HC (defaults to 40ft, the size the indices quote). FREE. Use it for transpacific (Shanghai/Ningbo/Yantian → Los Angeles/Long Beach/New York), Asia→Europe (→ Rotterdam/Hamburg/Genoa) and the other major deep-sea container lanes. For the weeks-long trend and a book-now-or-wait recommendation, use get_lane_trend. Indicative market intelligence, not a carrier quote.

Parameters3

origin_port	string	required	Origin port: a city name ('Shanghai', 'Ningbo', 'Rotterdam'), a UN/LOCODE ('CNSHA', 'NLRTM') or 'City, Country'.
dest_port	string	required	Destination port: a city name ('Los Angeles', 'New York', 'Hamburg'), a UN/LOCODE ('USLAX'), or 'City, Country'.
container_type	string	optional	Container size: '20ft', '40ft' or '40HC' (high-cube). Optional; defaults to '40ft' (the size the public indices quote). Synonyms like TEU/FEU/40HQ are accepted.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port: a city name ('Shanghai', 'Ningbo', 'Rotterdam'), a UN/LOCODE ('CNSHA', 'NLRTM') or 'City, Country'."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port: a city name ('Los Angeles', 'New York', 'Hamburg'), a UN/LOCODE ('USLAX'), or 'City, Country'."
    },
    "container_type": {
      "type": "string",
      "description": "Container size: '20ft', '40ft' or '40HC' (high-cube). Optional; defaults to '40ft' (the size the public indices quote). Synonyms like TEU/FEU/40HQ are accepted."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

get_lane_trend

Forecast the ocean spot rate for a lane (origin → destination) and get a grounded BOOK-NOW-OR-WAIT call for a given ship date. Returns: a weeks-long cross-validated time series; a STATISTICAL FORECAST several weeks ahead (Holt-Winters / ETS triple exponential smoothing) with prediction intervals that widen with the horizon, plus naïve/drift/seasonal-naïve baselines and an honest BACKTEST (MAPE/RMSE/MASE) of the forecast's accuracy; the ocean-freight SEASONALITY CALENDAR overlaid on your ship date (Chinese New Year pre-rush & post-slump, Golden Week, transpacific/Asia peak season, likely GRIs and blank-sailing pressure); ANOMALY detection (is today's rate an out-of-pattern spike or collapse vs its seasonal norm?); and a concrete book-now/book-soon/wait/split/monitor recommendation with the drivers shown. All of this runs server-side on freight-pulse's OWN accumulating per-lane history plus a curated freight-seasonality model — your own agent can't reproduce the forecast or the calendar from a single snapshot. Same port normalization as get_spot_rate (UN/LOCODE). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Without one you'll get unlock instructions. Tip: call get_spot_rate (free) on a lane first — it seeds the history. Indicative market intelligence, not a carrier quote.

Parameters5

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
weeks	number	optional	How many weeks of history to analyze (2–52, default 8). The window is capped by how much history we've accumulated for the lane.
ship_date	string	optional	The intended shipment date (ISO 'YYYY-MM-DD' or any parseable date). The seasonality calendar (CNY, peak season, GRIs, blank sailings) is evaluated for THIS date. Optional; defaults to today.
forecast_weeks	number	optional	How many weeks ahead to forecast the rate (1–26, default 6). Prediction intervals widen with the horizon.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "weeks": {
      "type": "number",
      "description": "How many weeks of history to analyze (2–52, default 8). The window is capped by how much history we've accumulated for the lane."
    },
    "ship_date": {
      "type": "string",
      "description": "The intended shipment date (ISO 'YYYY-MM-DD' or any parseable date). The seasonality calendar (CNY, peak season, GRIs, blank sailings) is evaluated for THIS date. Optional; defaults to today."
    },
    "forecast_weeks": {
      "type": "number",
      "description": "How many weeks ahead to forecast the rate (1–26, default 6). Prediction intervals widen with the horizon."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

get_all_in_rate

Get the ALL-IN ocean freight cost for a lane — the TRUE landed cost of the move, not just the base spot rate. get_spot_rate returns the index-blended BASE; this returns base + every applicable carrier SURCHARGE & accessorial, which routinely inflates the real cost by +30-60%. Models the opaque thicket importers actually pay: Terminal Handling (origin+destination), BAF/LSS bunker fuel (modeled from a marine-fuel proxy and the corridor's burn), CAF currency adjustment, Peak-Season Surcharge (only inside the seasonal peak window), a damped GRI residual, port Congestion surcharge, ISPS security, Documentation/B-L fee, ECA emissions, War-Risk / Red-Sea–Suez DIVERSION surcharge (only on Suez-exposed Asia↔Europe / Asia↔US-East lanes, higher when Cape-of-Good-Hope diverted), Panama Canal low-water surcharge (only on Panama-routed lanes), optional Overweight, and expected Demurrage & Detention (tiered escalating per-day cost past your free days). The engine knows WHICH route each lane follows (transpacific vs Suez vs Panama vs transatlantic) and applies ONLY the surcharges that actually bite that lane and ship date — and lists the ones it deliberately EXCLUDED and why. Returns the full line-item breakdown, the all-in total, and a base-vs-all-in comparison. Every figure is tagged 'typical' (representative published value) or 'modeled' (estimate) — these are indicative modeling values, not a carrier tariff. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters8

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
container_type	string	optional	Container size: '20ft', '40ft' or '40HC'. Optional; defaults to '40ft'.
ship_date	string	optional	Intended shipment date (ISO 'YYYY-MM-DD'). Drives Peak-Season Surcharge & GRI applicability. Optional; defaults to today.
free_days	number	optional	Carrier free days at destination before Demurrage & Detention accrues (default 5 when an estimated dwell is supplied).
estimated_days_at_port	number	optional	Total days you expect the box to sit at the destination terminal. If it exceeds free_days, the engine adds the expected (tiered, escalating) Demurrage & Detention. Omit to skip D&D.
overweight	boolean	optional	Flag an overweight load to include the overweight surcharge. Optional; default false.
fuel_proxy	number	optional	Optional live VLSFO marine-fuel price ($/tonne) to drive the BAF model. Omit to use a recent representative level (~$600/t, tagged modeled).

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "container_type": {
      "type": "string",
      "description": "Container size: '20ft', '40ft' or '40HC'. Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended shipment date (ISO 'YYYY-MM-DD'). Drives Peak-Season Surcharge & GRI applicability. Optional; defaults to today."
    },
    "free_days": {
      "type": "number",
      "description": "Carrier free days at destination before Demurrage & Detention accrues (default 5 when an estimated dwell is supplied)."
    },
    "estimated_days_at_port": {
      "type": "number",
      "description": "Total days you expect the box to sit at the destination terminal. If it exceeds free_days, the engine adds the expected (tiered, escalating) Demurrage & Detention. Omit to skip D&D."
    },
    "overweight": {
      "type": "boolean",
      "description": "Flag an overweight load to include the overweight surcharge. Optional; default false."
    },
    "fuel_proxy": {
      "type": "number",
      "description": "Optional live VLSFO marine-fuel price ($/tonne) to drive the BAF model. Omit to use a recent representative level (~$600/t, tagged modeled)."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

get_landed_cost

Get the full LANDED COST (cost puesto en destino) of an import — the number the importer's margin actually depends on, not just the freight. Returns merchandise value (FOB) + all-in ocean freight (base + every surcharge) + insurance (CIF) + CUSTOMS DUTY + import VAT/consumption tax, as a line-item breakdown, plus the % of landed cost that is freight vs duties vs taxes. Includes an HS-CODE CLASSIFIER: pass a product description ('bluetooth earbuds', 'office chairs', 'cotton t-shirts') and it proposes the most likely HS6 heading with a confidence score (and 2-3 candidates when the text is ambiguous), or pass an explicit hs_code. Duty is modeled per destination bloc (US HTS, EU TARIC, UK Global Tariff, Canada, Australia, Japan) with the right MFN rate for the product family, then the ORIGIN-SENSITIVE trade remedies: US Section 301 applied ONLY to China-origin goods, Section 232 on steel/aluminium, an ANTIDUMPING/CVD flag on high-risk family×origin combos (it warns, it does not invent a rate), and FTA PREFERENCE (EVFTA, USMCA, CETA, EU-Japan EPA, RCEP, …) when origin↔destination share an agreement — subject to rules of origin. De-minimis is handled (US $800, EU €150, …): below threshold → no duty/tax. Import VAT is computed on the correct CIF+duty base (EU VAT by country; the US has no federal import VAT). Every figure is tagged typical/modeled; this is an INDICATIVE landed-cost estimate and HS-classification aid, NOT a binding customs ruling. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters12

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). The origin COUNTRY drives Section 301 / FTA / antidumping.
dest_port	string	required	Destination port (city name, UN/LOCODE). The destination COUNTRY drives the duty bloc (US/EU/UK/CA/AU/JP) and import VAT.
product	string	optional	Product description to classify, e.g. 'bluetooth earbuds', 'office chairs', 'cotton t-shirts', 'car tyres'. The classifier maps it to an HS6 heading. Provide this OR hs_code.
hs_code	string	optional	Explicit HS code (6+ digits, e.g. '851830'). Overrides the text classifier. Provide this OR product.
fob_value	number	required	Merchandise value (FOB) in USD — the goods value at origin. REQUIRED: duties & taxes are computed on this (via CIF).
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' for the freight leg. Optional; defaults to '40ft'.
ship_date	string	optional	Intended ship date (ISO). Drives seasonal freight surcharges. Optional; defaults to today.
estimated_days_at_port	number	optional	Days the box will dwell at destination (adds Demurrage & Detention to the freight leg). Optional.
free_days	number	optional	Carrier free days before D&D (default 5 if a dwell is given).
overweight	boolean	optional	Flag an overweight load (freight surcharge). Optional.
fuel_proxy	number	optional	Optional VLSFO $/tonne for the BAF model. Optional.
insurance_rate_pct	number	optional	Marine insurance as a fraction of FOB+freight for the CIF model (default 0.005 = 0.5%). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). The origin COUNTRY drives Section 301 / FTA / antidumping."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE). The destination COUNTRY drives the duty bloc (US/EU/UK/CA/AU/JP) and import VAT."
    },
    "product": {
      "type": "string",
      "description": "Product description to classify, e.g. 'bluetooth earbuds', 'office chairs', 'cotton t-shirts', 'car tyres'. The classifier maps it to an HS6 heading. Provide this OR hs_code."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (6+ digits, e.g. '851830'). Overrides the text classifier. Provide this OR product."
    },
    "fob_value": {
      "type": "number",
      "description": "Merchandise value (FOB) in USD — the goods value at origin. REQUIRED: duties & taxes are computed on this (via CIF)."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' for the freight leg. Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO). Drives seasonal freight surcharges. Optional; defaults to today."
    },
    "estimated_days_at_port": {
      "type": "number",
      "description": "Days the box will dwell at destination (adds Demurrage & Detention to the freight leg). Optional."
    },
    "free_days": {
      "type": "number",
      "description": "Carrier free days before D&D (default 5 if a dwell is given)."
    },
    "overweight": {
      "type": "boolean",
      "description": "Flag an overweight load (freight surcharge). Optional."
    },
    "fuel_proxy": {
      "type": "number",
      "description": "Optional VLSFO $/tonne for the BAF model. Optional."
    },
    "insurance_rate_pct": {
      "type": "number",
      "description": "Marine insurance as a fraction of FOB+freight for the CIF model (default 0.005 = 0.5%). Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "fob_value"
  ]
}

compare_modes

Decide the TRANSPORT MODE for a shipment — OCEAN vs AIR vs SEA-AIR — on TOTAL economic cost, not just freight. The other tools price the ocean move; this one answers the importer's prior question: should these goods even go by sea? It costs all three modes and recommends the economically optimal one. Air is priced correctly on the IATA CHARGEABLE WEIGHT = max(actual gross weight, volumetric weight at 167 kg/m³) with an air fuel (FSC) + security (SSC) + handling stack — so bulky-but-light cargo is properly penalised (the lever a naïve 'air is just faster' estimate misses). Sea-air is modeled via the real hubs (Asia→Europe via Dubai/Jebel Ali, Asia→US-East via a US-West gateway): a cheap ocean leg to the hub + a short air final leg. The recommendation runs a real DECISION MODEL: cost of CAPITAL tied up in transit (value × annual rate × days), a p90 safety-stock HOLDING cost from each mode's variability, and — if you pass a deadline — an EXPECTED STOCKOUT cost from the probability the mode arrives late. So for high-value goods (or a tight deadline) air/sea-air can win even though the freight is far dearer, while for cheap goods ocean's much lower freight dominates. Returns the full ocean/air/sea-air table (freight, p50/p90 transit, capital, holding, stockout, total economic cost) + the recommended mode + the trade-off math. Every figure is modeled and tagged; air rates are volatile so they are honest BANDS, not a quote. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters17

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' for the ocean leg. Optional; defaults to '40ft'.
value	number	required	Merchandise value in USD — REQUIRED. It is the capital tied up in transit and the basis of the whole mode trade-off.
weight_kg	number	optional	Shipment gross weight in kg. Provide this and/or volume_m3 — air is billed on the chargeable weight (max of actual and volumetric).
volume_m3	number	optional	Shipment volume in cubic metres. Drives the IATA volumetric weight (m³ × 167 kg). Provide this and/or weight_kg.
deadline	string	optional	Optional hard arrival deadline (ISO 'YYYY-MM-DD'). If given, the engine adds an expected-stockout cost from each mode's probability of arriving late.
stockout_penalty	number	optional	USD penalty if the goods miss the deadline (lost sale / line-down / expedite). Defaults to the goods' value when a deadline is given without one. Optional.
annual_capital_rate_pct	number	optional	Annual cost-of-capital as a fraction (e.g. 0.12 = 12%/yr) for goods in transit. Optional; default 0.12.
annual_holding_rate_pct	number	optional	Annual inventory holding/carrying rate as a fraction (e.g. 0.25 = 25%/yr) for the p90 safety-stock buffer. Optional; default 0.25.
band	string	optional	Air/sea-air rate band to use: 'low', 'typical' or 'high'. Optional; default 'typical'.
jet_fuel_proxy	number	optional	Optional jet-fuel proxy to drive the air FSC. Omit for a modeled reference level.
ship_date	string	optional	Intended ship date (ISO). Drives the ocean seasonal surcharges & transit window. Optional; defaults to today.
estimated_days_at_port	number	optional	Days the box dwells at destination (adds D&D to the ocean freight leg). Optional.
free_days	number	optional	Carrier free days before D&D on the ocean leg (default 5 if a dwell is given). Optional.
overweight	boolean	optional	Flag an overweight ocean load (freight surcharge). Optional.
fuel_proxy	number	optional	Optional VLSFO $/tonne for the ocean BAF model. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' for the ocean leg. Optional; defaults to '40ft'."
    },
    "value": {
      "type": "number",
      "description": "Merchandise value in USD — REQUIRED. It is the capital tied up in transit and the basis of the whole mode trade-off."
    },
    "weight_kg": {
      "type": "number",
      "description": "Shipment gross weight in kg. Provide this and/or volume_m3 — air is billed on the chargeable weight (max of actual and volumetric)."
    },
    "volume_m3": {
      "type": "number",
      "description": "Shipment volume in cubic metres. Drives the IATA volumetric weight (m³ × 167 kg). Provide this and/or weight_kg."
    },
    "deadline": {
      "type": "string",
      "description": "Optional hard arrival deadline (ISO 'YYYY-MM-DD'). If given, the engine adds an expected-stockout cost from each mode's probability of arriving late."
    },
    "stockout_penalty": {
      "type": "number",
      "description": "USD penalty if the goods miss the deadline (lost sale / line-down / expedite). Defaults to the goods' value when a deadline is given without one. Optional."
    },
    "annual_capital_rate_pct": {
      "type": "number",
      "description": "Annual cost-of-capital as a fraction (e.g. 0.12 = 12%/yr) for goods in transit. Optional; default 0.12."
    },
    "annual_holding_rate_pct": {
      "type": "number",
      "description": "Annual inventory holding/carrying rate as a fraction (e.g. 0.25 = 25%/yr) for the p90 safety-stock buffer. Optional; default 0.25."
    },
    "band": {
      "type": "string",
      "description": "Air/sea-air rate band to use: 'low', 'typical' or 'high'. Optional; default 'typical'."
    },
    "jet_fuel_proxy": {
      "type": "number",
      "description": "Optional jet-fuel proxy to drive the air FSC. Omit for a modeled reference level."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO). Drives the ocean seasonal surcharges & transit window. Optional; defaults to today."
    },
    "estimated_days_at_port": {
      "type": "number",
      "description": "Days the box dwells at destination (adds D&D to the ocean freight leg). Optional."
    },
    "free_days": {
      "type": "number",
      "description": "Carrier free days before D&D on the ocean leg (default 5 if a dwell is given). Optional."
    },
    "overweight": {
      "type": "boolean",
      "description": "Flag an overweight ocean load (freight surcharge). Optional."
    },
    "fuel_proxy": {
      "type": "number",
      "description": "Optional VLSFO $/tonne for the ocean BAF model. Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "value"
  ]
}

procurement_strategy

Decide the OCEAN SOURCING STRATEGY for a lane over a YEAR — lock an annual/quarterly CONTRACT rate, stay on SPOT, or SPLIT — and in what proportion. This is the procurement/CFO decision the other tools don't touch: not 'book this box now' but 'how do I source my whole volume?'. It costs THREE strategies over your expected annual volume: 100% SPOT, 100% CONTRACT, and the OPTIMAL MIX. The spot side is a real DISTRIBUTION, not a mean: it builds a 52-week expected-spot path from our own forecast (Holt-Winters), the corridor's spot volatility and the seasonal calendar, so a peak-season spike shows up as a fat P95 TAIL. It reads the MARKET REGIME (soft / balanced / tight / extreme) — because the contract↔spot relationship FLIPS with the cycle: in a soft market a contract sits ABOVE cheap spot (you'd overpay), in a tight market spot spikes above contract (the contract PROTECTS you). It computes the BREAK-EVEN contract rate (where 100% contract beats expected 100% spot), optimizes the contract/spot MIX on a mean-variance objective for your risk tolerance (contract the steady base, leave the peak on spot), models MQC shortfall penalties (the cost of over-committing in a light year) and the loading-PRIORITY a contract buys (less peak rollover), and quantifies the VALUE OF PROTECTION in dollars. Honest by design (regla 7): the contract↔spot relationship is regime-dependent and uncertain, so contract rates are MODELED BANDS anchored to the lane's mid-cycle — NOT a filed carrier tariff. Pass your own offered contract rate to score it against break-even. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters9

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
annual_volume	number	required	Expected ANNUAL volume in containers of this type (TEU-equivalent ok) — REQUIRED. It is the basis of the contract-vs-spot trade-off.
risk_tolerance	string	optional	'low' (pay to avoid the tail → favors contract), 'medium' (default), or 'high' (chase the mean → favors spot). Sets the mean-variance λ.
contract_rate_offered	number	optional	An actual contract rate you've been offered (USD/container). If given, it is scored against break-even instead of using the modeled band. Optional.
volume_cv	number	optional	Relative std-dev of YOUR annual volume (e.g. 0.2 = ±20%), driving MQC shortfall risk. Optional; default 0.20.
ship_date	string	optional	Ship-date / contract-start anchor (ISO 'YYYY-MM-DD') for the seasonal & forecast overlay. Optional; defaults to today.
weeks	number	optional	Weeks of lane history to analyze for the forecast & mid-cycle reference (4–52, default 16). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'."
    },
    "annual_volume": {
      "type": "number",
      "description": "Expected ANNUAL volume in containers of this type (TEU-equivalent ok) — REQUIRED. It is the basis of the contract-vs-spot trade-off."
    },
    "risk_tolerance": {
      "type": "string",
      "description": "'low' (pay to avoid the tail → favors contract), 'medium' (default), or 'high' (chase the mean → favors spot). Sets the mean-variance λ."
    },
    "contract_rate_offered": {
      "type": "number",
      "description": "An actual contract rate you've been offered (USD/container). If given, it is scored against break-even instead of using the modeled band. Optional."
    },
    "volume_cv": {
      "type": "number",
      "description": "Relative std-dev of YOUR annual volume (e.g. 0.2 = ±20%), driving MQC shortfall risk. Optional; default 0.20."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship-date / contract-start anchor (ISO 'YYYY-MM-DD') for the seasonal & forecast overlay. Optional; defaults to today."
    },
    "weeks": {
      "type": "number",
      "description": "Weeks of lane history to analyze for the forecast & mid-cycle reference (4–52, default 16). Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "annual_volume"
  ]
}

get_port_intel

Get the PORT-CONGESTION & DISRUPTION intelligence for a lane — the OPERATIONAL state of the origin and destination ports and the live disruption events that move your transit time and your price. The rate tools tell you what a move costs; this tells you whether the PORTS can actually clear it on schedule. Returns a 0-100 CONGESTION INDEX for both the origin and destination ports on your ship date (structural berth/anchorage pressure + seasonal peak + active disruptions), the extra WAITING DAYS that congestion tacks onto your p90 transit, a 0-100 lane OPERATIONAL-RISK score with a building / steady / easing trend, and the upward RATE PRESSURE it implies. It surfaces the ACTIVE DISRUPTIONS that bite THIS lane on THIS date — the Red-Sea / Bab-el-Mandeb diversion around the Cape of Good Hope, the Panama Canal drought (draft & transit-slot restrictions on Panama-routed lanes), US West-Coast ILWU and US East/Gulf ILA dockworker labour cycles, the Asia typhoon season (Jun-Oct) and Atlantic hurricane season (Jun-Nov), and peak-season demand congestion — each with its time window, day-impact and rate pressure, and a flag for whether it's in its ACUTE window or only a recurring-season risk. A disruption OUTSIDE its window is not applied. Built on ~35 curated major-port congestion profiles (Shanghai, Ningbo, Yantian, Singapore, Busan, LA/Long Beach, NY/NJ, Savannah, Houston, Rotterdam, Hamburg, Antwerp, Felixstowe, Jebel Ali, …) and a dated catalogue of real disruption events — so a congestion wave that's BUILDING into your wait window can nudge you to anticipate and book. Every figure is a MODELED structural typical + a dated disruption overlay; it is INDICATIVE, NOT a live waiting-time feed for a specific port today (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters4

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (informational for the lane label). Optional; defaults to '40ft'.
ship_date	string	optional	Intended ship date (ISO 'YYYY-MM-DD'). The congestion peak windows and dated disruptions (Panama drought, ILA strike, typhoon/hurricane season, Red-Sea diversion) are evaluated for THIS date. Optional; defaults to today.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (informational for the lane label). Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO 'YYYY-MM-DD'). The congestion peak windows and dated disruptions (Panama drought, ILA strike, typhoon/hurricane season, Red-Sea diversion) are evaluated for THIS date. Optional; defaults to today."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

carrier_recommendation

Recommend WHICH CARRIER or ALLIANCE to sail with on a lane — the shipper's third decision after 'when to book' and 'which mode'. Carriers and their alliances differ enormously by corridor in coverage, schedule reliability and network breadth, so this ranks the ones that actually serve YOUR corridor and recommends 2-3 with the reasoning. Models the 2025-26 alliance realignment (NOT the pre-2025 map): GEMINI COOPERATION (Maersk + Hapag-Lloyd, live Feb 2025, a hub-and-spoke model explicitly targeting >90% on-time), OCEAN ALLIANCE (CMA CGM + COSCO + Evergreen + OOCL — the broadest direct-call network & highest frequency), PREMIER ALLIANCE (ONE + HMM + Yang Ming, the former THE Alliance minus Hapag, strong transpacific), and MSC operating standalone (the world's largest fleet, vast breadth, selective slot deals) — plus niche independents (ZIM's Asia→US-East express, Wan Hai intra-Asia). For each option it returns the EXPECTED ON-TIME PERFORMANCE on this lane (the corridor's market OTP refined by the carrier's own reliability band and how much it governs the string — so Gemini surfaces ~90% vs ~55% market average on Asia-Europe), the estimated SAILING FREQUENCY (sailings/week) and network breadth, a cost-positioning read, an overall fit SCORE, and the trade-off. The ranking FLIPS with your PRIORITY: 'reliability' floats Gemini up; 'frequency' or 'cost' floats Ocean Alliance / MSC up; a carrier with no network on the corridor is NOT recommended there. It also REFINES the lane OTP to the top pick so you can feed it into your p90 lead-time buffer. Every figure is a MODELED INDICATIVE BAND (capacity shares ~Alphaliner picture, reliability ~Sea-Intelligence rankings, corridor strengths) — NOT a carrier quote, a filed tariff or a weekly KPI (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters5

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
priority	string	optional	What the shipper optimizes for: 'reliability' (on-time, favours Gemini), 'frequency' (sailings/week, favours Ocean/MSC), 'cost' (cheapest-leaning), or 'balanced' (default). Synonyms accepted.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (informational for the lane label). Optional; defaults to '40ft'.
ship_date	string	optional	Intended ship date (ISO 'YYYY-MM-DD'). Sets the corridor's market-baseline OTP (Cape diversion + seasonal blank-sailing pressure) the ranking is refined from. Optional; defaults to today.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "priority": {
      "type": "string",
      "description": "What the shipper optimizes for: 'reliability' (on-time, favours Gemini), 'frequency' (sailings/week, favours Ocean/MSC), 'cost' (cheapest-leaning), or 'balanced' (default). Synonyms accepted."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (informational for the lane label). Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO 'YYYY-MM-DD'). Sets the corridor's market-baseline OTP (Cape diversion + seasonal blank-sailing pressure) the ranking is refined from. Optional; defaults to today."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

carbon_footprint

Compute the CO2e CARBON FOOTPRINT of a shipment and the EU-ETS carbon COST for a lane — the Scope-3 (upstream transport) number importers increasingly must report, and the maritime carbon cost they now must pay on EU-touching lanes. The rate tools price the money; this prices the CARBON. Returns the WELL-TO-WAKE (WTW) kg CO2e of the move computed the GLEC Framework / ISO 14083 way — grams CO2e per TONNE-KILOMETRE × the routed distance × the cargo mass — with a per-LEG breakdown (drayage + main sea/air leg) and the well-to-tank vs tank-to-wake split that reporting frameworks ask for. Ocean intensity is taken by VESSEL CLASS (a ULCV moves a tonne-km for a fraction of a feeder's gCO2e/t-km — the economy-of-scale effect a naïve estimate misses); the engine picks the corridor's mainline class and lengthens the sea distance when a lane is Cape-of-Good-Hope diverted (more km → more CO2e). It puts the THREE modes side by side — OCEAN vs AIR vs SEA-AIR — on the same lane & cargo, surfacing that air emits roughly 10-50× the ocean footprint per tonne-km (the central ESG-vs-speed trade-off, linking to compare_modes), with sea-air as the carbon-smart middle. For lanes that touch an EU/EEA port it computes the EU-ETS maritime carbon COST: the voyage CO2 in scope (100% intra-EU, 50% for an EU↔non-EU voyage) × the year's phase-in (2024 40% → 2025 70% → 2026 100%) × the EUA market price — the surcharge carriers now pass to cargo. A lane that doesn't touch the EU (e.g. Asia→US) is correctly OUT of scope (no ETS). It also clarifies FuelEU Maritime and — honestly — that CBAM taxes the PRODUCT's embedded carbon, NOT the freight (the confusion importers keep making). Every emission factor and the EUA price are MODELED bands tagged typical/modeled (regla 7) — indicative footprinting & carbon-cost modeling, NOT an audited per-vessel carbon statement or a filed surcharge. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters9

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate. The origin COUNTRY drives EU-ETS scope.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country'). The destination COUNTRY drives EU-ETS scope (touching the EU/EEA brings the voyage into scope).
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'. Drives the modeled typical laden cargo mass when no weight is given.
ship_date	string	optional	Intended ship date (ISO 'YYYY-MM-DD'). The YEAR drives the EU-ETS phase-in (2024 40%, 2025 70%, 2026+ 100%). Optional; defaults to today.
weight_kg	number	optional	Actual cargo gross weight in kg. Strongly recommended — emissions are per tonne-km, so the real mass sharpens the footprint and the EU-ETS cost. If omitted, a modeled typical laden mass for the container is used.
volume_m3	number	optional	Shipment volume in m³. Used for the AIR mode's IATA chargeable mass (max of actual and volumetric @167 kg/m³). Optional.
band	string	optional	Emission-factor band to report: 'low', 'typical' or 'high'. Optional; default 'typical' (factors are honest bands, not a single audited number).
eua_price_eur	number	optional	Override the EUA (EU Allowance) market price in €/tonne for the EU-ETS cost. Optional; defaults to a modeled typical (~€75) within a €55-100 band.
air_role	string	optional	Air emission factor role: 'freighter' (default, higher intensity) or 'belly' (passenger-jet hold, lower allocation). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate. The origin COUNTRY drives EU-ETS scope."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country'). The destination COUNTRY drives EU-ETS scope (touching the EU/EEA brings the voyage into scope)."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'. Drives the modeled typical laden cargo mass when no weight is given."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO 'YYYY-MM-DD'). The YEAR drives the EU-ETS phase-in (2024 40%, 2025 70%, 2026+ 100%). Optional; defaults to today."
    },
    "weight_kg": {
      "type": "number",
      "description": "Actual cargo gross weight in kg. Strongly recommended — emissions are per tonne-km, so the real mass sharpens the footprint and the EU-ETS cost. If omitted, a modeled typical laden mass for the container is used."
    },
    "volume_m3": {
      "type": "number",
      "description": "Shipment volume in m³. Used for the AIR mode's IATA chargeable mass (max of actual and volumetric @167 kg/m³). Optional."
    },
    "band": {
      "type": "string",
      "description": "Emission-factor band to report: 'low', 'typical' or 'high'. Optional; default 'typical' (factors are honest bands, not a single audited number)."
    },
    "eua_price_eur": {
      "type": "number",
      "description": "Override the EUA (EU Allowance) market price in €/tonne for the EU-ETS cost. Optional; defaults to a modeled typical (~€75) within a €55-100 band."
    },
    "air_role": {
      "type": "string",
      "description": "Air emission factor role: 'freighter' (default, higher intensity) or 'belly' (passenger-jet hold, lower allocation). Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

equipment_availability

Check whether the shipper can even GET A CONTAINER on a lane — and what the equipment imbalance costs — BEFORE pricing the move. The rate tools assume a box exists; this answers the constraint that often binds first: in a deficit origin you can have a rate and a sailing and still not secure a box. Returns a 0-100 AVAILABILITY INDEX for the empty box at the origin and a SHORTAGE-RISK score, driven by the structural EQUIPMENT IMBALANCE of container trade: trade is directional, so empties PILE UP at net-importer ports (LA/Long Beach, Rotterdam, Hamburg) and run SHORT at net-exporter hubs (north/central China, Vietnam) — carriers must reposition empties back against the loaded headhaul. It models the balance per TYPE: 40HC (the deep-sea workhorse) is the tightest dry type in a crunch, 20DV is structurally easier to source (the classic alternative), and REEFER is a separate, far scarcer, plug-limited pool. It overlays the SEASONAL swing on the real lunar calendar: the acute PRE-CHINESE-NEW-YEAR crunch (every exporter loads before the factory shutdown — equipment, not space, becomes the binding constraint), the POST-CNY glut (the empties that surged out sit stranded at destinations while China demand collapses), Golden-Week front-loading, and peak-season tightening — evaluated for YOUR ship date. It prices the EQUIPMENT-IMBALANCE SURCHARGE (EIS) and reposition cost the deficit imposes, plus the soft +% it pushes onto the effective booked rate, and lists the reposition INCENTIVES (triangulation/street-turn, fast empty return) that relieve it. When the requested box is short it proposes ALTERNATIVES — split a scarce 40HC into 2×20DV, shift the ship window out of the crunch, triangulate an import empty, or book a mega-fleet carrier (Maersk/MSC/CMA CGM) whose deep own-box pool and local depots ease the SAME deficit (a thin niche line is more exposed). Pass a carrier to refine the numbers. The shortage risk also feeds the book-now timing — a worsening crunch means anticipate and lock equipment early. Everything is a MODELED structural + seasonal profile expressed as honest bands — NOT a live depot inventory; we never claim a specific box count is available at a depot today (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters7

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country'). The origin REGION's net export/import role drives the equipment deficit/surplus.
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country'). The destination is where empties pile up (the reposition-from side).
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' — maps to the 20DV / 40DV / 40HC equipment pool. Optional; defaults to '40ft'. Use 'reefer' for refrigerated.
reefer	boolean	optional	Set true for a REEFER (refrigerated) move — a separate, far scarcer, plug-limited pool than dry. Optional; default false.
ship_date	string	optional	Intended ship date (ISO 'YYYY-MM-DD'). The seasonal equipment swing (pre-CNY crunch, post-CNY glut, Golden Week, peak tightening) is evaluated for THIS date. Optional; defaults to today.
carrier	string	optional	Optional carrier to refine availability by its own-box fleet & depot depth (e.g. 'Maersk', 'MSC', 'CMA CGM', 'ZIM'). A mega line eases the crunch; a thin niche line is more exposed.
band	string	optional	EIS / reposition-cost band to report: 'low', 'typical' or 'high'. Optional; default 'typical'.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country'). The origin REGION's net export/import role drives the equipment deficit/surplus."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country'). The destination is where empties pile up (the reposition-from side)."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' — maps to the 20DV / 40DV / 40HC equipment pool. Optional; defaults to '40ft'. Use 'reefer' for refrigerated."
    },
    "reefer": {
      "type": "boolean",
      "description": "Set true for a REEFER (refrigerated) move — a separate, far scarcer, plug-limited pool than dry. Optional; default false."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO 'YYYY-MM-DD'). The seasonal equipment swing (pre-CNY crunch, post-CNY glut, Golden Week, peak tightening) is evaluated for THIS date. Optional; defaults to today."
    },
    "carrier": {
      "type": "string",
      "description": "Optional carrier to refine availability by its own-box fleet & depot depth (e.g. 'Maersk', 'MSC', 'CMA CGM', 'ZIM'). A mega line eases the crunch; a thin niche line is more exposed."
    },
    "band": {
      "type": "string",
      "description": "EIS / reposition-cost band to report: 'low', 'typical' or 'high'. Optional; default 'typical'."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

incoterm_responsibility

Explain the EXACT cost & risk split between the SELLER (exporter) and the BUYER (importer) for an Incoterms® 2020 rule on a lane — the decision an importer makes when they agree 'FOB Shanghai' vs 'DDP my-warehouse', which a thin agent routinely gets wrong. Returns the precise POINT at which risk of loss/damage transfers (EXW at the seller's works; FCA/CPT/CIP at the first-carrier hand-over; FAS alongside the ship; FOB/CFR/CIF once ON BOARD; DAP/DDP at destination ready; DPU once unloaded), who pays each step (export clearance, origin haulage, the main international freight, destination terminal handling, on-carriage, import clearance, and the destination DUTY + import VAT/tax), and whether the rule MANDATES cargo insurance and at what level (CIF mandates only ICC C minimum; CIP mandates ICC A all-risk). It flags the classic traps: FOB/CFR/CPT put the TRANSIT RISK on the buyer (CFR/CPT even though the seller pays the freight); DDP loads the seller with destination customs and import VAT; EXW puts export clearance on the buyer; and FOB on CONTAINERS is the wrong rule (the ICC recommends FCA for terminal hand-over) — with a container-appropriateness warning. Indicative summary of the ICC rules — NOT legal, contractual or customs advice (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters5

origin_port	string	required	Origin/load port (city, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination/delivery port (city, UN/LOCODE, or 'City, Country').
incoterm	string	required	The Incoterms 2020 rule to analyse: one of EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP. REQUIRED.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (drives the container-appropriateness check). Optional; defaults to '40ft'.
product	string	optional	Optional product description (informational context only).

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin/load port (city, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination/delivery port (city, UN/LOCODE, or 'City, Country')."
    },
    "incoterm": {
      "type": "string",
      "description": "The Incoterms 2020 rule to analyse: one of EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP. REQUIRED."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (drives the container-appropriateness check). Optional; defaults to '40ft'."
    },
    "product": {
      "type": "string",
      "description": "Optional product description (informational context only)."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "incoterm"
  ]
}

required_documents

Produce the CHECKLIST of trade documents a shipment of THESE goods to THIS destination commonly needs — the paperwork that, if missed, gets the box fined, held or the duty overpaid. Returns the always-on commercial set (commercial invoice, packing list, Bill of Lading or Sea Waybill), the GOODS-TRIGGERED specials (lithium-battery Dangerous-Goods declaration for electronics/batteries, Safety Data Sheet + DG for chemicals, ISPM-15 wood treatment / phytosanitary for furniture/wood, textile & origin declarations for apparel/footwear), the DESTINATION import-regime filings (US Importer Security Filing ISF 10+2 — filed ≥24h before loading, $5,000 penalty if late; EU Entry Summary Declaration ENS via ICS2; UK Safety & Security), and the Certificate of Origin (recommended, and REQUIRED in preferential form to claim a reduced FTA duty rate). Pass a product description (it's classified to an HS family to trigger the right specials) or an explicit hs_code; without it you still get the core + destination set. Pass an Incoterm to tag each document with WHO is responsible under it (e.g. under DDP the seller files the import-side ISF). Indicative common-case checklist — NOT a customs broker's binding filing list (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters6

origin_port	string	required	Origin port (city, UN/LOCODE, or 'City, Country'). The origin country drives the certificate-of-origin / FTA note.
dest_port	string	required	Destination port (city, UN/LOCODE). The destination country drives which advance filing applies (US ISF, EU ENS, UK S&S).
product	string	optional	Product description, e.g. 'bluetooth earbuds', 'office chairs', 'cotton t-shirts' — classified to trigger goods-specific docs (DG, ISPM-15, textile). Provide this OR hs_code.
hs_code	string	optional	Explicit HS code (overrides the text classifier). Provide this OR product.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (informational). Optional; defaults to '40ft'.
incoterm	string	optional	Optional Incoterms 2020 rule to tag responsibilities (EXW…DDP).

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city, UN/LOCODE, or 'City, Country'). The origin country drives the certificate-of-origin / FTA note."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city, UN/LOCODE). The destination country drives which advance filing applies (US ISF, EU ENS, UK S&S)."
    },
    "product": {
      "type": "string",
      "description": "Product description, e.g. 'bluetooth earbuds', 'office chairs', 'cotton t-shirts' — classified to trigger goods-specific docs (DG, ISPM-15, textile). Provide this OR hs_code."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (overrides the text classifier). Provide this OR product."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (informational). Optional; defaults to '40ft'."
    },
    "incoterm": {
      "type": "string",
      "description": "Optional Incoterms 2020 rule to tag responsibilities (EXW…DDP)."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

dnd_strategy

Optimize the DEMURRAGE & DETENTION free-time strategy for a destination — beyond the simple D&D line: how many FREE DAYS should you negotiate, and what is the EXPECTED D&D cost of accepting fewer, given how long the box will actually DWELL at this (possibly congested) port? It reads the destination port's CONGESTION on your ship date and builds a DWELL DISTRIBUTION (mean + the right tail that a busy port fattens), then for a ladder of candidate free-day grants computes the PROBABILITY of breaching free time (incurring any D&D), the EXPECTED chargeable days, the EXPECTED D&D cost (on the destination region's tiered, escalating per-day schedule — US West-Coast steep, North-Europe gentler) and the p90 bad-case cost. It finds the marginal value of each extra free day and recommends a free-day TARGET — 'in this congested port the dwell tail is fat, so the default 4-5 free days carries $X expected D&D; negotiate 7+'. Demurrage (box sits FULL in the terminal) and detention (box held OUTSIDE past the empty-return grace) are modeled together as combined free time. Pass a carrier to refine the default grant, or your own mean dwell if you know your unpack speed. Modeled from industry-typical regional free days + a congestion-driven dwell distribution — NOT a carrier's filed free-time tariff (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters8

origin_port	string	required	Origin port (city, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port — its congestion drives the dwell distribution and the regional D&D schedule.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (drives the per-day D&D rate). Optional; defaults to '40ft'.
ship_date	string	optional	Intended ship date (ISO 'YYYY-MM-DD'). The destination congestion (peak windows, disruptions) is evaluated for THIS date. Optional; defaults to today.
carrier	string	optional	Optional carrier — refines the default free-day grant (mega lines often grant a touch more).
mean_dwell_days	number	optional	Override the modeled mean dwell (days) with your own unpack/return speed. Optional.
min_free_days	number	optional	Lowest free-day grant to evaluate (default 3).
max_free_days	number	optional	Highest free-day grant to evaluate (default 10 or default+4).

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port — its congestion drives the dwell distribution and the regional D&D schedule."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (drives the per-day D&D rate). Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO 'YYYY-MM-DD'). The destination congestion (peak windows, disruptions) is evaluated for THIS date. Optional; defaults to today."
    },
    "carrier": {
      "type": "string",
      "description": "Optional carrier — refines the default free-day grant (mega lines often grant a touch more)."
    },
    "mean_dwell_days": {
      "type": "number",
      "description": "Override the modeled mean dwell (days) with your own unpack/return speed. Optional."
    },
    "min_free_days": {
      "type": "number",
      "description": "Lowest free-day grant to evaluate (default 3)."
    },
    "max_free_days": {
      "type": "number",
      "description": "Highest free-day grant to evaluate (default 10 or default+4)."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

insurance_recommendation

Recommend cost-effective MARINE CARGO INSURANCE for a shipment — the cover an importer needs but often under-buys. It prices the three Institute Cargo Clauses side by side: ICC (A) ALL-RISK (covers everything bar named exclusions — for valuable/fragile/theft-prone cargo), ICC (B) named-perils-broad (adds water-ingress but NOT theft), and ICC (C) MINIMUM (only major vessel casualties — no water, no theft) — showing what each COVERS and EXCLUDES. The premium = INSURED VALUE (CIF + 10% customary markup, the freight pulled server-side so the base is real) × the cargo's LOSS PROFILE (electronics/batteries load the rate; robust steel discounts it) × the MODE risk (air has a structurally lower loss rate than ocean — links to compare_modes) × the ROUTE risk (a Red-Sea/Cape-diverted lane spikes the separate WAR-RISK additional premium — links to the disruptions engine) × the deductible. It recommends the cost-effective cover level for your cargo and clarifies the Incoterms tie: CIF obliges the seller to buy only ICC (C) minimum, CIP obliges ICC (A) all-risk, and a FOB/CFR/CPT buyer gets NO seller insurance at all (must self-arrange). Modeled market-typical bands — NOT a broker's quote (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters10

origin_port	string	required	Origin port (city, UN/LOCODE, or 'City, Country'). The route (incl. Red-Sea diversion) drives the war-risk premium.
dest_port	string	required	Destination port (city, UN/LOCODE, or 'City, Country').
cargo_value	number	required	Merchandise value (USD) — REQUIRED. The insured value is CIF (cargo + freight) + 10%.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (for the freight leg). Optional; defaults to '40ft'.
product	string	optional	Product description to classify the cargo loss profile (e.g. 'bluetooth earbuds', 'steel coils'). Optional but improves the rate.
hs_code	string	optional	Explicit HS code (alternative to product). Optional.
mode	string	optional	Transport mode for the loss profile: 'ocean' (default), 'air' (lower loss rate) or 'sea-air'. Optional.
deductible_fraction	number	optional	Policy deductible as a fraction of insured value (0 = nil, 0.005 = 0.5% typical, 0.01, 0.02). A higher excess lowers the premium. Optional.
ship_date	string	optional	Intended ship date (ISO). Optional; defaults to today.
markup_pct	number	optional	Insured-value markup over CIF (default 0.10 = the customary +10%). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city, UN/LOCODE, or 'City, Country'). The route (incl. Red-Sea diversion) drives the war-risk premium."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city, UN/LOCODE, or 'City, Country')."
    },
    "cargo_value": {
      "type": "number",
      "description": "Merchandise value (USD) — REQUIRED. The insured value is CIF (cargo + freight) + 10%."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (for the freight leg). Optional; defaults to '40ft'."
    },
    "product": {
      "type": "string",
      "description": "Product description to classify the cargo loss profile (e.g. 'bluetooth earbuds', 'steel coils'). Optional but improves the rate."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (alternative to product). Optional."
    },
    "mode": {
      "type": "string",
      "description": "Transport mode for the loss profile: 'ocean' (default), 'air' (lower loss rate) or 'sea-air'. Optional."
    },
    "deductible_fraction": {
      "type": "number",
      "description": "Policy deductible as a fraction of insured value (0 = nil, 0.005 = 0.5% typical, 0.01, 0.02). A higher excess lowers the premium. Optional."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO). Optional; defaults to today."
    },
    "markup_pct": {
      "type": "number",
      "description": "Insured-value markup over CIF (default 0.10 = the customary +10%). Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "cargo_value"
  ]
}

ship_decision

The UNIFIED decision tool — integrates EVERY freight-pulse layer (rate/forecast, all-in cost, transit & reliability, mode-choice, procurement, port congestion, carrier/alliance, emissions, equipment availability, Incoterms, demurrage & detention, and cargo insurance) into ONE actionable answer for a CONCRETE shipment. This is the tool that makes freight-pulse insustituible: it doesn't just price one layer, it WEIGHS them all coherently. Give the lane + merchandise value (+ optional weight/volume, ship date, urgency, deadline, product, Incoterm, carrier) and it returns: the recommended MODE (urgency-aware — a critical deadline can override the economic optimum toward air/sea-air), the recommended CARRIER for the corridor, the book-now / book-soon / wait / monitor TIMING (the forecast call, overlaid with a building congestion/equipment crunch), the total COST PUESTO EN DESTINO (landed: goods + freight + duty + import tax, when a product is given), and the KEY RISKS with concrete MITIGATIONS (Red-Sea diversion, port congestion, equipment scarcity, D&D exposure, transit-risk insurance). Every component is computed by its own modeled engine and folded in transparently (the breakdown is shown). Indicative decision support — not a booking or a quote (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters14

origin_port	string	required	Origin port (city, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port (city, UN/LOCODE, or 'City, Country').
value	number	required	Merchandise value (USD) — REQUIRED. Drives mode-choice (capital in transit), insurance and (with a product) landed cost.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
weight_kg	number	optional	Shipment gross weight (kg) — sharpens mode-choice (air chargeable weight) and emissions. Optional.
volume_m3	number	optional	Shipment volume (m³) — drives the air volumetric weight. Optional.
product	string	optional	Product description or HS context — enables the landed-cost (duty) component. Optional.
hs_code	string	optional	Explicit HS code (alternative to product). Optional.
urgency	string	optional	'relaxed', 'normal' (default), 'urgent' or 'critical'. A critical/urgent shipment shifts the recommendation toward speed (air/sea-air) and a reliability-led carrier.
deadline	string	optional	Hard arrival deadline (ISO 'YYYY-MM-DD') — adds an expected-stockout cost to the mode decision. Optional.
ship_date	string	optional	Intended ship date (ISO). Drives seasonality, congestion and the book-now call. Optional; defaults to today.
incoterm	string	optional	Optional Incoterms 2020 rule (EXW…DDP) — sets who carries transit risk in the risk assessment.
carrier	string	optional	Optional preferred carrier (refines equipment & D&D).
annual_volume	number	optional	Optional annual volume (containers) — informational for the decision context.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city, UN/LOCODE, or 'City, Country')."
    },
    "value": {
      "type": "number",
      "description": "Merchandise value (USD) — REQUIRED. Drives mode-choice (capital in transit), insurance and (with a product) landed cost."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'."
    },
    "weight_kg": {
      "type": "number",
      "description": "Shipment gross weight (kg) — sharpens mode-choice (air chargeable weight) and emissions. Optional."
    },
    "volume_m3": {
      "type": "number",
      "description": "Shipment volume (m³) — drives the air volumetric weight. Optional."
    },
    "product": {
      "type": "string",
      "description": "Product description or HS context — enables the landed-cost (duty) component. Optional."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (alternative to product). Optional."
    },
    "urgency": {
      "type": "string",
      "description": "'relaxed', 'normal' (default), 'urgent' or 'critical'. A critical/urgent shipment shifts the recommendation toward speed (air/sea-air) and a reliability-led carrier."
    },
    "deadline": {
      "type": "string",
      "description": "Hard arrival deadline (ISO 'YYYY-MM-DD') — adds an expected-stockout cost to the mode decision. Optional."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO). Drives seasonality, congestion and the book-now call. Optional; defaults to today."
    },
    "incoterm": {
      "type": "string",
      "description": "Optional Incoterms 2020 rule (EXW…DDP) — sets who carries transit risk in the risk assessment."
    },
    "carrier": {
      "type": "string",
      "description": "Optional preferred carrier (refines equipment & D&D)."
    },
    "annual_volume": {
      "type": "number",
      "description": "Optional annual volume (containers) — informational for the decision context."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "value"
  ]
}

simulate_scenario

Run a WHAT-IF on a lane: recompute the COST and TIME impact of a structural change to the freight market, on top of freight-pulse's engines. Scenarios: 'red-sea-reopen' (Suez/Bab-el-Mandeb reopens and Asia-Europe / the Suez share of Asia-US-East services return from the Cape-of-Good-Hope diversion → shorter transit, war-risk & diversion surcharges fall — only material on Suez-exposed lanes); 'fuel-spike' (bunker VLSFO up X% → the BAF/bunker portion of the all-in rises; pass fuel_spike_pct); 'cny' (Chinese New Year front-loading: the pre-CNY rush spikes the spot rate and the equipment crunch and dips schedule reliability — material on China-origin lanes); 'tariff-change' (destination duty changes by X percentage points — e.g. a new Section-301 tranche or an FTA change — raising/lowering the landed cost while freight is UNCHANGED; pass tariff_delta_pp and value). It recomputes the affected engine outputs under the perturbed inputs it can thread (fuel proxy, ship date) and models the structural ones (the Red-Sea routing flag, a tariff delta) as explicit, transparent adjustments — never silently — and reports the baseline, the scenario and the deltas. A what-if is a MODELED counterfactual, not a prediction the event will occur (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.

Parameters8

origin_port	string	required	Origin port (city, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port (city, UN/LOCODE, or 'City, Country').
scenario	string	required	The what-if: 'red-sea-reopen', 'fuel-spike', 'cny' or 'tariff-change'. REQUIRED.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
ship_date	string	optional	Intended ship date (ISO). Drives the CNY-year and the baseline all-in. Optional; defaults to today.
fuel_spike_pct	number	optional	For 'fuel-spike': percent increase in VLSFO bunker (e.g. 30 = +30%). Default 30.
tariff_delta_pp	number	optional	For 'tariff-change': change in duty in PERCENTAGE POINTS (e.g. 10 = +10pp, -5 = a cut). Default 10.
value	number	optional	For 'tariff-change': merchandise value (USD) to size the duty/landed impact. Default 50000.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city, UN/LOCODE, or 'City, Country')."
    },
    "scenario": {
      "type": "string",
      "description": "The what-if: 'red-sea-reopen', 'fuel-spike', 'cny' or 'tariff-change'. REQUIRED."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO). Drives the CNY-year and the baseline all-in. Optional; defaults to today."
    },
    "fuel_spike_pct": {
      "type": "number",
      "description": "For 'fuel-spike': percent increase in VLSFO bunker (e.g. 30 = +30%). Default 30."
    },
    "tariff_delta_pp": {
      "type": "number",
      "description": "For 'tariff-change': change in duty in PERCENTAGE POINTS (e.g. 10 = +10pp, -5 = a cut). Default 10."
    },
    "value": {
      "type": "number",
      "description": "For 'tariff-change': merchandise value (USD) to size the duty/landed impact. Default 50000."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "scenario"
  ]
}

door_to_door

Get the TRUE DOOR-TO-DOOR cost and time of an import move, not the port-to-port figure importers usually quote. The ocean tools price PORT-TO-PORT; this layers the INLAND legs at BOTH ends onto the all-in ocean move: origin drayage (the short truck move factory/CY → load port), destination drayage (discharge port → DC), the US CHASSIS rental (a separate daily charge + a chassis-split fee that exists in the US but is bundled elsewhere), terminal GATE-congestion fees and turn-time days, and — when the cargo's real destination is INLAND — the interior haul with a RAIL-vs-TRUCK decision (US IPI intermodal to Chicago/Dallas/Memphis; the Rotterdam/Antwerp barge-rail hinterland to Duisburg/Basel/Milan), choosing the cheaper mode by distance (deadline-aware). Inland routinely adds 15-40% over the port-to-port cost and several days — both of which this returns folded into a door-to-door total and a door p50/p90 transit. Every inland figure is a modeled market-typical band (regla 7), not a trucker quote. PREMIUM: x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.

Parameters8

origin_port	string	required	Origin (load) port — city, UN/LOCODE, or 'City, Country'.
dest_port	string	required	Destination (discharge) port — city, UN/LOCODE, or 'City, Country'.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
ship_date	string	optional	Intended ship date (ISO). Drives ocean seasonality & transit. Optional; defaults to today.
band	string	optional	Inland cost band: 'low', 'typical' (default) or 'high'.
inland_destination	string	optional	Optional inland point the cargo really goes to (e.g. 'Chicago', 'Dallas', 'Duisburg', 'Milan', 'Basel') → adds the interior rail-vs-truck haul from the discharge port.
interior_mode	string	optional	Force the interior haul mode: 'rail' or 'truck'. Optional; default = cheaper of the two (deadline-aware).
urgent	boolean	optional	Hard deadline → biases the interior haul to truck for door-speed. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin (load) port — city, UN/LOCODE, or 'City, Country'."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination (discharge) port — city, UN/LOCODE, or 'City, Country'."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Intended ship date (ISO). Drives ocean seasonality & transit. Optional; defaults to today."
    },
    "band": {
      "type": "string",
      "description": "Inland cost band: 'low', 'typical' (default) or 'high'."
    },
    "inland_destination": {
      "type": "string",
      "description": "Optional inland point the cargo really goes to (e.g. 'Chicago', 'Dallas', 'Duisburg', 'Milan', 'Basel') → adds the interior rail-vs-truck haul from the discharge port."
    },
    "interior_mode": {
      "type": "string",
      "description": "Force the interior haul mode: 'rail' or 'truck'. Optional; default = cheaper of the two (deadline-aware)."
    },
    "urgent": {
      "type": "boolean",
      "description": "Hard deadline → biases the interior haul to truck for door-speed. Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

load_plan

Optimize how a product LOADS into a container — the stowage/cube-and-weight question every importer faces. Give the CARTON dimensions (cm) and gross weight (kg) and optionally a target quantity, and it computes: how many units fit BY VOLUME and BY WEIGHT and which constraint BINDS FIRST (the crux — dense cargo like tiles/stone tops out by WEIGHT at low cube, while light cargo like apparel/foam fills the CUBE with payload to spare); the utilization on BOTH axes (% volume AND % payload) so you see the wasted constraint; the 40HC-vs-2×20DV head-to-head for the cargo's density (two 20ft give ~2× the payload for ~the same cube — the right answer for heavy cargo, which a naïve volume-only divide gets wrong); an OVERWEIGHT warning when a box that's 'full' by cube would be ILLEGAL to truck because the destination ROAD/axle weight limit (e.g. US ~38-44k lb cargo on a standard chassis) is far below the ISO 26.7t container plate; and a recommended container MIX for a target quantity with the last box right-sized. Uses real interior dimensions and max payloads of 20DV/40DV/40HC (and reefers) plus per-country road weight caps. Indicative stowage PLANNING (practical-cube loadability, not 3D bin-packing), not a load-securing certification (regla 7). PREMIUM: x402 (USDC on Base) or a prepaid key.

Parameters10

length_cm	number	required	Carton length in cm. REQUIRED.
width_cm	number	required	Carton width in cm. REQUIRED.
height_cm	number	required	Carton height in cm. REQUIRED.
weight_kg	number	required	Gross weight per carton in kg. REQUIRED — it drives the weight-binding & overweight logic.
units_per_carton	number	optional	Units (pieces) per carton, for unit-level totals. Optional; default 1.
reefer	boolean	optional	Evaluate reefer containers (20RF/40RF) instead of dry. Optional.
destination_country	string	optional	Destination ISO-2 country (e.g. 'US', 'DE') → enables the road-weight overweight check. Optional.
heavy_chassis	boolean	optional	Use the heavy/tri-axle road limit instead of the standard chassis cap. Optional.
target_cartons	number	optional	Total cartons to ship → produces a container MIX. Optional.
target_units	number	optional	Total units to ship (converted via units_per_carton) → produces a container mix. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "length_cm": {
      "type": "number",
      "description": "Carton length in cm. REQUIRED."
    },
    "width_cm": {
      "type": "number",
      "description": "Carton width in cm. REQUIRED."
    },
    "height_cm": {
      "type": "number",
      "description": "Carton height in cm. REQUIRED."
    },
    "weight_kg": {
      "type": "number",
      "description": "Gross weight per carton in kg. REQUIRED — it drives the weight-binding & overweight logic."
    },
    "units_per_carton": {
      "type": "number",
      "description": "Units (pieces) per carton, for unit-level totals. Optional; default 1."
    },
    "reefer": {
      "type": "boolean",
      "description": "Evaluate reefer containers (20RF/40RF) instead of dry. Optional."
    },
    "destination_country": {
      "type": "string",
      "description": "Destination ISO-2 country (e.g. 'US', 'DE') → enables the road-weight overweight check. Optional."
    },
    "heavy_chassis": {
      "type": "boolean",
      "description": "Use the heavy/tri-axle road limit instead of the standard chassis cap. Optional."
    },
    "target_cartons": {
      "type": "number",
      "description": "Total cartons to ship → produces a container MIX. Optional."
    },
    "target_units": {
      "type": "number",
      "description": "Total units to ship (converted via units_per_carton) → produces a container mix. Optional."
    }
  },
  "required": [
    "length_cm",
    "width_cm",
    "height_cm",
    "weight_kg"
  ]
}

optimize_network

Optimize a shipper's ENTIRE annual lane PORTFOLIO at once — the question the single-lane tools can't answer. Give a SET of lanes with their annual volumes (an importer's network) and the engine optimizes globally: it procures each lane (contract / spot / optimal mix) and costs it, scores its schedule reliability and its CO2, then enforces NETWORK CONSTRAINTS — a total freight BUDGET (shifts soft-market lanes to locked contracts to fit), a minimum SERVICE level (won't cut a lane's reliability below the floor to save money), and an ESG CO2 ceiling (targets the carbon-heaviest lanes). It surfaces the TOP SAVING lanes (spot-vs-contract spread × volume), where to CONSOLIDATE volume under one alliance contract for a better tier, and the network coste/servicio/CO2 trade-off. Reuses the same modeled engines as the per-lane tools, so the portfolio answer is coherent with each lane. Indicative portfolio guidance, not a tendered rate or committed allocation (regla 7). PREMIUM: x402 (USDC on Base) or a prepaid key.

Parameters7

lanes	array	required	The lane portfolio. Each item: { origin_port, dest_port, annual_volume, container_type?, contract_rate_offered? }. REQUIRED, max 30.
ship_date	string	optional	Reference ship date (ISO) for the seasonal/market context. Optional.
risk_tolerance	string	optional	'low', 'medium' (default) or 'high' — the portfolio's appetite for spot exposure.
budget	number	optional	Total annual freight budget (USD). If exceeded, the engine recommends shifting lanes toward locked contracts. Optional.
min_reliability	number	optional	Minimum acceptable schedule reliability (0-100) on any lane. Lanes below it are flagged; cost is not cut at the expense of service. Optional.
max_co2_tonnes	number	optional	Network CO2 ceiling (tonnes/yr). If exceeded, the engine targets the carbon-heaviest lanes. Optional.
consolidation_threshold	number	optional	Volume (containers/yr) at which a lane earns a consolidated-contract tier. Optional; default 500.

Raw schema

{
  "type": "object",
  "properties": {
    "lanes": {
      "type": "array",
      "description": "The lane portfolio. Each item: { origin_port, dest_port, annual_volume, container_type?, contract_rate_offered? }. REQUIRED, max 30.",
      "items": {
        "type": "object",
        "properties": {
          "origin_port": {
            "type": "string"
          },
          "dest_port": {
            "type": "string"
          },
          "annual_volume": {
            "type": "number"
          },
          "container_type": {
            "type": "string"
          },
          "contract_rate_offered": {
            "type": "number"
          }
        },
        "required": [
          "origin_port",
          "dest_port",
          "annual_volume"
        ]
      }
    },
    "ship_date": {
      "type": "string",
      "description": "Reference ship date (ISO) for the seasonal/market context. Optional."
    },
    "risk_tolerance": {
      "type": "string",
      "description": "'low', 'medium' (default) or 'high' — the portfolio's appetite for spot exposure."
    },
    "budget": {
      "type": "number",
      "description": "Total annual freight budget (USD). If exceeded, the engine recommends shifting lanes toward locked contracts. Optional."
    },
    "min_reliability": {
      "type": "number",
      "description": "Minimum acceptable schedule reliability (0-100) on any lane. Lanes below it are flagged; cost is not cut at the expense of service. Optional."
    },
    "max_co2_tonnes": {
      "type": "number",
      "description": "Network CO2 ceiling (tonnes/yr). If exceeded, the engine targets the carbon-heaviest lanes. Optional."
    },
    "consolidation_threshold": {
      "type": "number",
      "description": "Volume (containers/yr) at which a lane earns a consolidated-contract tier. Optional; default 500."
    }
  },
  "required": [
    "lanes"
  ]
}

payment_terms

Recommend the TRADE-FINANCE / PAYMENT TERMS for an import deal — the other half of the transaction the freight tools ignore. Give the lane (→ exporter country at origin, importer country at destination), the invoice value and the counterparty RELATIONSHIP, and it scores the payment-instrument spectrum — CASH-IN-ADVANCE / LETTER OF CREDIT (irrevocable, possibly CONFIRMED) / DOCUMENTARY COLLECTION D/P (documents against payment) / D/A (documents against acceptance) / OPEN ACCOUNT — on its RISK ALLOCATION (CIA = all risk on the buyer … open account = all risk on the seller) and arrange cost, then recommends one by the relationship × COUNTRY-RISK matrix: a new counterparty in a high-risk importer country → an irrevocable, confirmed LC; an established relationship in a safe country → cheaper open account; in between → documentary collection. It PRICES the LC commission for the deal (issuing rises with importer-country risk; confirmation — a bank in the seller's country adding its guarantee — adds a country-risk-scaled premium), and ties to Incoterms (CIF/CIP put insurance on the seller; an LC pairs with the FOB/CFR document set). Country-risk and LC-commission bands are MODELED market-typical figures; this is not financial, legal or banking advice (regla 7). PREMIUM: x402 (USDC on Base) or a prepaid key.

Parameters9

origin_port	string	required	Origin port — its COUNTRY is taken as the exporter/seller country.
dest_port	string	required	Destination port — its COUNTRY is taken as the importer/buyer country (drives the country-risk band).
invoice_value	number	required	Commercial invoice value in USD. REQUIRED — finance costs are priced on it.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
relationship	string	optional	Counterparty relationship strength: 'new', 'developing' (default), 'established' or 'long-term'. The single biggest driver of the recommendation.
importer_country	string	optional	Override the importer ISO-2 country (else taken from the destination port).
exporter_country	string	optional	Override the exporter ISO-2 country (else taken from the origin port).
confirmed	boolean	optional	Force the LC pricing confirmed/unconfirmed. Optional; default = auto by importer-country risk.
incoterm	string	optional	Optional Incoterms 2020 rule (CIF, FOB, CIP…) for the document-set tie-in note.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port — its COUNTRY is taken as the exporter/seller country."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port — its COUNTRY is taken as the importer/buyer country (drives the country-risk band)."
    },
    "invoice_value": {
      "type": "number",
      "description": "Commercial invoice value in USD. REQUIRED — finance costs are priced on it."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'."
    },
    "relationship": {
      "type": "string",
      "description": "Counterparty relationship strength: 'new', 'developing' (default), 'established' or 'long-term'. The single biggest driver of the recommendation."
    },
    "importer_country": {
      "type": "string",
      "description": "Override the importer ISO-2 country (else taken from the destination port)."
    },
    "exporter_country": {
      "type": "string",
      "description": "Override the exporter ISO-2 country (else taken from the origin port)."
    },
    "confirmed": {
      "type": "boolean",
      "description": "Force the LC pricing confirmed/unconfirmed. Optional; default = auto by importer-country risk."
    },
    "incoterm": {
      "type": "string",
      "description": "Optional Incoterms 2020 rule (CIF, FOB, CIP…) for the document-set tie-in note."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "invoice_value"
  ]
}

special_cargo

Assess SPECIAL / NON-STANDARD CARGO for a lane — dangerous goods, refrigerated (reefer), and out-of-gauge — the moves a plain 'dry box' rate model can't price or clear. DANGEROUS GOODS (IMDG): give a hazard class ('3', '2.1', 'class 9') or a commodity that classifies to one (e.g. 'paint' → Class 3 flammable liquid, 'lithium batteries' → Class 9), and it returns the IMDG hazard family, the STOWAGE category (on/under deck), the SEGREGATION requirements against any other classes you list in the same booking, the documentation burden (the shipper's Dangerous Goods Declaration + class-specific papers), the per-class DG SURCHARGE, and — the decision that matters — whether that class is ACCEPTED on a standard liner service, needs prior approval, or is commonly REFUSED (Class 1 explosives, 6.2 infectious, 7 radioactive). REEFER: give a commodity ('frozen shrimp', 'bananas', 'pharma 2-8') and it returns the carrying SETPOINT + tolerance band, the regime (frozen/chilled/pharma/ambient-controlled), the cold-chain RISK (a pharma GDP breach can total the cargo; a banana below 12°C is chilling injury), and the reefer plug + pharma cold-chain + controlled-atmosphere PREMIUMS. OUT-OF-GAUGE (OOG): give over-dimensions (length/width/height in cm + weight) or request a flat-rack/open-top, and it picks the equipment, computes how many neighbouring SLOTS the protrusion sterilises, the OOG surcharge (equipment + slots + lashing/survey), and the BREAKBULK fallback when nothing fits a box. Every figure is MODELED planning data — NOT the IMDG Code, a carrier DG acceptance ruling, or a certified declaration (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.

Parameters13

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port (city name, UN/LOCODE, or 'City, Country').
container_type	string	optional	Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
dg_class	string	optional	IMDG hazard class for a dangerous-goods check: '1','2.1','2.2','2.3','3','4.1','4.2','4.3','5.1','5.2','6.1','6.2','7','8','9' (also 'class 3' etc). Provide this OR a 'product' that classifies to a class.
other_classes	array	optional	Other IMDG classes in the same booking / on board, to evaluate SEGREGATION against. Optional.
product	string	optional	Free-text commodity. Drives the reefer lookup ('frozen shrimp', 'bananas', 'pharma 2-8') OR infers a DG class for some families ('lithium batteries' → 9, 'paint' → 3).
oog_equipment	string	optional	Explicit out-of-gauge equipment: 'flat-rack-40','flat-rack-20','open-top-40','open-top-20','breakbulk'. Optional.
length_cm	number	optional	Over-dimension piece length in cm (triggers an OOG assessment). Optional.
width_cm	number	optional	Over-dimension piece width in cm. Optional.
height_cm	number	optional	Over-dimension piece height in cm. Optional.
weight_kg	number	optional	Piece weight in kg (drives flat-rack vs breakbulk). Optional.
reefer	boolean	optional	Force a reefer assessment even without a recognised product. Optional.
controlled_atmosphere	boolean	optional	Add the controlled-atmosphere (CA) reefer premium. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (city name, UN/LOCODE, or 'City, Country')."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'."
    },
    "dg_class": {
      "type": "string",
      "description": "IMDG hazard class for a dangerous-goods check: '1','2.1','2.2','2.3','3','4.1','4.2','4.3','5.1','5.2','6.1','6.2','7','8','9' (also 'class 3' etc). Provide this OR a 'product' that classifies to a class."
    },
    "other_classes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Other IMDG classes in the same booking / on board, to evaluate SEGREGATION against. Optional."
    },
    "product": {
      "type": "string",
      "description": "Free-text commodity. Drives the reefer lookup ('frozen shrimp', 'bananas', 'pharma 2-8') OR infers a DG class for some families ('lithium batteries' → 9, 'paint' → 3). "
    },
    "oog_equipment": {
      "type": "string",
      "description": "Explicit out-of-gauge equipment: 'flat-rack-40','flat-rack-20','open-top-40','open-top-20','breakbulk'. Optional."
    },
    "length_cm": {
      "type": "number",
      "description": "Over-dimension piece length in cm (triggers an OOG assessment). Optional."
    },
    "width_cm": {
      "type": "number",
      "description": "Over-dimension piece width in cm. Optional."
    },
    "height_cm": {
      "type": "number",
      "description": "Over-dimension piece height in cm. Optional."
    },
    "weight_kg": {
      "type": "number",
      "description": "Piece weight in kg (drives flat-rack vs breakbulk). Optional."
    },
    "reefer": {
      "type": "boolean",
      "description": "Force a reefer assessment even without a recognised product. Optional."
    },
    "controlled_atmosphere": {
      "type": "boolean",
      "description": "Add the controlled-atmosphere (CA) reefer premium. Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

export_compliance

Check whether it is LEGAL to EXPORT a given product to a destination, and whether it needs an export LICENCE — the goods-side trade-compliance question (NOT denied-party / sanctioned-person screening, which is a separate regulated process this tool does NOT perform). Pass a product description (reusing the same HS classifier as get_landed_cost) or an HS code + the lane. It classifies the goods against the DUAL-USE control lists (a modeled ECCN / EU Annex-I dual-use category: advanced electronics, encryption/information-security, sensors & lasers, navigation, aerospace, nuclear, special materials, machine tools, controlled telecom), reads the DESTINATION's embargo / restriction level (comprehensive embargo, arms/dual-use embargo, licence-required, partial, or permissive — modeled at a high level), and runs the decision tree: a dual-use good to an embargoed destination is BLOCKED; a dual-use good to a licence-required destination needs a LICENCE; an ordinary good to a permissive destination is likely PERMITTED; and anything ambiguous returns REVIEW-REQUIRED. ⚠️ THIS IS THE MOST LEGALLY SENSITIVE TOOL. The classification, the dual-use flag and the embargo list are a MODELED, SIMPLIFIED, NON-AUTHORITATIVE planning aid — NOT legal advice, NOT an official commodity classification (e.g. BIS CCATS), and NOT a current sanctions determination. Lists change; control hinges on exact technical parameters and end-use. You MUST verify with your government licensing authority (US BIS / the relevant EU member-state authority) and qualified trade-compliance counsel before exporting (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.

Parameters5

origin_port	string	required	Origin port — its COUNTRY is the exporter jurisdiction.
dest_port	string	required	Destination port — its COUNTRY drives the embargo / licence-required check.
container_type	string	optional	Container size '20ft'/'40ft'/'40HC' (informational). Optional.
product	string	optional	Product description to classify, e.g. 'thermal imaging camera', 'encryption appliance', 'cotton t-shirts'. Provide this OR hs_code.
hs_code	string	optional	Explicit HS code (6+ digits). Provide this OR product.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port — its COUNTRY is the exporter jurisdiction."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port — its COUNTRY drives the embargo / licence-required check."
    },
    "container_type": {
      "type": "string",
      "description": "Container size '20ft'/'40ft'/'40HC' (informational). Optional."
    },
    "product": {
      "type": "string",
      "description": "Product description to classify, e.g. 'thermal imaging camera', 'encryption appliance', 'cotton t-shirts'. Provide this OR hs_code."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (6+ digits). Provide this OR product."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

fx_exposure

Quantify and hedge the CURRENCY RISK of your ocean-freight spend. Freight is quoted and largely invoiced in USD, but a non-US shipper PAYS in its home currency (EUR/GBP/JPY/CNY/…) — so a large, recurring USD freight bill is a foreign-exchange exposure: if the home currency weakens, the same freight costs more locally. Pass your home currency + your annual USD freight spend, and it returns: the exposure in your local currency at a modeled spot, the annualised VOLATILITY band of the pair, the 95% adverse FX move on the spend (in money), and a HEDGE-RATIO recommendation — what % of the exposure to cover with forwards — using a media-variance objective analogous to the procurement engine: higher volatility and a lower risk tolerance push the hedge up, but a variable spend caps it (you can't lock forwards for volume you might not ship), so it never blindly recommends 100%. It also sketches the forward-points carry (so the hedge isn't assumed free) and a laddered hedging plan. Honest (regla 7): MODELED reference analysis, NOT live market quotes and NOT financial / hedging advice — consult a treasury/FX professional. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters5

local_currency	string	required	Your home currency you pay freight in: EUR, GBP, JPY, CNY, INR, KRW, CAD, AUD, SGD, BRL, MXN (or a name). REQUIRED.
annual_freight_spend_usd	number	required	Your yearly USD ocean-freight bill (the USD exposure). REQUIRED.
horizon_months	number	optional	Hedging horizon in months (1-36, default 12). The exposure & risk are pro-rated to it.
risk_tolerance	string	optional	'low' (hedge more), 'medium' (default) or 'high' (hedge less).
spend_cv	number	optional	Relative std-dev of your freight spend itself (e.g. 0.2 = ±20% volume). Caps the hedge ratio. Optional; default 0.15.

Raw schema

{
  "type": "object",
  "properties": {
    "local_currency": {
      "type": "string",
      "description": "Your home currency you pay freight in: EUR, GBP, JPY, CNY, INR, KRW, CAD, AUD, SGD, BRL, MXN (or a name). REQUIRED."
    },
    "annual_freight_spend_usd": {
      "type": "number",
      "description": "Your yearly USD ocean-freight bill (the USD exposure). REQUIRED."
    },
    "horizon_months": {
      "type": "number",
      "description": "Hedging horizon in months (1-36, default 12). The exposure & risk are pro-rated to it."
    },
    "risk_tolerance": {
      "type": "string",
      "description": "'low' (hedge more), 'medium' (default) or 'high' (hedge less)."
    },
    "spend_cv": {
      "type": "number",
      "description": "Relative std-dev of your freight spend itself (e.g. 0.2 = ±20% volume). Caps the hedge ratio. Optional; default 0.15."
    }
  },
  "required": [
    "local_currency",
    "annual_freight_spend_usd"
  ]
}

build_tender

Build the structure of a freight RFP / TENDER to put your ocean network out to bid. Pass your lanes with annual volumes and it returns, per lane, the volume + a modeled MARKET-RATE BAND (from our all-in rate engine, server-side) so you walk in knowing the credible price — the anchor that lets you spot a low-ball. Plus: the standard service requirements (fixed-day sailings, equipment commitment, reliability target, transparent surcharge formulas, free time), the AWARD CRITERIA weighted by your priority (cost / reliability / balanced), the BID SHEET columns carriers fill in, the RFP timeline (issue → Q&A → bids → evaluate → BAFO → award), and the modeled total annual spend. Pair with evaluate_bids to score the answers. Honest (regla 7): market bands are modeled, not filed tariffs. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters2

lanes	array	required	The lanes to tender. Each: { origin_port, dest_port, annual_volume, container_type? }.
priority	string	optional	Award weighting: 'cost', 'reliability' or 'balanced' (default).

Raw schema

{
  "type": "object",
  "properties": {
    "lanes": {
      "type": "array",
      "description": "The lanes to tender. Each: { origin_port, dest_port, annual_volume, container_type? }.",
      "items": {
        "type": "object"
      }
    },
    "priority": {
      "type": "string",
      "description": "Award weighting: 'cost', 'reliability' or 'balanced' (default)."
    }
  },
  "required": [
    "lanes"
  ]
}

evaluate_bids

Evaluate carrier BIDS on a freight tender and pick the best award per lane. Pass your lanes (with annual volumes) and the bids each carrier submitted (carrier + all-in rate, optionally transit/sailings/free-days). For each lane it scores every bid on COST + RELIABILITY (the carrier's expected on-time performance from iter8 carrier matching) + COVERAGE (does it actually serve the corridor), DETECTS LOW-BALLS — a bid implausibly under the lane's modeled market band, the kind that gets rolled or surcharged back up and won't hold — by scoring them DOWN on credibility, and picks the best CREDIBLE award per lane. At the network level it shows the awarded annual cost vs the naive-cheapest cost (the cost of choosing credible over chasing a low-ball) and how many low-balls it flagged. Honest (regla 7): a modeled decision aid, not a procurement decision — verify rates & service commitments contractually. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters2

lanes	array	required	Lanes with bids. Each: { origin_port, dest_port, annual_volume, container_type?, bids: [ { carrier, rate, transit_days?, sailings_per_week?, free_days? } ] }.
priority	string	optional	Scoring weighting: 'cost', 'reliability' or 'balanced' (default).

Raw schema

{
  "type": "object",
  "properties": {
    "lanes": {
      "type": "array",
      "description": "Lanes with bids. Each: { origin_port, dest_port, annual_volume, container_type?, bids: [ { carrier, rate, transit_days?, sailings_per_week?, free_days? } ] }.",
      "items": {
        "type": "object"
      }
    },
    "priority": {
      "type": "string",
      "description": "Scoring weighting: 'cost', 'reliability' or 'balanced' (default)."
    }
  },
  "required": [
    "lanes"
  ]
}

customs_optimization

Find the DUTY-SAVING levers a customs broker knows but the importer usually does not — and quantify each against your shipment's REAL landed-cost duty. Give a product (or HS code) + the lane + the FOB value + your trade FLOW (import & sell / re-export / import-components-assemble-re-export / store), and it returns, ranked by saving: DUTY DRAWBACK (US 99% recovery of duties on goods you re-export — honestly flagging that Section 301 is NOT drawback-eligible, the big China carve-out); FOREIGN-TRADE ZONE / FREE ZONE (eliminate duty on the re-exported share, defer it on the rest, inverted-tariff election); BONDED / CUSTOMS WAREHOUSE (defer the duty cash-flow until withdrawal, or avoid it on re-export); EU/UK INWARD PROCESSING (suspend duty on inputs you process & re-export) and OUTWARD PROCESSING (duty only on value added abroad); FIRST-SALE valuation (US — value on the lower factory price, cutting MFN AND 301 proportionally); and TARIFF ENGINEERING (legally reclassify to a lower-duty HS line). Each lever shows the money saved, whether it's cash-back vs cash-flow-deferral vs a rate/base cut, and the catch — plus a clearance-workflow checklist. Reuses the real landed-cost engine so the duty base, 301/232/FTA stack and import VAT are genuine. ⚠️ Aduanas are complex: every figure is MODELED, INDICATIVE planning intelligence, NOT customs/legal/tax advice — confirm eligibility and obtain binding rulings with a licensed broker (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.

Parameters7

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port — its country sets the customs bloc & regimes.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
product	string	optional	Product description to classify (e.g. 'bluetooth earbuds'). Provide this OR hs_code.
hs_code	string	optional	Explicit HS code (6+ digits). Provide this OR product.
fob_value	number	required	Merchandise value (FOB) in USD. REQUIRED — it's the duty base.
flow	string	optional	The goods flow: 'import-consume' (sell domestically, default), 'import-reexport', 'import-assemble' (components→assemble→re-export), or 'import-store'. Free text accepted.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port — its country sets the customs bloc & regimes."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "product": {
      "type": "string",
      "description": "Product description to classify (e.g. 'bluetooth earbuds'). Provide this OR hs_code."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (6+ digits). Provide this OR product."
    },
    "fob_value": {
      "type": "number",
      "description": "Merchandise value (FOB) in USD. REQUIRED — it's the duty base."
    },
    "flow": {
      "type": "string",
      "description": "The goods flow: 'import-consume' (sell domestically, default), 'import-reexport', 'import-assemble' (components→assemble→re-export), or 'import-store'. Free text accepted."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "fob_value"
  ]
}

sourcing_analysis

The strategic CHINA+1 / NEARSHORING decision, quantified. Give the SAME product (or HS code) + a destination market + the China-equivalent FOB cost, and it compares making it in China vs Vietnam / India / Mexico / Turkey (and Thailand / Indonesia / Malaysia) on the three axes that actually decide it: TOTAL LANDED COST per origin — manufactured cost (relative labour/productivity index) + the real freight from each origin's export gateway + the real DUTY, so Section 301 penalises China→US, USMCA makes Mexico→US duty-free, and EVFTA makes Vietnam→EU duty-free (all through the genuine duty tables, not a fudge); LEAD TIME — the real ocean transit plus each origin's structural adder (Mexico/Turkey nearshore shortens the chain dramatically); and RISK — a geopolitical/concentration score, with a penalty that marks DOWN a China-only answer for single-country dependence (the whole point of China+1). It ranks the origins on a weightable blend (cost / lead-time / risk priority), names the recommended origin, and proposes a de-risking dual-source MIX. The highest-value strategic question in global sourcing right now. Honest (regla 7): cost indices, risk scores and lead adders are MODELED, product-specific and directional — frame the trade-off, then get factory quotes + a rules-of-origin check. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters7

product	string	required	Product to source, e.g. 'cotton t-shirts', 'lithium batteries'. Provide this OR hs_code.
hs_code	string	optional	Explicit HS code. Provide this OR product.
dest_port	string	required	Destination market port (its country drives the duty/FTA treatment). REQUIRED.
fob_value	number	required	The China-equivalent manufactured (FOB) cost in USD — other origins are scaled by their cost index. REQUIRED.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
candidates	array	optional	Candidate origin countries (ISO2 or name): CN, VN, IN, MX, TR, TH, ID, MY. Optional; default = CN, VN, IN, MX, TR.
priority	string	optional	Weighting: 'cost', 'lead-time'/'speed', 'risk'/'resilience', or 'balanced' (default).

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "description": "Product to source, e.g. 'cotton t-shirts', 'lithium batteries'. Provide this OR hs_code."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code. Provide this OR product."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination market port (its country drives the duty/FTA treatment). REQUIRED."
    },
    "fob_value": {
      "type": "number",
      "description": "The China-equivalent manufactured (FOB) cost in USD — other origins are scaled by their cost index. REQUIRED."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Candidate origin countries (ISO2 or name): CN, VN, IN, MX, TR, TH, ID, MY. Optional; default = CN, VN, IN, MX, TR."
    },
    "priority": {
      "type": "string",
      "description": "Weighting: 'cost', 'lead-time'/'speed', 'risk'/'resilience', or 'balanced' (default)."
    }
  },
  "required": [
    "product",
    "dest_port",
    "fob_value"
  ]
}

market_report

Compose freight-pulse's whole engine stack into ONE executive market-intelligence report for a lane — the committee-ready brief a head of logistics presents. Give the lane (and optionally a product + merchandise value to deepen it) and it returns a structured, sectioned report: 1) MARKET STATE & OUTLOOK — today's cross-validated spot + direction, the Holt-Winters forecast with intervals, the seasonality calendar overlaid on your ship date (CNY / Golden Week / peak / GRIs / blank sailings), and an anomaly read; 2) COST — all-in freight and, with product+value, the full landed cost (duty / 301 / FTA / import VAT); 3) TRANSIT, RELIABILITY & PORT CONGESTION — operational risk, added delay, active disruptions; 4) RECOMMENDATIONS — the unified mode + carrier + book-now/wait timing; 5) RISKS & MITIGATIONS; 6) ESG — ocean CO2e and EU-ETS carbon cost; plus an EXECUTIVE SUMMARY, a HEADLINE call, and a Monday-morning ACTION LIST. Every section is sourced from a real modeled engine and tagged; the report names which engines contributed and which weren't available for the lane. Honest (regla 7): indicative decision support, not a quote/booking/legal advice. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters9

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Planned ship date (YYYY-MM-DD). Optional; default today. Overlays the seasonality calendar.
product	string	optional	Product / HS to unlock the landed-cost & decision sections. Optional.
hs_code	string	optional	Explicit HS code. Optional.
value	number	optional	Merchandise value (USD) — unlocks landed cost + the unified mode/carrier/timing decision. Optional but recommended.
weight_kg	number	optional	Cargo weight (kg) — sharpens emissions & decisioning. Optional.
volume_m3	number	optional	Cargo volume (m3). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Planned ship date (YYYY-MM-DD). Optional; default today. Overlays the seasonality calendar."
    },
    "product": {
      "type": "string",
      "description": "Product / HS to unlock the landed-cost & decision sections. Optional."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code. Optional."
    },
    "value": {
      "type": "number",
      "description": "Merchandise value (USD) — unlocks landed cost + the unified mode/carrier/timing decision. Optional but recommended."
    },
    "weight_kg": {
      "type": "number",
      "description": "Cargo weight (kg) — sharpens emissions & decisioning. Optional."
    },
    "volume_m3": {
      "type": "number",
      "description": "Cargo volume (m3). Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

create_watch

Register a standing WATCH on a lane so freight-pulse alerts you when something changes — the feature that makes it a recurring daily tool, not a one-shot lookup. Give a lane + one or more THRESHOLDS and it persists the watch SERVER-SIDE (in our own store, per your key): 'spot-below' / 'spot-above' a USD level (buying window / cost ceiling), 'reliability-below' a score (rollover/delay risk), 'disruption' (any active disruption appears on the corridor/ports), 'book-now' (the forecast/timing engine flips to a book-now window), or 'forecast-rising' / 'forecast-falling' beyond a % move (act early / wait). It returns the watch id and the registered thresholds. Pair it with check_watches, which your agent polls (e.g. daily) to get back only the alerts that fired. Honest (regla 7): evaluated against modeled engine outputs — an alert is a signal to look, not a booking trigger. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters5

origin_port	string	required	Origin port to watch.
dest_port	string	required	Destination port to watch.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
thresholds	array	required	Conditions to fire on. Each: { metric, value? }. metric ∈ spot-below \| spot-above \| reliability-below \| disruption \| book-now \| forecast-rising \| forecast-falling. value: USD for spot-, 0-100 for reliability-below, % for forecast-. e.g. [{ metric:'spot-below', value:2800 }, { metric:'disruption' }].
label	string	optional	Optional name for the watch.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port to watch."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port to watch."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "thresholds": {
      "type": "array",
      "description": "Conditions to fire on. Each: { metric, value? }. metric ∈ spot-below | spot-above | reliability-below | disruption | book-now | forecast-rising | forecast-falling. value: USD for spot-*, 0-100 for reliability-below, % for forecast-*. e.g. [{ metric:'spot-below', value:2800 }, { metric:'disruption' }].",
      "items": {
        "type": "object"
      }
    },
    "label": {
      "type": "string",
      "description": "Optional name for the watch."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "thresholds"
  ]
}

check_watches

Evaluate the lane watches you registered with create_watch against the LIVE modeled market and return the alerts that FIRED. For each watch it gathers the current cross-validated spot + direction, the modeled lane reliability, any active disruptions, and (when a watch needs it) the forecast/timing book call + expected move, then checks every threshold and reports which ones tripped — with the observed value, the reason and a severity. Pass a watch_id to check just one, or omit it to evaluate them all. This is the daily poll that turns freight-pulse into a standing watchtower on your network. Honest (regla 7): modeled signals, verify before acting. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters1

watch_id

string

optional

Evaluate only this watch id. Optional — omit to evaluate all your watches.

Raw schema

{
  "type": "object",
  "properties": {
    "watch_id": {
      "type": "string",
      "description": "Evaluate only this watch id. Optional — omit to evaluate all your watches."
    }
  },
  "required": []
}

qualify_fta_origin

Does your product actually QUALIFY for the FTA preference? The expensive detail iter14's sourcing/landed-cost silently assumes away: the USMCA / EVFTA / CETA / RCEP / KORUS preferential (usually 0%) duty applies ONLY if the good MEETS the agreement's RULE OF ORIGIN — and a huge share of would-be-preferential imports FAIL it (Chinese fabric cut in Vietnam misses EVFTA's yarn-forward rule; a Mexican assembly that's 60% imported misses USMCA's RVC). Give the product (or HS), the country of MANUFACTURE, the destination market, and the bill of MATERIALS (each input's value + origin + optional HS), and it computes against the resolved FTA's product rule: REGIONAL VALUE CONTENT (both transaction-value and net-cost methods vs the threshold), TARIFF SHIFT / change in tariff classification (CC chapter / CTH heading / CTSH subheading), DE-MINIMIS tolerance, and agreement-specific rules (USMCA autos 75% RVC + steel/aluminium; EVFTA apparel yarn-forward). It returns the VERDICT — QUALIFIES or NOT, WHY, exactly how many RVC points (and how much $) you're short, and the concrete paths to qualify. Links to iter4 (HS) and iter14 (sourcing/duty). ⚠️ Rules of origin are among the most complex parts of trade law — MODELED, INDICATIVE qualification aid, NOT a legal origin determination; the agreement's PSR annex + a licensed broker govern the binding answer, and a wrong preference claim carries duty + penalty exposure (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters7

product	string	optional	Product description to classify (e.g. 'cotton t-shirt'). Provide this OR hs_code.
hs_code	string	optional	Explicit HS code (6+ digits) of the finished good. Provide this OR product.
manufacture_country	string	required	Country where the finished good is MADE (ISO2 like 'VN' or a name). REQUIRED.
destination	string	required	Destination market — country (ISO2/name) or a port. Its bloc sets the FTA. REQUIRED.
transaction_value	number	required	FOB value of the FINISHED good in USD (the RVC denominator). REQUIRED.
materials	array	required	Bill of materials: each { description, value (USD), origin (ISO2/name), hs_code? }. REQUIRED.
net_cost_fraction	number	optional	Net cost as a fraction of transaction value for the net-cost RVC method (default 0.85). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "description": "Product description to classify (e.g. 'cotton t-shirt'). Provide this OR hs_code."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (6+ digits) of the finished good. Provide this OR product."
    },
    "manufacture_country": {
      "type": "string",
      "description": "Country where the finished good is MADE (ISO2 like 'VN' or a name). REQUIRED."
    },
    "destination": {
      "type": "string",
      "description": "Destination market — country (ISO2/name) or a port. Its bloc sets the FTA. REQUIRED."
    },
    "transaction_value": {
      "type": "number",
      "description": "FOB value of the FINISHED good in USD (the RVC denominator). REQUIRED."
    },
    "materials": {
      "type": "array",
      "description": "Bill of materials: each { description, value (USD), origin (ISO2/name), hs_code? }. REQUIRED.",
      "items": {
        "type": "object"
      }
    },
    "net_cost_fraction": {
      "type": "number",
      "description": "Net cost as a fraction of transaction value for the net-cost RVC method (default 0.85). Optional."
    }
  },
  "required": [
    "manufacture_country",
    "destination",
    "transaction_value",
    "materials"
  ]
}

check_lc_documents

Will your letter-of-credit documents GET PAID? Banks reject roughly 60-70% of first-presentation documentary-credit submissions over DOCUMENTARY DISCREPANCIES. Give the fields of the credit + the presented documents (commercial invoice, bill of lading, insurance, packing list) and it applies the UCP 600 rules a trade-finance checker uses, returning the DISCREPANCIES that would make an examining bank reject the presentation — each tied to its UCP article with a remedy: invoice amount over the credit (art. 18/30 tolerances), currency mismatch (art. 18a), goods description not CORRESPONDING to the credit (art. 18c), data conflict across documents (art. 14), late shipment vs the latest-shipment date, STALE presentation (>21 days, art. 14c) or after expiry, port-of-loading/discharge mismatch on the B/L (art. 20), a non-clean B/L (art. 27), and insurance <110% of CIF / wrong currency / dated after shipment (art. 28). It reports clean-vs-rejected, the severity mix, what it checked and what it couldn't. Links to iter12 trade finance. ⚠️ The examining bank determines compliance under UCP 600 + ISBP 821 document-by-document; many discrepancies are judgement calls or waivable — MODELED pre-check, NOT a bank determination or legal advice (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters25

creditAmount	number	optional	The credit (LC) amount.
creditCurrency	string	optional	Credit currency (e.g. USD).
amountTolerance	number	optional	Amount tolerance fraction (e.g. 0.05 = ±5%). Default 0.
creditGoodsDescription	string	optional	Goods description as written in the credit.
portOfLoading	string	optional	Credit's required port of loading.
portOfDischarge	string	optional	Credit's required port of discharge.
beneficiary	string	optional	Credit beneficiary (the seller).
latestShipmentDate	string	optional	Latest shipment date (YYYY-MM-DD).
expiryDate	string	optional	Credit expiry date (YYYY-MM-DD).
presentationPeriodDays	number	optional	Presentation period in days (UCP default 21).
incoterm	string	optional	Credit incoterm (CIF/CIP trigger the insurance check).
insuranceRequired	boolean	optional	Does the credit require an insurance document?
invoiceAmount	number	optional	Commercial invoice amount.
invoiceCurrency	string	optional	Invoice currency.
invoiceGoodsDescription	string	optional	Goods description on the invoice.
invoiceBeneficiary	string	optional	Who issued the invoice.
blPortOfLoading	string	optional	Port of loading on the B/L.
blPortOfDischarge	string	optional	Port of discharge on the B/L.
shipmentDate	string	optional	On-board / shipment date on the B/L (YYYY-MM-DD).
presentationDate	string	optional	Date documents are presented to the bank (YYYY-MM-DD).
blClean	boolean	optional	Is the B/L clean (no defect clause)?
insuredAmount	number	optional	Insured amount on the insurance document.
insuredCurrency	string	optional	Insurance currency.
insuranceDate	string	optional	Insurance document date (YYYY-MM-DD).
packingListGoodsDescription	string	optional	Goods description on the packing list.

Raw schema

{
  "type": "object",
  "properties": {
    "creditAmount": {
      "type": "number",
      "description": "The credit (LC) amount."
    },
    "creditCurrency": {
      "type": "string",
      "description": "Credit currency (e.g. USD)."
    },
    "amountTolerance": {
      "type": "number",
      "description": "Amount tolerance fraction (e.g. 0.05 = ±5%). Default 0."
    },
    "creditGoodsDescription": {
      "type": "string",
      "description": "Goods description as written in the credit."
    },
    "portOfLoading": {
      "type": "string",
      "description": "Credit's required port of loading."
    },
    "portOfDischarge": {
      "type": "string",
      "description": "Credit's required port of discharge."
    },
    "beneficiary": {
      "type": "string",
      "description": "Credit beneficiary (the seller)."
    },
    "latestShipmentDate": {
      "type": "string",
      "description": "Latest shipment date (YYYY-MM-DD)."
    },
    "expiryDate": {
      "type": "string",
      "description": "Credit expiry date (YYYY-MM-DD)."
    },
    "presentationPeriodDays": {
      "type": "number",
      "description": "Presentation period in days (UCP default 21)."
    },
    "incoterm": {
      "type": "string",
      "description": "Credit incoterm (CIF/CIP trigger the insurance check)."
    },
    "insuranceRequired": {
      "type": "boolean",
      "description": "Does the credit require an insurance document?"
    },
    "invoiceAmount": {
      "type": "number",
      "description": "Commercial invoice amount."
    },
    "invoiceCurrency": {
      "type": "string",
      "description": "Invoice currency."
    },
    "invoiceGoodsDescription": {
      "type": "string",
      "description": "Goods description on the invoice."
    },
    "invoiceBeneficiary": {
      "type": "string",
      "description": "Who issued the invoice."
    },
    "blPortOfLoading": {
      "type": "string",
      "description": "Port of loading on the B/L."
    },
    "blPortOfDischarge": {
      "type": "string",
      "description": "Port of discharge on the B/L."
    },
    "shipmentDate": {
      "type": "string",
      "description": "On-board / shipment date on the B/L (YYYY-MM-DD)."
    },
    "presentationDate": {
      "type": "string",
      "description": "Date documents are presented to the bank (YYYY-MM-DD)."
    },
    "blClean": {
      "type": "boolean",
      "description": "Is the B/L clean (no defect clause)?"
    },
    "insuredAmount": {
      "type": "number",
      "description": "Insured amount on the insurance document."
    },
    "insuredCurrency": {
      "type": "string",
      "description": "Insurance currency."
    },
    "insuranceDate": {
      "type": "string",
      "description": "Insurance document date (YYYY-MM-DD)."
    },
    "packingListGoodsDescription": {
      "type": "string",
      "description": "Goods description on the packing list."
    }
  },
  "required": []
}

record_performance

Log a shipment's REAL outcome into your private supplier/carrier/lane SCORECARD — the tool that makes freight-pulse RECURRING (you feed it, it accumulates a history no single source hands you). Give the SUBJECT (a carrier like 'Maersk', a supplier, or a lane) and the outcome — promised vs actual transit days, on-time, damage, documentary discrepancy, rollover — and it appends the event to your log, PERSISTED SERVER-SIDE per your key, then returns the subject's running KPIs (OTP %, reliability score, damage/discrepancy/roll rates). Pair with get_scorecard to rank and trend your network over time. Links to iter8 (structural carrier intel) — this is the EMPIRICAL counterpart. Honest (regla 7): it's YOUR own log — KPIs reflect only what you record, small samples flagged. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters10

subject	string	required	Carrier / supplier / lane name to record against. REQUIRED.
subject_type	string	optional	'carrier' (default), 'supplier' or 'lane'.
lane	string	optional	Lane label for context (e.g. 'Shanghai → Los Angeles'). Optional.
promised_days	number	optional	Promised transit/delivery in days.
actual_days	number	optional	Actual transit/delivery in days.
on_time	boolean	optional	Explicit on-time flag (else derived from promised+actual).
damaged	boolean	optional	Were goods damaged?
discrepancy	boolean	optional	Was there a documentary discrepancy?
rolled	boolean	optional	Was the container rolled / shut out?
note	string	optional	Free-text note. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "Carrier / supplier / lane name to record against. REQUIRED."
    },
    "subject_type": {
      "type": "string",
      "description": "'carrier' (default), 'supplier' or 'lane'."
    },
    "lane": {
      "type": "string",
      "description": "Lane label for context (e.g. 'Shanghai → Los Angeles'). Optional."
    },
    "promised_days": {
      "type": "number",
      "description": "Promised transit/delivery in days."
    },
    "actual_days": {
      "type": "number",
      "description": "Actual transit/delivery in days."
    },
    "on_time": {
      "type": "boolean",
      "description": "Explicit on-time flag (else derived from promised+actual)."
    },
    "damaged": {
      "type": "boolean",
      "description": "Were goods damaged?"
    },
    "discrepancy": {
      "type": "boolean",
      "description": "Was there a documentary discrepancy?"
    },
    "rolled": {
      "type": "boolean",
      "description": "Was the container rolled / shut out?"
    },
    "note": {
      "type": "string",
      "description": "Free-text note. Optional."
    }
  },
  "required": [
    "subject"
  ]
}

get_scorecard

Read your accumulating supplier/carrier/lane SCORECARD — the KPIs you've fed with record_performance. Returns, per subject, on-time %, average delay, damage/discrepancy/rollover rates, a 0-100 reliability score and an improving/declining/stable TREND, ranked best-OTP-first, with the best & worst performer. Omit 'subject' for the whole network or pass one to drill in. The standing performance history that turns freight-pulse into a recurring decision tool (who do I award next year's volume to?). Honest (regla 7): your own empirical log, small samples flagged. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters2

subject	string	optional	Drill into one carrier/supplier/lane. Optional — omit for the whole scorecard.
subject_type	string	optional	'carrier' (default), 'supplier' or 'lane' — disambiguates the subject.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "Drill into one carrier/supplier/lane. Optional — omit for the whole scorecard."
    },
    "subject_type": {
      "type": "string",
      "description": "'carrier' (default), 'supplier' or 'lane' — disambiguates the subject."
    }
  },
  "required": []
}

lane_risk_index

How FRAGILE is this route? The 0-100 lane-risk score a supply-chain director needs for their risk map. Give the lane and it COMPOSES the risk dimensions every other freight-pulse engine already models: CHOKEPOINT criticality (Suez / Red-Sea / Bab-el-Mandeb / Panama / Malacca, reusing the routing engine), GEOPOLITICAL risk per origin/destination/transit country (modeled bands), CONCENTRATION (single-port & single-carrier dependence), LABOUR risk (active strikes), CLIMATE risk (typhoon/hurricane/drought windows), CONGESTION (port-intel operational risk) and EQUIPMENT risk (box imbalance). It returns the composite score + the per-driver breakdown (which factor dominates) + ranked MITIGATIONS (alternate routings, add a second carrier/port, pre-position inventory, nearshore a second source). Honest (regla 7): MODELED, indicative — geopolitical risk is judgemental and time-varying; not a live threat feed or insurance-grade rating. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters7

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Ship date (YYYY-MM-DD) — overlays seasonal labour/climate windows. Optional; default today.
transit_country	string	optional	A transit-country ISO2 to fold into geopolitical risk (e.g. 'EG' for Suez). Optional.
carrier_count	number	optional	How many distinct carriers you use on this lane (concentration). Default 1.
port_count	number	optional	How many distinct origin ports you use for this flow. Default 1.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) — overlays seasonal labour/climate windows. Optional; default today."
    },
    "transit_country": {
      "type": "string",
      "description": "A transit-country ISO2 to fold into geopolitical risk (e.g. 'EG' for Suez). Optional."
    },
    "carrier_count": {
      "type": "number",
      "description": "How many distinct carriers you use on this lane (concentration). Default 1."
    },
    "port_count": {
      "type": "number",
      "description": "How many distinct origin ports you use for this flow. Default 1."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

inventory_optimization

Size the INVENTORY a freight decision forces you to hold. The freight choice (mode, reliability, transit time) DETERMINES your safety stock — this computes it. Give the lane + your annual demand (units) + unit value, and it returns, per mode (ocean baseline vs a faster/more-reliable air option): the SAFETY STOCK = z(service level) × σ of lead-time-demand (σ_LTD = sqrt(L·σ_demand² + demand²·σ_lead²), reusing the lane's modeled transit time AND its variability from the transit engine), the REORDER POINT, the Wilson EOQ, and the TOTAL inventory cost (ordering + cycle holding + safety-stock holding). It proves THE trade-off: a faster, more reliable mode shrinks the lead time and its variability → a SMALLER safety stock → released working capital + lower holding — so the 'expensive' freight can pay for itself in less immobilised inventory. Honest (regla 7): textbook OR (normal-approx safety stock, Wilson EOQ) with indicative default cost parameters you should override. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters13

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
annual_demand_units	number	required	Annual demand in UNITS. REQUIRED — inventory policy is sized off it.
unit_value_usd	number	required	Per-unit value (USD). REQUIRED — drives holding cost and immobilised capital.
demand_cv	number	optional	Demand coefficient of variation (σ_demand/mean). Optional; default 0.30.
service_level	number	optional	Target cycle service level (in-stock probability, e.g. 0.95). Optional; default 0.95.
annual_holding_rate_pct	number	optional	Annual holding cost as a fraction of unit value (e.g. 0.25). Optional; default 0.25.
ordering_cost_usd	number	optional	Fixed cost per purchase order (USD). Optional; default 250.
units_per_container	number	optional	Units per ocean container (for the annual freight trade-off). Optional.
air_weight_kg	number	optional	Air shipment weight per consignment (kg) to price the air freight side of the trade-off. Optional.
air_volume_m3	number	optional	Air shipment volume per consignment (m³). Optional.
ship_date	string	optional	Ship date (YYYY-MM-DD). Optional; default today.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "annual_demand_units": {
      "type": "number",
      "description": "Annual demand in UNITS. REQUIRED — inventory policy is sized off it."
    },
    "unit_value_usd": {
      "type": "number",
      "description": "Per-unit value (USD). REQUIRED — drives holding cost and immobilised capital."
    },
    "demand_cv": {
      "type": "number",
      "description": "Demand coefficient of variation (σ_demand/mean). Optional; default 0.30."
    },
    "service_level": {
      "type": "number",
      "description": "Target cycle service level (in-stock probability, e.g. 0.95). Optional; default 0.95."
    },
    "annual_holding_rate_pct": {
      "type": "number",
      "description": "Annual holding cost as a fraction of unit value (e.g. 0.25). Optional; default 0.25."
    },
    "ordering_cost_usd": {
      "type": "number",
      "description": "Fixed cost per purchase order (USD). Optional; default 250."
    },
    "units_per_container": {
      "type": "number",
      "description": "Units per ocean container (for the annual freight trade-off). Optional."
    },
    "air_weight_kg": {
      "type": "number",
      "description": "Air shipment weight per consignment (kg) to price the air freight side of the trade-off. Optional."
    },
    "air_volume_m3": {
      "type": "number",
      "description": "Air shipment volume per consignment (m³). Optional."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD). Optional; default today."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "annual_demand_units",
    "unit_value_usd"
  ]
}

total_cost_ownership

The CFO / supply-chain-director cumbre tool: ONE comparable number per strategy that ties the WHOLE chain together. Give a product + destination + per-unit baseline FOB + annual demand, and it composes, PER STRATEGY (origin × mode): PRODUCT cost (origin cost index), all-in FREIGHT (door-to-door), DUTY/landed (Section 301 / FTA preference), INVENTORY cost (safety stock + cycle holding driven by the lead time & its variability), CAPITAL-IN-TRANSIT (pipeline value × cost of capital), and a RISK premium (lane-risk score × inventory value). It ranks the strategies by TOTAL TCO and shows WHY the ranking flips: nearshore (Mexico) can BEAT China on TCO even with a pricier product (no Section 301, shorter lead → less inventory+capital, lower risk); AIR can win for HIGH-VALUE goods (the capital+inventory saving dwarfs the freight premium); and the ranking shifts with volume and unit value. This is the tool that ties the entire freight-pulse stack into one decision. Honest (regla 7): composes the indicative outputs of the sourcing/landed/transit/inventory/lane-risk engines; not an audited cost or a binding tariff classification. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters17

product	string	required	Product text ('bluetooth earbuds') or an HS code. REQUIRED.
hs_code	string	optional	Explicit HS code (alternative to product).
dest_port	string	required	Destination port. REQUIRED.
fob_value	number	required	Per-unit baseline FOB (the China-equivalent manufactured cost) in USD. REQUIRED — other origins scale from it.
annual_demand_units	number	required	Annual demand in UNITS. REQUIRED.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
candidates	array	optional	Candidate origin ISO2 codes (CN, VN, IN, MX, TR, TH, ID, MY). Optional; default the China+1 set.
include_air	boolean	optional	Also evaluate AIR per origin. Optional; default true.
units_per_container	number	optional	Units per container. Optional; default a value-density proxy.
air_weight_kg	number	optional	Air weight per container-equivalent (kg) to price air. Optional.
demand_cv	number	optional	Demand CV. Optional; default 0.30.
service_level	number	optional	Service level. Optional; default 0.95.
annual_holding_rate_pct	number	optional	Holding rate. Optional; default 0.25.
annual_capital_rate_pct	number	optional	Cost of capital. Optional; default 0.12.
ordering_cost_usd	number	optional	Ordering cost per PO. Optional; default 250.
risk_cost_factor	number	optional	Fraction of avg inventory value charged as expected-disruption cost (scaled by lane-risk/100). Optional; default 0.5.
ship_date	string	optional	Ship date (YYYY-MM-DD). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "description": "Product text ('bluetooth earbuds') or an HS code. REQUIRED."
    },
    "hs_code": {
      "type": "string",
      "description": "Explicit HS code (alternative to product)."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port. REQUIRED."
    },
    "fob_value": {
      "type": "number",
      "description": "Per-unit baseline FOB (the China-equivalent manufactured cost) in USD. REQUIRED — other origins scale from it."
    },
    "annual_demand_units": {
      "type": "number",
      "description": "Annual demand in UNITS. REQUIRED."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Candidate origin ISO2 codes (CN, VN, IN, MX, TR, TH, ID, MY). Optional; default the China+1 set."
    },
    "include_air": {
      "type": "boolean",
      "description": "Also evaluate AIR per origin. Optional; default true."
    },
    "units_per_container": {
      "type": "number",
      "description": "Units per container. Optional; default a value-density proxy."
    },
    "air_weight_kg": {
      "type": "number",
      "description": "Air weight per container-equivalent (kg) to price air. Optional."
    },
    "demand_cv": {
      "type": "number",
      "description": "Demand CV. Optional; default 0.30."
    },
    "service_level": {
      "type": "number",
      "description": "Service level. Optional; default 0.95."
    },
    "annual_holding_rate_pct": {
      "type": "number",
      "description": "Holding rate. Optional; default 0.25."
    },
    "annual_capital_rate_pct": {
      "type": "number",
      "description": "Cost of capital. Optional; default 0.12."
    },
    "ordering_cost_usd": {
      "type": "number",
      "description": "Ordering cost per PO. Optional; default 250."
    },
    "risk_cost_factor": {
      "type": "number",
      "description": "Fraction of avg inventory value charged as expected-disruption cost (scaled by lane-risk/100). Optional; default 0.5."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD). Optional."
    }
  },
  "required": [
    "product",
    "dest_port",
    "fob_value",
    "annual_demand_units"
  ]
}

contingency_plan

'My route just broke — what do I do AHEAD of the next sailing?' Give a lane and it detects the ACTIVE disruption (Red-Sea/Bab-el-Mandeb, Panama Canal drought, port labour strike, typhoon/hurricane, peak congestion — reusing the disruption catalogue) and generates an ACTIONABLE response playbook: alternate ROUTING (Cape of Good Hope), MODAL-SHIFT (air/sea-air the urgent slice), PORT-SWAP (divert to the unaffected coast/gateway), PRE-POSITION (build buffer ahead of the window), RE-PRIORITISE — each PRICED against the lane's real freight & lead time: the modeled cost (USD) and time (days) of plan B versus HOLDING. It ranks the plays by your urgency (cost-first vs time-first) and recommends one. Pass disruption_type to model a specific what-if even if it isn't currently active. Honest (regla 7): MODELED, indicative response options & deltas — not a guarantee of alternate-routing space; validate availability with your carrier/forwarder. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters6

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Ship date (YYYY-MM-DD) — selects which seasonal/dated disruptions are active. Optional; default today.
disruption_type	string	optional	Force a specific disruption: 'red-sea' / 'panama' / 'labor' / 'weather' / 'peak' (else the most severe active one is chosen; an inactive type is modeled as a what-if). Optional.
urgency	string	optional	'cost' (minimise spend), 'time' (minimise delay) or 'balanced'. Optional; default balanced.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) — selects which seasonal/dated disruptions are active. Optional; default today."
    },
    "disruption_type": {
      "type": "string",
      "description": "Force a specific disruption: 'red-sea' / 'panama' / 'labor' / 'weather' / 'peak' (else the most severe active one is chosen; an inactive type is modeled as a what-if). Optional."
    },
    "urgency": {
      "type": "string",
      "description": "'cost' (minimise spend), 'time' (minimise delay) or 'balanced'. Optional; default balanced."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

decarbonization_roadmap

A PROGRAMME to cut the carbon of your transport network to a target. Give a lane (or an annual network footprint in tonnes CO2e) and a reduction TARGET %, and it walks the abatement levers cheapest-$/tCO2e first on a marginal-abatement-cost curve: MODAL SHIFT (air→ocean / →sea-air — the biggest lever, often NEGATIVE cost because it also saves freight), CONSOLIDATION, EFFICIENT CARRIER, SAF book-and-claim (sustainable aviation fuel), ALTERNATIVE MARINE FUEL (green-methanol book-and-claim), and — last — VERIFIED OFFSETS. It returns the ordered roadmap with each lever's tonnes abated, cost and running marginal cost, the total programme cost and blended $/tCO2e, an honest REDUCTION-vs-OFFSET split (insetting > offsetting), and the EU-ETS € SAVING from the lower in-scope footprint. Honest (regla 7): MODELED, indicative abatement costs/ceilings (SAF & offset prices are volatile and quality-dependent); offsets are flagged compensation, NOT reduction, and a target beyond what reduction levers reach is clearly labelled. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters9

origin_port	string	optional	Origin port (for a lane-based baseline). Optional if baseline_co2e_tonnes is given.
dest_port	string	optional	Destination port. Optional if baseline_co2e_tonnes is given.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
reduction_target	number	optional	Reduction target as a fraction (0.30) or percent (30). Optional; default 0.30.
baseline_co2e_tonnes	number	optional	Supply an annual NETWORK footprint (tonnes CO2e) instead of deriving from a lane. Optional.
weight_kg	number	optional	Cargo weight for the lane emissions baseline (kg). Optional.
allowed_levers	array	optional	Restrict to specific lever ids (modal-shift-air-to-ocean, consolidation, saf-book-and-claim, alt-marine-fuel, verified-offsets, …). Optional; default all.
cost_band	string	optional	Cost sensitivity: 'low' / 'typical' / 'high'. Optional; default typical.
ship_date	string	optional	Ship date (YYYY-MM-DD) — drives the EU-ETS phase-in year. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (for a lane-based baseline). Optional if baseline_co2e_tonnes is given."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port. Optional if baseline_co2e_tonnes is given."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "reduction_target": {
      "type": "number",
      "description": "Reduction target as a fraction (0.30) or percent (30). Optional; default 0.30."
    },
    "baseline_co2e_tonnes": {
      "type": "number",
      "description": "Supply an annual NETWORK footprint (tonnes CO2e) instead of deriving from a lane. Optional."
    },
    "weight_kg": {
      "type": "number",
      "description": "Cargo weight for the lane emissions baseline (kg). Optional."
    },
    "allowed_levers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Restrict to specific lever ids (modal-shift-air-to-ocean, consolidation, saf-book-and-claim, alt-marine-fuel, verified-offsets, …). Optional; default all."
    },
    "cost_band": {
      "type": "string",
      "description": "Cost sensitivity: 'low' / 'typical' / 'high'. Optional; default typical."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) — drives the EU-ETS phase-in year. Optional."
    }
  },
  "required": []
}

reverse_logistics

The reverse flow almost nobody models: goods have to come BACK from the destination market — what do you do with them? Give the lane + how many units + their value + condition (defective / RMA / over-stock / surplus), and it prices the three dispositions per unit and picks the best NET RECOVERY: RETURN (reverse freight ≈1.6× forward + recondition/handling, reclaiming the re-export DUTY DRAWBACK already paid — 99% recovery, but Section-301 duty is carved out), DESTROY in destination (cheap, zero product value, still drawback-eligible) or LIQUIDATE into the destination secondary market (some cash back, no reverse freight, no drawback). It proves the rule: high unit value + recoverable duty + cheap reverse freight → RETURN; reverse freight per unit above the recoverable value → never ship it home (destroy for the drawback, or liquidate locally — whichever nets more). Flags the storage bleed that forces the decision window. Honest (regla 7): INDICATIVE recovery fractions, freight multipliers & handling defaults you should override; drawback eligibility and the §301 carve-out are real but filing-specific — NOT customs/legal advice. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters14

origin_port	string	required	Origin port (where the goods would RETURN to). City name, UN/LOCODE, or 'City, Country'.
dest_port	string	required	Destination port (where the goods currently are).
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
quantity_units	number	required	How many units are coming back. REQUIRED.
unit_value_usd	number	required	Per-unit value (USD). REQUIRED — drives recovery, handling and the decision.
condition	string	optional	'defective' / 'rma' / 'overstock' / 'surplus' — sets recovery & recondition. Optional; default rma.
duty_paid_per_unit_usd	number	optional	Duty already paid per unit on the original import (USD) — drives the drawback reclaim. Optional; default 0.
section301_per_unit_usd	number	optional	Of that duty, the Section-301 slice per unit (USD) — NOT drawback-eligible. Optional; default 0.
drawback_eligible	boolean	optional	Is re-export/destruction drawback available to you? Optional; default true.
recondition_hub	string	optional	Return to a reconditioning HUB instead of origin (shorter, cheaper return leg). Optional.
forward_freight_per_unit_usd	number	optional	Override the forward per-unit freight (USD) instead of deriving it from the lane. Optional.
units_per_container	number	optional	Units per container — to spread container freight over units. Optional.
pending_days	number	optional	Days the goods sit pending a decision (storage bleed). Optional; default 0.
ship_date	string	optional	Ship date (YYYY-MM-DD) for the freight anchor. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (where the goods would RETURN to). City name, UN/LOCODE, or 'City, Country'."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port (where the goods currently are)."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "quantity_units": {
      "type": "number",
      "description": "How many units are coming back. REQUIRED."
    },
    "unit_value_usd": {
      "type": "number",
      "description": "Per-unit value (USD). REQUIRED — drives recovery, handling and the decision."
    },
    "condition": {
      "type": "string",
      "description": "'defective' / 'rma' / 'overstock' / 'surplus' — sets recovery & recondition. Optional; default rma."
    },
    "duty_paid_per_unit_usd": {
      "type": "number",
      "description": "Duty already paid per unit on the original import (USD) — drives the drawback reclaim. Optional; default 0."
    },
    "section301_per_unit_usd": {
      "type": "number",
      "description": "Of that duty, the Section-301 slice per unit (USD) — NOT drawback-eligible. Optional; default 0."
    },
    "drawback_eligible": {
      "type": "boolean",
      "description": "Is re-export/destruction drawback available to you? Optional; default true."
    },
    "recondition_hub": {
      "type": "string",
      "description": "Return to a reconditioning HUB instead of origin (shorter, cheaper return leg). Optional."
    },
    "forward_freight_per_unit_usd": {
      "type": "number",
      "description": "Override the forward per-unit freight (USD) instead of deriving it from the lane. Optional."
    },
    "units_per_container": {
      "type": "number",
      "description": "Units per container — to spread container freight over units. Optional."
    },
    "pending_days": {
      "type": "number",
      "description": "Days the goods sit pending a decision (storage bleed). Optional; default 0."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) for the freight anchor. Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "quantity_units",
    "unit_value_usd"
  ]
}

pallet_plan

Optimize PALLETIZATION across the full chain product → case → pallet → container (distinct from the box→container load optimizer). Give a case (carton) size & weight, a pallet standard (EUR 1200×800, EUR2 1200×1000, US/GMA 48×40, AU 1165) and a container, and it computes: cases per pallet (best layer pattern from both case orientations + pinwheel × layers, capped by the pallet weight AND the container height), pallets per container (floor footprint × single-vs-double-stack under the ceiling, capped by payload), and the % container CUBE UTILISATION. It then contrasts PALLETIZED vs FLOOR-LOADED: floor-loading reclaims the ~12–18% cube a pallet wastes (deck + top-air + footprint rounding) but is ~4× slower to handle and bruises more cargo — the real trade-off, quantified in extra cases and cube points. Pass a total case count for the pallets/containers your shipment needs. Honest (regla 7): INDICATIVE rectangular-packing geometry capped by weight/height — not a stow guarantee; real patterns depend on crush strength, interlocking and overhang. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters9

case_length_mm	number	optional	Case (carton) length in mm. Optional; default 400.
case_width_mm	number	optional	Case width in mm. Optional; default 300.
case_height_mm	number	optional	Case height in mm. Optional; default 250.
case_weight_kg	number	optional	Case weight in kg. Optional; default 12.
pallet	string	optional	Pallet standard: 'EUR' (1200×800), 'EUR2' (1200×1000), 'US' (48×40), 'AU' (1165). Optional; default EUR.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'/reefer. Optional; default 40HC.
reefer	boolean	optional	Reefer container. Optional; default false.
allow_double_stack	boolean	optional	Allow double-stacking pallets if height permits. Optional; default true.
total_cases	number	optional	Total shipment case count → pallets & containers needed. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "case_length_mm": {
      "type": "number",
      "description": "Case (carton) length in mm. Optional; default 400."
    },
    "case_width_mm": {
      "type": "number",
      "description": "Case width in mm. Optional; default 300."
    },
    "case_height_mm": {
      "type": "number",
      "description": "Case height in mm. Optional; default 250."
    },
    "case_weight_kg": {
      "type": "number",
      "description": "Case weight in kg. Optional; default 12."
    },
    "pallet": {
      "type": "string",
      "description": "Pallet standard: 'EUR' (1200×800), 'EUR2' (1200×1000), 'US' (48×40), 'AU' (1165). Optional; default EUR."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'/reefer. Optional; default 40HC."
    },
    "reefer": {
      "type": "boolean",
      "description": "Reefer container. Optional; default false."
    },
    "allow_double_stack": {
      "type": "boolean",
      "description": "Allow double-stacking pallets if height permits. Optional; default true."
    },
    "total_cases": {
      "type": "number",
      "description": "Total shipment case count → pallets & containers needed. Optional."
    }
  },
  "required": []
}

customs_valuation

Compute the correct DUTIABLE BASE on which the duty is charged — it is NOT just the invoice. Under the WTO Customs Valuation Agreement, give the destination country + invoice price + Incoterm and it builds the TRANSACTION VALUE: it normalises the price to an FOB-origin base (stripping freight/insurance/destination/duty a CIF or DDP price already carries), then ADDS the statutory additions importers forget — ASSISTS (free tooling/moulds/design — inflate the base), royalties, SELLING commission, packing — while EXCLUDING buying commission and post-import costs, and applies the COUNTRY BASIS: CIF (EU & most — international freight+insurance IN the base) vs FOB (US — excluded). It returns the line-by-line base, the duty on the correct base vs the naive invoice (the over/under-payment), and the DEDUCTIVE (resale-back-calc) and COMPUTED (cost build-up) methods when there is no transaction value. Honest (regla 7): INDICATIVE model of the method hierarchy & adjustments; related-party tests, first-sale and assist apportionment are case-specific — NOT a customs ruling or legal advice. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters20

dest_country	string	required	Destination country ISO2 (US, DE, GB, …). REQUIRED — sets the CIF/FOB basis.
invoice_price_usd	number	optional	The price actually paid/payable (total, or per-unit if per_unit=true). REQUIRED for transaction value.
quantity_units	number	optional	Quantity of units (for per-unit assists apportionment & per-unit output). Optional; default 1.
per_unit	boolean	optional	Is invoice_price_usd a PER-UNIT figure? Optional; default false (total).
incoterm	string	optional	Incoterm of the price (EXW/FOB/CIF/DDP…). Optional; default FOB.
method	string	optional	'transaction-value' (default), 'deductive' or 'computed'.
assists_usd	number	optional	Assists supplied free (tooling/moulds/materials/design), TOTAL USD — ADD to base. Optional.
royalties_usd	number	optional	Royalties/licence fees that are a condition of sale, TOTAL USD. Optional.
selling_commission_usd	number	optional	Selling commission (to seller's agent), TOTAL USD — dutiable. Optional.
buying_commission_usd	number	optional	Buying commission (to buyer's own agent), TOTAL USD — NOT dutiable (shown excluded). Optional.
packing_usd	number	optional	Packing & containers cost, TOTAL USD. Optional.
international_freight_usd	number	optional	International freight to the import port, TOTAL USD (in base on CIF basis only). Optional.
insurance_usd	number	optional	International insurance, TOTAL USD (in base on CIF basis only). Optional.
post_import_transport_usd	number	optional	Post-import transport/destination charges baked into a DAP/DDP price, TOTAL USD — stripped out. Optional.
baked_import_duty_usd	number	optional	Import duty/tax baked into a DDP price, TOTAL USD — stripped out. Optional.
duty_rate_pct	number	optional	Modeled duty rate (0.075 or 7.5) to value the over/under-payment vs the naive invoice. Optional.
resale_price_usd	number	optional	Deductive method: destination unit resale price (USD).
resale_margin_pct	number	optional	Deductive: resale gross margin to deduct (0.30). Optional; default 0.30.
deductible_inland_usd	number	optional	Deductive: per-unit post-import freight+duties to deduct (USD). Optional.
computed_unit_cost_usd	number	optional	Computed method: built-up unit cost (materials+fabrication+profit+expenses), USD.

Raw schema

{
  "type": "object",
  "properties": {
    "dest_country": {
      "type": "string",
      "description": "Destination country ISO2 (US, DE, GB, …). REQUIRED — sets the CIF/FOB basis."
    },
    "invoice_price_usd": {
      "type": "number",
      "description": "The price actually paid/payable (total, or per-unit if per_unit=true). REQUIRED for transaction value."
    },
    "quantity_units": {
      "type": "number",
      "description": "Quantity of units (for per-unit assists apportionment & per-unit output). Optional; default 1."
    },
    "per_unit": {
      "type": "boolean",
      "description": "Is invoice_price_usd a PER-UNIT figure? Optional; default false (total)."
    },
    "incoterm": {
      "type": "string",
      "description": "Incoterm of the price (EXW/FOB/CIF/DDP…). Optional; default FOB."
    },
    "method": {
      "type": "string",
      "description": "'transaction-value' (default), 'deductive' or 'computed'."
    },
    "assists_usd": {
      "type": "number",
      "description": "Assists supplied free (tooling/moulds/materials/design), TOTAL USD — ADD to base. Optional."
    },
    "royalties_usd": {
      "type": "number",
      "description": "Royalties/licence fees that are a condition of sale, TOTAL USD. Optional."
    },
    "selling_commission_usd": {
      "type": "number",
      "description": "Selling commission (to seller's agent), TOTAL USD — dutiable. Optional."
    },
    "buying_commission_usd": {
      "type": "number",
      "description": "Buying commission (to buyer's own agent), TOTAL USD — NOT dutiable (shown excluded). Optional."
    },
    "packing_usd": {
      "type": "number",
      "description": "Packing & containers cost, TOTAL USD. Optional."
    },
    "international_freight_usd": {
      "type": "number",
      "description": "International freight to the import port, TOTAL USD (in base on CIF basis only). Optional."
    },
    "insurance_usd": {
      "type": "number",
      "description": "International insurance, TOTAL USD (in base on CIF basis only). Optional."
    },
    "post_import_transport_usd": {
      "type": "number",
      "description": "Post-import transport/destination charges baked into a DAP/DDP price, TOTAL USD — stripped out. Optional."
    },
    "baked_import_duty_usd": {
      "type": "number",
      "description": "Import duty/tax baked into a DDP price, TOTAL USD — stripped out. Optional."
    },
    "duty_rate_pct": {
      "type": "number",
      "description": "Modeled duty rate (0.075 or 7.5) to value the over/under-payment vs the naive invoice. Optional."
    },
    "resale_price_usd": {
      "type": "number",
      "description": "Deductive method: destination unit resale price (USD)."
    },
    "resale_margin_pct": {
      "type": "number",
      "description": "Deductive: resale gross margin to deduct (0.30). Optional; default 0.30."
    },
    "deductible_inland_usd": {
      "type": "number",
      "description": "Deductive: per-unit post-import freight+duties to deduct (USD). Optional."
    },
    "computed_unit_cost_usd": {
      "type": "number",
      "description": "Computed method: built-up unit cost (materials+fabrication+profit+expenses), USD."
    }
  },
  "required": [
    "dest_country"
  ]
}

booking_strategy

When and how to RESERVE space so your box isn't rolled and your cargo isn't stranded on the dock. Give the lane + ship date + criticality, and it reads the demand PRESSURE (composing the seasonality calendar — CNY / Golden Week / transpacific peak — with the equipment-crunch signal) into a band (slack → acute), then returns: the optimal BOOKING WINDOW (lead days, plus a criticality buffer, and the date to book by), the SPOT vs CONTRACT rollover probability and roll-delay days, and the GUARANTEED/PREMIUM-booking trade-off — the certain premium surcharge vs the expected rollover-delay cost of riding spot (roll prob × delay days × per-day criticality cost). It recommends spot, a guaranteed booking, or — if your committed volume justifies it — a named-account allocation. Proves: peak/CNY → book earlier + pay for the guarantee; slack market → ride spot. Honest (regla 7): INDICATIVE rollover probabilities & premiums by band (reusing the real seasonality/equipment calendars) — not a space guarantee or carrier quote. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters7

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Ship date (YYYY-MM-DD) — selects the seasonal/equipment pressure. Optional; default today.
criticality	string	optional	'low' / 'normal' / 'high' / 'critical' — how badly a rollover delay hurts. Optional; default normal.
base_freight_per_container_usd	number	optional	Base ocean freight per container (USD) to price the premium & delay cost. Optional — derived if omitted.
annual_containers	number	optional	Annual committed volume on this lane (containers/yr) — triggers the named-account allocation call. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) — selects the seasonal/equipment pressure. Optional; default today."
    },
    "criticality": {
      "type": "string",
      "description": "'low' / 'normal' / 'high' / 'critical' — how badly a rollover delay hurts. Optional; default normal."
    },
    "base_freight_per_container_usd": {
      "type": "number",
      "description": "Base ocean freight per container (USD) to price the premium & delay cost. Optional — derived if omitted."
    },
    "annual_containers": {
      "type": "number",
      "description": "Annual committed volume on this lane (containers/yr) — triggers the named-account allocation call. Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

cold_chain

Cold-chain / pharma (GDP) compliance for a TEMPERATURE-CONTROLLED shipment — beyond a reefer setpoint. Give the lane + the product (e.g. 'pharma vaccines 2-8°C', 'frozen seafood', 'bananas') or a sensitivity class, and it returns the temperature requirement, the THERMAL-EXCURSION risk across the transit, the recommended MODE + thermal packaging, and the GDP datalogger/chain-validation needs. The core insight: excursion risk RISES with transit DURATION. It reads the iter3 transit p90 for the ocean routing and runs a survival model per packaging option (ocean active reefer, ocean qualified-passive PCM/VIP, active air) — a long Cape-diverted reefer accumulates far more deviation exposure (and a gen-set/fuel/plug failure tail) than a 3-day air leg. Each option is totalled = freight + packaging premium + monitoring + EXPECTED THERMAL LOSS (excursion × loss-fraction × cargo value), and the lowest-total option wins. Proves: pharma 2-8°C on a long transit → high excursion risk → fly it with active cooling OR use qualified passive packaging; a frozen load on a short lane → ocean reefer is fine. For GDP cargo it mandates continuous data-logging, pre-cool, a validated lane and a documented chain. Honest (regla 7): INDICATIVE GDP/cold-chain model — excursion probabilities, MKT, packaging performance and loss fractions are modeled typicals, NOT a GDP qualification, stability statement or QA release. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters11

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Ship date (YYYY-MM-DD) — selects the transit/diversion state. Optional; default today.
product	string	optional	Product description — 'pharma vaccines 2-8°C', 'frozen seafood', 'bananas', 'fresh produce', 'insulin'. Sets the temperature requirement & sensitivity.
sensitivity	string	optional	Explicit sensitivity class — ambient \| cool \| chilled \| frozen \| pharma \| pharma-critical. Overrides the product match. Provide this OR 'product'.
cargo_value_usd	number	optional	Total cargo value (USD) — drives the expected-loss economics. Optional; a class default is used if omitted.
unit_value_usd	number	optional	Per-unit value (USD) — with 'units', an alternative to cargo_value_usd. Optional.
units	number	optional	Number of units (with unit_value_usd). Optional.
ocean_freight_usd	number	optional	Override the ocean all-in freight per container (USD). Optional — derived if omitted.
air_freight_multiple	number	optional	Air freight as a multiple of ocean (default ~6-7×). Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) — selects the transit/diversion state. Optional; default today."
    },
    "product": {
      "type": "string",
      "description": "Product description — 'pharma vaccines 2-8°C', 'frozen seafood', 'bananas', 'fresh produce', 'insulin'. Sets the temperature requirement & sensitivity."
    },
    "sensitivity": {
      "type": "string",
      "description": "Explicit sensitivity class — ambient | cool | chilled | frozen | pharma | pharma-critical. Overrides the product match. Provide this OR 'product'."
    },
    "cargo_value_usd": {
      "type": "number",
      "description": "Total cargo value (USD) — drives the expected-loss economics. Optional; a class default is used if omitted."
    },
    "unit_value_usd": {
      "type": "number",
      "description": "Per-unit value (USD) — with 'units', an alternative to cargo_value_usd. Optional."
    },
    "units": {
      "type": "number",
      "description": "Number of units (with unit_value_usd). Optional."
    },
    "ocean_freight_usd": {
      "type": "number",
      "description": "Override the ocean all-in freight per container (USD). Optional — derived if omitted."
    },
    "air_freight_multiple": {
      "type": "number",
      "description": "Air freight as a multiple of ocean (default ~6-7×). Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

rate_benchmark

Benchmark a rate you ALREADY PAY against the market — the 'am I being clamped?' check every shipper wants. Give the lane + the rate you pay (paid_rate_usd) and it places that rate in the MARKET BAND of the corridor (percentile against p20 / median / p80), built from the cross-validated index mid (Drewry WCI + Freightos FBX) and the corridor's modeled rate dispersion. It returns where you sit (p20 = a strong price, median = fair, p80 = over-paying), how much you OVER- or UNDER-pay vs the market mid in $/container and per YEAR at your volume, and the LEVER to correct it — renegotiate to the median, tender the lane, switch carrier/alliance, or lock a good price. A contract rate sitting above the median in a soft/falling market is flagged for renegotiation, not just labelled expensive. Proves: a rate at the p80 → 'you over-pay $X/ctr; renegotiate toward the median to save $X×volume/yr'; a rate at the p20 → 'good price, hold it'. The SAME rate is placed differently as the live band moves. Honest (regla 7): the band is a MODELED dispersion around the index mid, NOT a panel of real quotes — a true benchmark needs a rate panel (Xeneta/SeaRates). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters8

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port.
paid_rate_usd	number	required	The rate you currently PAY for this lane (USD per container). REQUIRED — this is what gets benchmarked.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Ship date (YYYY-MM-DD) for the market read. Optional; default today.
basis	string	optional	'spot' (default — bare ocean freight) or 'all-in' (base + surcharges) — match it to what your paid rate INCLUDES. Optional.
annual_containers	number	optional	Annual containers on this lane — to annualise the over/under-payment & savings. Optional.
is_contract	boolean	optional	Is the paid rate a CONTRACT rate? Flags a high contract in a soft/falling market. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port."
    },
    "paid_rate_usd": {
      "type": "number",
      "description": "The rate you currently PAY for this lane (USD per container). REQUIRED — this is what gets benchmarked."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) for the market read. Optional; default today."
    },
    "basis": {
      "type": "string",
      "description": "'spot' (default — bare ocean freight) or 'all-in' (base + surcharges) — match it to what your paid rate INCLUDES. Optional."
    },
    "annual_containers": {
      "type": "number",
      "description": "Annual containers on this lane — to annualise the over/under-payment & savings. Optional."
    },
    "is_contract": {
      "type": "boolean",
      "description": "Is the paid rate a CONTRACT rate? Flags a high contract in a soft/falling market. Optional."
    }
  },
  "required": [
    "origin_port",
    "dest_port",
    "paid_rate_usd"
  ]
}

appointment_plan

Plan the terminal APPOINTMENT and the box sequence so you don't eat demurrage & detention. US/EU terminals require a timed appointment to pick up the import container and to return the empty; miss the window and dwell climbs and D&D starts. Give the lane + ship date and it reads the destination port congestion (iter7) at arrival, derives APPOINTMENT-SLOT availability (how far out the first slot is and how likely a desired slot is missed — the real dwell driver), then returns: the OPTIMAL PICKUP WINDOW (late enough not to pre-pay storage, with a reserve for a missed slot, by-date inside your free days), the PICKUP→EMPTY-RETURN sequence (a dual transaction where the port supports it to cut detention), and the expected D&D of the plan vs sending the trucker blind, with the saving. Proves: a congested port (LA/LB at peak) → tight slot window, book earlier, dual-transaction the empty → saves $X of D&D; a fluid port → same-day slots, relaxed window, no premium. Honest (regla 7): INDICATIVE — appointment availability, slot scarcity and dual-transaction behaviour are modeled by port & congestion band, NOT a live terminal appointment feed (eModal/Voyage/TideWorks). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters7

origin_port	string	required	Origin port (city name, UN/LOCODE, or 'City, Country').
dest_port	string	required	Destination port — where the box is picked up & the empty returned.
container_type	string	optional	Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'.
ship_date	string	optional	Ship date (YYYY-MM-DD) — sets the arrival window & congestion. Optional; default today.
discharge_clear_days	number	optional	Days to discharge + customs-clear before the box is available for pickup. Optional; default 2.
import_free_days	number	optional	Your contract's import (demurrage) free days. Optional — a regional default is used.
empty_return_free_days	number	optional	Your contract's empty-return (detention) free days. Optional — a regional default is used.

Raw schema

{
  "type": "object",
  "properties": {
    "origin_port": {
      "type": "string",
      "description": "Origin port (city name, UN/LOCODE, or 'City, Country')."
    },
    "dest_port": {
      "type": "string",
      "description": "Destination port — where the box is picked up & the empty returned."
    },
    "container_type": {
      "type": "string",
      "description": "Container '20ft'/'40ft'/'40HC'. Optional; default '40ft'."
    },
    "ship_date": {
      "type": "string",
      "description": "Ship date (YYYY-MM-DD) — sets the arrival window & congestion. Optional; default today."
    },
    "discharge_clear_days": {
      "type": "number",
      "description": "Days to discharge + customs-clear before the box is available for pickup. Optional; default 2."
    },
    "import_free_days": {
      "type": "number",
      "description": "Your contract's import (demurrage) free days. Optional — a regional default is used."
    },
    "empty_return_free_days": {
      "type": "number",
      "description": "Your contract's empty-return (detention) free days. Optional — a regional default is used."
    }
  },
  "required": [
    "origin_port",
    "dest_port"
  ]
}

select_provider

Choose the right freight INTERMEDIARY — freight forwarder, 3PL/4PL, customs broker, NVOCC or carrier-direct — and know how to grade them. Give a NEED profile (priority cost vs service, cargo specialisation reefer/dangerous-goods/project/e-commerce/high-value, annual volume, corridor count, whether you need warehousing, whether customs is the hard part) and it scores every provider archetype on weighted criteria (corridor coverage, specialisation, technology/visibility, customs depth, cost, service, financial stability), RANKS them, recommends the provider TYPE (+ a pairing, e.g. niche forwarder + customs broker), and emits a weighted SCORECARD you fill in for real candidates. Proves: a reefer-heavy, low-volume, service-led need → a niche cold-chain forwarder tops the rank (NOT a generic mega-3PL); a high-volume cost-led need on a few lanes → carrier-direct / NVOCC; a customs-heavy need pulls in a customs-broker pairing. The criterion weights shift with the need, so the recommendation changes when the profile changes. Honest (regla 7): INDICATIVE archetypes & weights — NOT an endorsement of, or performance claim about, any named provider; run your own RFI/references. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.

Parameters7

priority	string	optional	'cost' \| 'service' \| 'balanced' — the primary driver. Optional; default balanced.
specialisation	string	optional	Cargo specialisation needed: 'reefer' / 'dangerous-goods' / 'project' / 'ecommerce' / 'high-value' / 'none'. Optional; default none.
cargo_type	string	optional	Alias for 'specialisation' — a free-text cargo description is parsed into a specialisation. Optional.
annual_containers	number	optional	Annual container volume (rough) — sets the volume band (low <50, mid, high ≥500). Optional.
corridor_count	number	optional	Number of distinct corridors/regions you ship. Optional; default 1.
needs_warehousing	boolean	optional	Do you need warehousing/fulfilment, not just transport? Pulls toward 3PL/4PL. Optional.
customs_heavy	boolean	optional	Is customs the hard part (high-duty, regulated, FTA-heavy)? Pulls in a customs broker. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "priority": {
      "type": "string",
      "description": "'cost' | 'service' | 'balanced' — the primary driver. Optional; default balanced."
    },
    "specialisation": {
      "type": "string",
      "description": "Cargo specialisation needed: 'reefer' / 'dangerous-goods' / 'project' / 'ecommerce' / 'high-value' / 'none'. Optional; default none."
    },
    "cargo_type": {
      "type": "string",
      "description": "Alias for 'specialisation' — a free-text cargo description is parsed into a specialisation. Optional."
    },
    "annual_containers": {
      "type": "number",
      "description": "Annual container volume (rough) — sets the volume band (low <50, mid, high ≥500). Optional."
    },
    "corridor_count": {
      "type": "number",
      "description": "Number of distinct corridors/regions you ship. Optional; default 1."
    },
    "needs_warehousing": {
      "type": "boolean",
      "description": "Do you need warehousing/fulfilment, not just transport? Pulls toward 3PL/4PL. Optional."
    },
    "customs_heavy": {
      "type": "boolean",
      "description": "Is customs the hard part (high-duty, regulated, FTA-heavy)? Pulls in a customs broker. Optional."
    }
  },
  "required": []
}

README.md6 KBView on GitHub

freight-pulse 🚢

Ocean & multimodal freight intelligence suite for AI agents. One MCP server that answers any shipping question an importer, CFO, or supply-chain agent actually asks — from "what's the spot rate Shanghai → LA?" to "what's my total landed cost with duty?" to "should I book this lane now or wait?" — across 47 tools covering rates, total landed cost, transit reliability, customs, risk, emissions, and a unified ship decision.

Give it a lane, an HS code, a value — get back one trustworthy, cross-validated answer with a confidence read, not one vendor's quote. The rate engine, port normalization, customs logic, and the accumulating per-lane history all run server-side (the moat); the npm package is a thin client.

Hosted endpoint: https://freight-pulse-mcp.vercel.app/mcp · streamable-HTTP, no signup for the free tier.

Why an agent picks this

A single freight API returns one vendor's number with no second opinion and stops at the rate. freight-pulse goes the whole distance an importer needs:

Cross-validated rates. Reads Drewry's World Container Index (WCI) and the Freightos Baltic Index (FBX) server-side (plus your own SeaRates key if you supply one) and reconciles them into one normalized USD figure with a confidence score (do the sources agree?) and a market direction (rising / falling / stable).
The whole decision, not just the price. Landed cost with HS-code duty, all-in door-to-door, transit time + reliability (p90), air-vs-ocean trade-off, customs, risk, CO₂ — folded into a single ship_decision verdict: BOOK NOW / WAIT / SWITCH MODE.
Its own accumulating history. Every lane queried is cached with a timestamp; trend tools serve a weeks-long normalized series no single index hands an agent for free.
Public, non-sensitive inputs. Ports, HS codes, declared values — nothing secret. Safe for an agent to call without handing over credentials.

Worked example — Shanghai → Los Angeles, 40ft, $180k of cargo

code

💲 get_spot_rate     → $5,442 / 40ft · confidence 🟢 80/100 · cross-validated from Drewry + FBX (spread 11%)
🧾 get_all_in_rate   → $6,910 all-in (BAF, THC, doc, ISF, drayage folded in)
📦 get_landed_cost   → $193,180 delivered  (rate + 3.4% duty on HS 8516 + MPF/HMF + insurance)
🚢 ship_decision     → BOOK NOW  ·  rate stable-to-rising, equipment available, transit p90 within SLA

One agent call chain, one verdict. That's the difference between a freight API and a freight agent.

What's inside — 47 tools

Area	Tools
Rates & trend	`get_spot_rate` (FREE), `get_lane_trend`, `get_all_in_rate`, `rate_benchmark` (am I overpaying?)
Total cost	`get_landed_cost`, `total_cost_ownership`, `customs_valuation`, `customs_optimization`
Decision	`ship_decision`, `simulate_scenario`, `compare_modes` (air vs ocean), `sourcing_analysis` (China+1 / nearshoring)
Transit & risk	`get_port_intel` (congestion), `lane_risk_index`, `disruption`, `contingency_plan`, `get_scorecard`
Procurement	`procurement_strategy`, `build_tender`, `evaluate_bids`, `select_provider` (forwarder/3PL), `record_performance`
Customs & docs	`required_documents`, `incoterm_responsibility`, `qualify_fta_origin`, `export_compliance`, `check_lc_documents`
Carriers & equipment	`carrier_recommendation`, `equipment_availability`, `booking_strategy`, `appointment_plan`, `dnd_strategy` (demurrage & detention)
Inland & load	`door_to_door`, `load_plan`, `pallet_plan`, `optimize_network`, `cold_chain`
Finance & risk	`payment_terms`, `fx_exposure`, `insurance_recommendation`, `inventory_optimization`
Sustainability	`carbon_footprint` (GLEC/ISO 14083), `decarbonization_roadmap`, `reverse_logistics`
Monitoring	`create_watch`, `check_watches`, `market_report`, `special_cargo`

get_spot_rate is free (the hook). The deep analytical tools are premium.

Quickstart (MCP)

jsonc

{
  "mcpServers": {
    "freight-pulse": {
      "command": "npx",
      "args": ["-y", "freight-pulse-mcp"],
      "env": {
        // optional: unlock premium tools with a prepaid key
        "FREIGHT_PULSE_KEY": "fp_…",
        // optional: your own SeaRates key — cross-validated as a THIRD source, RAISES confidence
        "SEARATES_API_KEY": "…"
      }
    }
  }
}

Or connect over HTTP at POST https://freight-pulse-mcp.vercel.app/mcp (streamable).

Free vs Pro

	Free	Pro
`get_spot_rate` (cross-validated rate + confidence + direction)	✅	✅
All 40+ analytical tools (landed cost, ship_decision, customs, risk, trend, …)	upsell preview	✅ full result
Accumulating per-lane trend history	—	✅
Pay how	—	🪙 x402 (USDC on Base) per call — agents pay automatically, no signup · or 💳 card via Stripe checkout for a prepaid key

Two ways to pay a premium call:

🪙 x402 (USDC on Base) — an x402-aware agent pays per call automatically, zero signup.
💳 Card (Stripe) — buy a prepaid API key, send it as Authorization: Bearer <key> (or set FREIGHT_PULSE_KEY).

On the data

freight-pulse is indicative market intelligence cross-validated from public freight indices and customs references — not a carrier quote or a booking. Always verify with your forwarder before committing. Drewry WCI and Freightos FBX publish weekly assessments; the optional SeaRates source is bring-your-own-key (it only raises confidence, never required).

The analysis engine — index fetching, port/HS normalization, cross-validation, the confidence model, customs/duty logic, and the per-lane history cache — runs server-side. The npm package is a thin client that forwards to the hosted service.

MIT · github.com/Baneado98/freight-pulse · Hosted at freight-pulse-mcp.vercel.app

Install

Tools (47)

get_spot_rateget_lane_trendget_all_in_rateget_landed_costcompare_modesprocurement_strategyget_port_intelcarrier_recommendation

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://freight-pulse-mcp.vercel.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "freight-pulse": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://freight-pulse-mcp.vercel.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

freight-pulse 🚢 (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

get_spot_rate

get_lane_trend

get_all_in_rate

get_landed_cost

compare_modes

procurement_strategy

get_port_intel

carrier_recommendation

carbon_footprint

equipment_availability

incoterm_responsibility

required_documents

dnd_strategy

insurance_recommendation

ship_decision

simulate_scenario

door_to_door

load_plan

optimize_network

payment_terms

special_cargo

export_compliance

fx_exposure

build_tender

evaluate_bids

customs_optimization

sourcing_analysis

market_report

create_watch

check_watches

qualify_fta_origin

check_lc_documents

record_performance

get_scorecard

lane_risk_index

inventory_optimization

total_cost_ownership

contingency_plan

decarbonization_roadmap

reverse_logistics

pallet_plan

customs_valuation

booking_strategy

cold_chain

rate_benchmark

appointment_plan

select_provider

freight-pulse 🚢

Why an agent picks this

Worked example — Shanghai → Los Angeles, 40ft, $180k of cargo

What's inside — 47 tools

Quickstart (MCP)

Free vs Pro

On the data

Install

Remote endpoint

Related servers