set_booking_details

Status: Verified | Module: booking

Set booking fields incrementally. Can be called multiple times. A no-op call (just session_id) returns the current draft status (collected_count / total_required / missing_fields) — this is the v2.0 replacement for the removed get_draft_status tool.

6 REQUIRED fields for booking: pickup_address, dropoff_address, appointment_time, trip_type, transport_mode, treatment_type. Roundtrips also require return_type (and return_time if scheduled).

• transport_mode is a static enum of 7 codes (see Input table) — server-side strict validation rejects anything else with a clear “must be one of” error. The agent can use verify_member.typical_service_type as a default.
• treatment_type is fuzzy-matched server-side against the org’s per-LOB catalogue. Exact / substring matches substitute the canonical name on the draft; ambiguous / no-match outcomes return INVALID_TREATMENT_TYPE carrying did_you_mean (top-3 alphabetical) or available (top-10 alphabetical) so the agent can recover without a follow-up tool call.

Annotations

Hint	Value
destructiveHint	false
idempotentHint	true

Input

Field	Type	Required	Description
session_id	string	yes	Active session
Address fields
pickup_address	object	booking-required	Structured address: {street, city, state, zip_code, latitude, longitude}. REQUIRED for booking.
dropoff_address	object	booking-required	Structured address: {street, city, state, zip_code, latitude, longitude}. REQUIRED for booking.
Facility/place details
pickup_facility_name	string	no	Name of pickup facility
dropoff_facility_name	string	no	Name of dropoff facility
pickup_apt_suite	string	no	Apt/suite at pickup (e.g. "Apt 204")
dropoff_apt_suite	string	no	Apt/suite at dropoff
pickup_phone	string	no	Contact phone at pickup. US format: 10 digits or 11 starting with 1.
dropoff_phone	string	no	Contact phone at dropoff. US format: 10 digits or 11 starting with 1.
Core booking fields
appointment_time	string	booking-required	YYYY-MM-DD HH:MM (24h), ISO 8601, or natural language. REQUIRED for booking.
pickup_time	string	no	Override auto-computed pickup time
trip_type	string	booking-required	one_way, roundtrip, standing_order. REQUIRED for booking.
transport_mode	string	booking-required	Static enum (case-insensitive): amb (ambulatory/walks), wc (standard wheelchair — under 350 lbs), bwc (bariatric wheelchair — over 350 lbs, extra-wide vehicle needed), str (stretcher/bed-bound), bls (basic life support), als (advanced life support), mileage_reimbursement (member drives self). Anything else is rejected. REQUIRED for booking.
return_type	string	roundtrip-required	will_call or scheduled. REQUIRED for roundtrip.
return_time	string	conditional	REQUIRED when return_type is scheduled.
treatment_type	string	booking-required	Treatment-type name. Server fuzzy-matches against the org’s per-LOB catalogue (exact / substring / ambiguous / none). REQUIRED for booking.
special_needs	string	no	Special accommodations
companion_name	string	no	Companion name (auto-sets adult_count=2)
companion_type	string	no	adult, child, attendant
notes	string	no	Additional trip notes
Passenger counts
adult_count	int	no	Number of adult passengers (default 1)
pca_count	int	no	Personal Care Attendants
attendant_count	int	no	Attendants/escorts (non-PCA)
child_count	int	no	Child passengers
Requester
requester_name	string	no	Person requesting on behalf of member
requester_phone	string	no	Requester phone. US format: 10 digits or 11 starting with 1.
requester_relationship	string	no	Member, Family, Facility, Case Manager
Optional IDs
service_type_id	string	no	Service type UUID from manifest
service_type	string	no	Service type code (for display)
treatment_type_id	string	no	Treatment type UUID from manifest
trip_purpose	string	no	medical or vab (auto-detected)

6 required fields for review: pickup_address, dropoff_address, appointment_time, trip_type, transport_mode (or service_type or service_type_id), treatment_type (or treatment_type_id). Roundtrips also require return_type (and return_time if scheduled).

Address format: Addresses must be structured objects with {street, city, state, zip_code, latitude, longitude}. Use the home_address from verify_member for home pickups, or coordinates from resolve_address candidates.

Transport mode static enum: The 7 codes listed in the table above are the ONLY accepted values (case-insensitive, surrounding whitespace tolerated). Legacy aliases like mr, standard, self_drive, sedan, wav, ambulatory are rejected to prevent silent mismapping. Internally the server still translates each code into the canonical proto value (standard for amb/wc/bwc/str/bls/als, mileage_reimbursement for MR) for the trip-create call.

