estimate_trip

Status: Implemented | Module: planning

ALL-IN-ONE travel estimate: route + weather + optimal pickup time in a single call. Always call before set_booking_details. Returns travel time (normal + traffic-aware), distance, live weather at the pickup coordinates, a weather advisory, a weather-adjusted suggested pickup time, and the buffer breakdown (travel + weather). No need to call a separate weather tool — it is built in.

Do NOT use for standing-order trips. Optimized for Virginia and nearby states (WV, MD, NC, DC, KY, TN).

Annotations

Hint	Value
readOnlyHint	true
openWorldHint	true

Input

Field	Type	Required	Description
session_id	string	yes	Active session ID from verify_member
pickup	string	yes	Pickup address (e.g. 12411 Gayton Rd, Richmond, VA 23238)
dropoff	string	yes	Dropoff/destination address
arrival_time	string	no	When the member needs to ARRIVE at dropoff. YYYY-MM-DD HH:MM (24h). If omitted, uses current time for the traffic model; no suggested pickup time is computed.

arrival_time is parsed in America/New_York. Supported layouts: YYYY-MM-DD HH:MM, YYYY-MM-DDTHH:MM, YYYY-MM-DDTHH:MM:SS.

Output

Field	Type	Description
drive_time	string	Human drive time (45 min or 1h 20m)
drive_minutes	int	Traffic-aware drive minutes
distance	string	Human distance (e.g. 22.4 miles)
route	string	Route summary text from the directions provider
weather	string	Summary (e.g. Light rain, 52°F) — omitted when weather unavailable
weather_advisory	string	Advisory text (e.g. Heavy rain — allow extra time) — omitted when none
suggested_pickup	string	Weather-adjusted pickup time (YYYY-MM-DD HH:MM) — only when arrival_time is supplied
buffer_minutes	int	Total added buffer (travel 15% + weather 0-30%)
weather_adjusted	bool	True when the weather buffer was non-zero

Buffer Formula

The travel buffer is MAX(25 min, ceil(15% of traffic-aware drive time)) — the 25-minute floor protects short trips where 15% would otherwise yield only a few minutes of slack.

The weather buffer is conditional on isHazardousWeather() — only hazardous conditions add a buffer. Percentages are applied against the traffic-aware drive time:

• Snow: +30%
• Rain: +20%
• Fog or heavy precipitation: +20%
• Wind > 30 mph: +10%

(Light rain, partly cloudy, etc. do not trigger an extra buffer.)

When arrival_time is supplied, suggested_pickup is computed as:

suggested_pickup = arrival_time - (drive_minutes + total_buffer) minutes

The result is then rounded DOWN to the nearest 5-minute boundary (suggesting 1:25 PM is friendlier than 1:27 PM, and rounding down — never up — keeps the suggested pickup early enough to meet the appointment).

Departure time for the traffic model is seeded at arrival_time - 60 min when arrival is known.

Graceful Degradation

• Route fetch failure is fatal — the tool returns an error.
• Weather fetch failure is NOT fatal — the weather fields are omitted and the route-only estimate is returned with baseline buffer.
• Cache read/write failures are non-fatal (logged as warnings).

Caching

• Route cache: per org_id, keyed by pickup|dropoff|hour-bucket (SHA-256 truncated), 1h TTL.
• Weather cache: per org_id, keyed by rounded coordinates + hour bucket, 15 min TTL.

Cache keys are stable within an hour window and automatically regenerate with the traffic model.

Integrations

• Directions: Google Directions API (see internal/pkg/integrations/directions/).
• Weather: Open-Meteo (see internal/app/planning/adapters/weather/).

Side Effects

• Loads session and refreshes TTL.
• No audit write — lookup only (no PHI persisted).

Related

• Source: internal/app/planning/usecases/estimate_trip.go, internal/app/planning/adapters/mcp/handlers/estimate_trip.go
• Prerequisite: verify_member
• Next: set_booking_details