Skip to content
NEMT MCP Service

Trip Estimation Flow

The trip estimation flow composes route calculation, live weather, and buffer sizing to suggest an optimal pickup time before the member commits to booking. Always call estimate_trip before set_booking_details so the agent can quote realistic times and apply weather-aware buffering.

Tool Sequence

Section titled “Tool Sequence”
  1. verify_member
  2. (Optional) resolve_address or find_place — confirm pickup and dropoff
  3. estimate_trip — compute route + weather + suggested pickup
  4. set_booking_details — use the suggested pickup time from step 3
graph LR V["verify_member"] --> R["resolve_address / find_place
(pickup + dropoff)"] R --> E["estimate_trip
route + weather + buffer"] E --> S["set_booking_details
(use suggested_pickup)"] style V fill:#48bb78,color:#fff style R fill:#ed8936,color:#fff style E fill:#0bc5ea,color:#fff style S fill:#4299e1,color:#fff

Inputs

Section titled “Inputs”

Required: pickup, dropoff, session_id. Optional: arrival_time (YYYY-MM-DD HH:MM in America/New_York). Without arrival_time, the tool returns a route-only estimate using the current time for the traffic model and does not compute suggested_pickup.

Buffer Calculation

Section titled “Buffer Calculation”

Total buffer = travel buffer + weather buffer, applied to the traffic-aware drive time:

Layer Percent Condition
Travel 15% Always applied
Weather (snow) +30% Snow condition
Weather (rain) +20% Rain condition
Weather (fog / heavy precipitation) +20% Fog or heavy precip
Weather (wind) +10% Wind > 30 mph

When arrival_time is supplied:

suggested_pickup = arrival_time - (drive_minutes_traffic + total_buffer) minutes

weather_adjusted=true in the response tells the agent the pickup was padded for weather, and weather_advisory carries a human-readable reason to relay to the member.

Integrations

Section titled “Integrations”
  • Route: Google Directions API — returns drive time, traffic-aware drive time, distance, pickup coordinates, and a route summary.
  • Weather: Open-Meteo — returns the pickup-area forecast windowed around the arrival time (or now + 4 hours when no arrival).

Graceful Degradation

Section titled “Graceful Degradation”
  • Route failure is fatal; the tool returns an error.
  • Weather failure is NOT fatal. Weather fields are omitted, weather_adjusted=false, and the estimate is returned with baseline travel buffer only.
  • Cache read/write failures are non-fatal warnings.

Caching

Section titled “Caching”
  • Route: per-org_id, keyed by pickup|dropoff|hour-bucket (SHA-256 truncated to 16 hex chars), 1 hour TTL.
  • Weather: per-org_id, keyed by rounded_coords|hour-bucket, 15 min TTL.

Geographic Optimization

Section titled “Geographic Optimization”

Tuned for Virginia and nearby states (WV, MD, NC, DC, KY, TN). Default bias coordinates (used when the session does not expose home coordinates) are 37.4316, -78.6569 (Virginia center).

Standing Orders

Section titled “Standing Orders”

Do NOT call estimate_trip for recurring/standing-order bookings — the weather forecast is only valid for near-term trips. Use the standing-order flow for those and let the admin schedule times manually.

Section titled “Related”