Cancellation Flow

Sequence

verify_member
  --> get_active_trips
  --> cancel_trip(trip_id)            # Step 1: returns available reasons
  --> [present reasons to member]
  --> cancel_trip(trip_id, reason)    # Step 2: fuzzy-match + cancel

cancel_trip is now a single-tool two-step pattern. The separate get_cancellation_reasons tool was removed in v2.0 — fetching the reasons IS the first call to cancel_trip (the no-reason variant). This halves the round-trip count and removes a stale read tool that always paired 1:1 with cancel_trip anyway.

sequenceDiagram participant Agent participant MCP Agent->>MCP: verify_member(member_id, dob) MCP-->>Agent: session_id Agent->>MCP: get_active_trips(session_id) MCP-->>Agent: trips[] with trip_id Agent->>MCP: cancel_trip(session_id, trip_id) [no reason] MCP-->>Agent: available_reasons[] (Step 1) Note over Agent: Present reasons to member Agent->>MCP: cancel_trip(session_id, trip_id, reason="Member Request") MCP-->>Agent: status=cancelled (Step 2)

Step-by-Step

Step 1: verify_member

Establish a session for the member. Same as the booking flow.

Step 2: get_active_trips

List the member’s active trips to find the trip to cancel.

Input: session_id
Output: trips[] with trip_id, confirmation_number, status, addresses, times

Step 3: cancel_trip (no reason — fetch reasons)

Call cancel_trip WITHOUT a reason arg. The use case fetches the available reasons for THIS specific trip and returns them. No cancellation is performed.

Input: session_id, trip_id
Output: available_reasons[] with reason_id (UUID), name, description_required (boolean)

Step 4: Present to Member

Show the reasons to the member; let them choose. Conversational step, handled by the AI agent.

Step 5: cancel_trip (with reason — cancel)

Call cancel_trip again WITH the chosen reason.

Input: session_id, trip_id, reason (the chosen reason name OR its reason_id UUID)
Optional: reason_description — required when the matched reason carries description_required: true
Matcher order: case-insensitive id → exact case-insensitive name → bidirectional substring (single hit) → UUID/numeric pass-through
Uses the Customer initiator (member-facing reasons)

Cancelling a Standing Order

cancel_standing_order follows the same two-step pattern: omit reason to fetch, pass reason to cancel.

Error Scenarios

Error	Recovery
`NO_SESSION`	Call verify_member first
No active trips	Inform member they have no trips to cancel
`MISSING_PREREQUISITE` (`could not match cancellation reason`)	Re-call without `reason` to see the available list, then re-call with one of those names
`MISSING_PREREQUISITE` (`ambiguous match`)	The supplied substring matched multiple reasons; pick a more specific name or pass the `reason_id`
`MISSING_PREREQUISITE` (`requires a reason_description`)	Re-call with `reason_description` set