Treatment type fuzzy matching (server-side, against the org’s per-LOB catalogue loaded by verify_member):

Outcome	Behaviour
Exact case-insensitive match	Canonical name (case-corrected) is stored on the draft.
Substring match (1 hit)	Canonical name is stored; treatment_type_normalization_note echoes the substitution (e.g. Matched "infusion" -> "Infusion Therapy").
Substring match (2+ hits)	Returns INVALID_TREATMENT_TYPE with did_you_mean (top-3 alphabetical).
No match	Returns INVALID_TREATMENT_TYPE with available (top-10 alphabetical).
Cache miss / new org	Returns INVALID_TREATMENT_TYPE with empty available — agent should re-call verify_member to refresh the cache.

Phone validation: All phone fields (pickup_phone, dropoff_phone, requester_phone, address phone) are validated as US format: 10 digits or 11 digits starting with 1. Formatting characters (spaces, dashes, parens, dots) are stripped before validation.

AI Agent Aliases

Models sometimes hallucinate field names. These are silently mapped:

Alias	Maps to
pickup_date	appointment_time
dropoff_time	appointment_time
destination	dropoff_address
origin	pickup_address
ride_type	trip_type
driver_notes	notes
special_requirements	special_needs

Date/Time Formats

Category	Examples
Preferred	2026-04-05 14:30 (YYYY-MM-DD HH:MM)
ISO 8601	2026-04-05T14:30:00Z
Natural	March 5 at 3pm, march 5th, 2026 at 3:00 PM
Relative	tomorrow at 3pm, next monday at 2pm

Output

Field	Type	Description
status	string	success or error
updated_fields	string[]	Fields set in this call
missing_fields	string[]	Fields still needed
collected_count	int	How many booking-relevant fields are populated on the draft (NEW in v2.0 — replaces get_draft_status)
total_required	int	How many required fields exist for this trip type (NEW in v2.0)
ready_to_confirm	bool	All required fields present
appointment_display	string	Formatted appointment time (when set)
pickup_time_display	string	Formatted pickup time (when set/computed)
trip_type	string	Current trip type
transport_mode	string	Current transport mode
service_type_id	string	Service type UUID (when set)
service_type	string	Service type code (when set)
trip_purpose	string	medical or vab (auto-detected from treatment_type if not supplied)
treatment_type	string	Treatment type name (when set)
return_type	string	will_call or scheduled (when set)
return_time_display	string	Human-readable return time (when scheduled)
treatment_type_normalization_note	string	Set when the fuzzy matcher case-corrected or substring-matched the caller’s treatment_type (e.g. Matched "infusion" -> "Infusion Therapy"). Empty for exact matches.
warnings	string[]	Weekend warnings, etc.
suggested_prompt	string	Natural-language prompt the AI should ask next

v2.0 audit changes (~600 B saved per call):

• Dropped pickup_formatted / dropoff_formatted echoes (the caller passed addresses in — no need to echo back).
• Dropped BookingProgress.Sequence / TotalSteps / StepName / CompletedSteps (sequence tracking moved to the sequence middleware; per-call payload no longer carries it).
• Added collected_count + total_required so a no-op call doubles as the status snapshot — folds in the responsibilities of the removed get_draft_status tool.

Example Request

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "set_booking_details",
    "arguments": {
      "session_id": "a1b2c3d4-...",
      "pickup_address": {
        "street": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62701",
        "latitude": 39.7817,
        "longitude": -89.6501
      },
      "dropoff_address": {
        "street": "456 Health Ave",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62701",
        "latitude": 39.7817,
        "longitude": -89.6501
      },
      "appointment_time": "2026-04-15 14:00",
      "trip_type": "roundtrip",
      "transport_mode": "wc",
      "return_type": "will_call",
      "treatment_type": "Dialysis"
    }
  }
}

Error Codes

• NO_SESSION / DRAFT_NOT_FOUND – No active session or draft
• INVALID_ADDRESS – Address incomplete or cannot be parsed
• INVALID_DATE – Date/time cannot be parsed
• INVALID_TREATMENT_TYPE – treatment_type could not be resolved against the org’s per-LOB catalogue. Error envelope carries did_you_mean (top-3 alphabetical) when the input matched 2+ candidates, or available (top-10 alphabetical) when it matched none. Agent should present the recovery list to the member and re-call.
• MISSING_PREREQUISITE – verify_member not called, or transport_mode outside the static 7-code enum (error message lists the allowed codes)

Related

• Booking Flow
• Next: review_trip