create_booking_intent

Instructions

Implementation Reference

• src/server.ts:452-475 (registration)

  Tool definition (name, description, input schema) for 'create_booking_intent' registered in the ALL_TOOLS array.

  {
    name: "create_booking_intent",
    description:
      "Create a booking intent — returns a deep-link the user clicks to complete the booking on autonomad.ai. The first booking they complete unlocks a 1-month free Autonomad Premium trial automatically. ALWAYS call this instead of trying to book directly through MCP — bookings require payment + identity verification that must happen on the web. \n\nWHEN TO CALL — two distinct triggers:\n  (a) PICK intents (flight / hotel / activity / event / transport / trip): call AFTER the user has chosen a specific offer.\n  (b) BROWSE intent ('experiences'): call IMMEDIATELY in the SAME assistant turn that you ran search_activities and/or search_events for a browse query. Do NOT wait for the user to ask 'where's the link?' — the user already told you they want this when they asked to browse. Showing search results without also producing the deep-link is a UX failure: it forces the subscriber to manually request something they already implicitly asked for.\n\nINTENT TYPE GUIDE — pick exactly one:\n- 'flight'   → user picked a flight only. offer_data = the flight offer object verbatim from search_flights, PLUS a top-level `passengers: <number>` field (the number of travelers the user originally requested — search_flights individual offers don't echo this back, so you must add it explicitly).\n- 'hotel'    → user picked a hotel only. offer_data = the hotel offer object verbatim from search_hotels (or just {city, check_in, check_out} if you want to send them to a hotel-search results page rather than a specific hotel). Include `adults: <number>` and `rooms: <number>` so the booking page pre-fills the right party size.\n- 'activity' → user picked a Viator activity. offer_data = the activity offer.\n- 'event'    → user picked a Ticketmaster/SeatGeek event. offer_data = the event offer.\n- 'transport'→ user picked a rideshare/car-rental quote. offer_data = the transport offer.\n- 'trip'     → user picked MULTIPLE things together (e.g. flight + hotel for the same trip). Pack them in offer_data as { flight: { ...offer, passengers: <n> }, hotel: { ...offer, adults: <n>, rooms: <n> }, activities: [<activity_offer>, ...] } — only include the keys the user actually picked. ONE deep-link covers all of them.\n- 'experiences' → BROWSE intent. The user wants to look at all activities AND events for a destination + date window WITHOUT picking a specific one. STRONGLY PREFER this over picking one activity yourself when the user asks to 'browse', 'see what's available', 'look at experiences in X', or just describes a destination/date range with no specific tour name. offer_data shape: { destination: 'City, Region', date_from: 'YYYY-MM-DD', date_to: 'YYYY-MM-DD', travelers?: <number>, activity_keywords?: [...], event_categories?: [...] }. The deep-link lands the subscriber on autonomad.ai's add-ons step with destination + dates pre-filled, where Viator activities and Ticketmaster/SeatGeek events for the area are surfaced together — and they can edit dates / traveler count inline. Use this whenever the subscriber's intent is 'show me everything', not 'I want this one specific tour'.\n\nPrefer 'trip' when the user said something like 'book me a flight and hotel for X' and you have both picked. Prefer 'experiences' when the user is asking to BROWSE activities/events without picking one (e.g. 'experiences between July 9 and July 13 near Stintino' → ONE deep-link, not 24 individual activity intents). Don't generate two separate intents (flight + hotel) for the same trip — that produces two deep-links and a confusing user experience.\n\nUSER-FACING REPLY REQUIREMENTS — every time you create a booking intent, your reply text MUST include:\n1. The deep_link as a clickable markdown link, e.g. '[Complete on autonomad.ai →](<deep_link>)' or 'Open: <deep_link>'.\n2. The 1-month free Autonomad Premium trial. The response payload carries a `free_trial_offer` object exactly so you can surface it. Use plain English (e.g. 'Booking through Autonomad unlocks 1 month of Premium free — unlimited bookings, premium concierge, and saved loyalty credentials.'). NEVER drop this; it is core to the value proposition and the only reason a booking-intent flow beats a raw Viator/Ticketmaster URL.\n3. The link expiry window (e.g. '~30 minutes — say the word and I'll regenerate if it lapses.').\n\nCRITICAL: always echo the original passenger / adults / travelers count into offer_data. Without it the booking page defaults to 2 travelers regardless of what the user asked for.",
    inputSchema: {
      type: "object" as const,
      properties: {
        intent_type: {
          type: "string",
          enum: ["flight", "hotel", "activity", "event", "transport", "trip", "experiences"],
          description: "Type of thing being booked. Use 'trip' for compound flight+hotel (or flight+hotel+activities) bookings; the single deep-link will pre-select all pieces on the autonomad.ai resume page. Use 'experiences' for browse-mode intents — the deep-link lands the subscriber on the add-ons step with all Viator activities + Ticketmaster events for the destination/date window, no specific pick required.",
        },
        offer_data: {
          type: "object",
          description: "For single-item intents (flight/hotel/activity/event/transport): pass the offer object verbatim from the corresponding search tool. For 'trip' intent: pass { flight, hotel, activities } where each value is the verbatim offer object the user picked. For 'experiences' intent: pass { destination, date_from, date_to, travelers? } — no specific offer needed, the dashboard surfaces all matching activities + events on arrival.",
        },
        expires_minutes: {
          type: "number",
          description: "Optional. How long the deep-link is valid. Defaults to 30 min (Duffel offers expire in ~20 min anyway). Capped at 24 hours.",
        },
      },
      required: ["intent_type", "offer_data"],
    },
  },

