List major container ports, optionally filtered by region.

This is the grounding tool — call it first when you need to know which ports are relevant to a route or region before calling other tools.

Args: region: Optional region filter. Available regions: East Asia, Southeast Asia, South Asia, Middle East, Red Sea, Northwest Europe, Mediterranean, North America West, North America East. Leave empty to list all ports.

Returns: dict with 'region', 'port_count', and 'ports' list

Get current weather conditions and 24-hour forecast for a port.

Weather is sourced from Open-Meteo (free, no API key required). Pay attention to wind speed in knots — values above 25 kn affect large vessel operations; above 40 kn typically suspends port activity.

Args: port_name: Port common name (e.g. "Rotterdam") or UN/LOCODE (e.g. "NLRTM")

Returns: dict with current conditions, wind speed, operational impact assessment, and hourly 24h forecast

Get live vessel positions from AIS transponder data for a shipping region.

Uses AISStream.io free WebSocket feed (requires AISSTREAM_API_KEY in .env). Listens for ~8 seconds and returns a snapshot of vessels in the region.

Named regions this tool recognizes (not specific to any one route — use whichever apply to the route you're assessing): "South China Sea", "East China Sea", "Strait of Malacca", "Indian Ocean", "Red Sea", "Suez Canal", "Persian Gulf", "Mediterranean", "English Channel", "North Sea", "Taiwan Strait", "East Asia", "Northwest Europe", "North America West", "North America East"

Args: region: Named region — see list above, or call list_major_ports() for context max_vessels: Maximum vessels to return (default 20)

Returns: dict with vessel_count, underway/anchored breakdown, and per-vessel details (MMSI, name, position, speed, course, nav status)

Search recent news for supply chain disruption signals.

Uses NewsAPI (free tier, 100 req/day — requires NEWS_API_KEY in .env). Returns articles with a 'flagged_high_signal' list highlighting those mentioning strikes, storms, blockages, attacks, or sanctions.

If the query names a known port or shipping region, results are filtered to articles that actually mention that place — this prevents e.g. a Red Sea query returning unrelated Strait of Hormuz coverage just because both mention "attack". Check the 'location_filter' and 'filtered_out' fields in the response to see if/how this applied. Lead each query with the exact place name for the filter to engage.

Example query shapes — lead with the place actually relevant to your route, not necessarily these:

• " port delay" (e.g. "Rotterdam port delay")

• " attack blockage" (e.g. "Red Sea attack blockage")

• " disruption" (e.g. "Suez Canal disruption")

• "container shipping freight rates" (no location — not filtered)

Args: query: Search query string, ideally leading with a specific place name days: Days back to search (default 7, max 30 on free tier)

Returns: dict with articles list, flagged_high_signal subset, and location_filter/filtered_out showing whether results were filtered

Get current congestion metrics for a port: vessel queue, wait times, capacity utilization, trend, and operational advisory.

Data is realistically mocked (live data requires MarineTraffic or FreightWaves enterprise subscription). The interface mirrors what a production integration would return.

Args: port_name: Port common name or UN/LOCODE

Returns: dict with capacity_utilization_pct, vessels_queued, estimated_wait_hours, trend_vs_yesterday, severity, and advisory