ship_decision
Integrates all freight-pulse layers to produce one actionable decision for a shipment: recommended mode, carrier, timing, total landed cost, and key risks with mitigations, considering urgency and deadlines.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origin_port | Yes | Origin port (city, UN/LOCODE, or 'City, Country'). | |
| dest_port | Yes | Destination port (city, UN/LOCODE, or 'City, Country'). | |
| value | Yes | Merchandise value (USD) — REQUIRED. Drives mode-choice (capital in transit), insurance and (with a product) landed cost. | |
| container_type | No | Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'. | |
| weight_kg | No | Shipment gross weight (kg) — sharpens mode-choice (air chargeable weight) and emissions. Optional. | |
| volume_m3 | No | Shipment volume (m³) — drives the air volumetric weight. Optional. | |
| product | No | Product description or HS context — enables the landed-cost (duty) component. Optional. | |
| hs_code | No | Explicit HS code (alternative to product). Optional. | |
| urgency | No | 'relaxed', 'normal' (default), 'urgent' or 'critical'. A critical/urgent shipment shifts the recommendation toward speed (air/sea-air) and a reliability-led carrier. | |
| deadline | No | Hard arrival deadline (ISO 'YYYY-MM-DD') — adds an expected-stockout cost to the mode decision. Optional. | |
| ship_date | No | Intended ship date (ISO). Drives seasonality, congestion and the book-now call. Optional; defaults to today. | |
| incoterm | No | Optional Incoterms 2020 rule (EXW…DDP) — sets who carries transit risk in the risk assessment. | |
| carrier | No | Optional preferred carrier (refines equipment & D&D). | |
| annual_volume | No | Optional annual volume (containers) — informational for the decision context. |