• src/server.ts:934-962 (handler)

  Handler function that executes the 'create_booking_intent' tool logic: posts to /v1/mcp/intents API with the MCP key, intent type, offer data, and optional expiration, then returns the deep-link and metadata.

  case "create_booking_intent": {
    const { intent_type, offer_data, expires_minutes } = args as {
      intent_type: string;
      offer_data: Record<string, unknown>;
      expires_minutes?: number;
    };
    const key = await ensureMcpKey();
    if (!key) {
      throw new Error("Could not bootstrap an MCP key for this installation. Please retry — if this persists, check internet access to api.autonomad.ai.");
    }
    const result = await apiCall("POST", "/v1/mcp/intents", {
      mcp_key: key,
      intent_type,
      offer_data,
      expires_minutes,
    });
    const data = (result as any)?.data ?? result;
    const deepLink = data?.deep_link as string | undefined;
    const expiresAt = data?.expires_at as string | undefined;
    const message = deepLink
      ? `Booking intent created. Click here to complete the booking on autonomad.ai (1-month free Autonomad Premium trial included on first booking):\n\n  ${deepLink}\n\nExpires: ${expiresAt || "30 minutes"}.`
      : "Booking intent created — see raw payload for the deep link.";
    return {
      content: [
        { type: "text", text: message },
        { type: "text", text: JSON.stringify(data, null, 2) },
      ],
    };
  }

• src/server.ts:456-474 (schema)

  Input schema for create_booking_intent: intent_type (enum), offer_data (object), and optional expires_minutes.

  inputSchema: {
    type: "object" as const,
    properties: {
      intent_type: {
        type: "string",
        enum: ["flight", "hotel", "activity", "event", "transport", "trip", "experiences"],
        description: "Type of thing being booked. Use 'trip' for compound flight+hotel (or flight+hotel+activities) bookings; the single deep-link will pre-select all pieces on the autonomad.ai resume page. Use 'experiences' for browse-mode intents — the deep-link lands the subscriber on the add-ons step with all Viator activities + Ticketmaster events for the destination/date window, no specific pick required.",
      },
      offer_data: {
        type: "object",
        description: "For single-item intents (flight/hotel/activity/event/transport): pass the offer object verbatim from the corresponding search tool. For 'trip' intent: pass { flight, hotel, activities } where each value is the verbatim offer object the user picked. For 'experiences' intent: pass { destination, date_from, date_to, travelers? } — no specific offer needed, the dashboard surfaces all matching activities + events on arrival.",
      },
      expires_minutes: {
        type: "number",
        description: "Optional. How long the deep-link is valid. Defaults to 30 min (Duffel offers expire in ~20 min anyway). Capped at 24 hours.",
      },
    },
    required: ["intent_type", "offer_data"],
  },

• src/server.ts:516-516 (helper)

  Tool annotation mapping for create_booking_intent providing safety hints: title 'Create Booking Deep-Link', readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true.

  create_booking_intent: { title: "Create Booking Deep-Link", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },