Booking management

join_booking_waitlist

Subscribe the customer to one email when their requested option becomes available. Requires explicit customer intent to receive the alert. Does not reserve, pay, or auto-book. The entry expires after the requested local date. Separate from the business signup waitlist.

View as Markdown

Scope & access

Directory + businessWrites data

Follow the credential fields below. Public discovery does not require a login; private booking operations require the indicated token.

This tool advertises idempotent behavior. If an idempotencyKey is specified, reuse it with identical arguments only when retrying that same intended action.

Parameters

These are the directory endpoint parameters. Business endpoints scope public discovery to the published business; owner calls still require businessId. Inspect tools/list on your endpoint for the exact schema.

offeringIdOptional

string

Offering ID from list_offerings, belonging to this business.

paramsRequired

object

Booking parameters from get_business.bookingParamsSchema. Hotel: checkIn/checkOut YYYY-MM-DD, adults. Restaurant: date, time HH:mm, partySize. Salon: offeringId, date, optional time/staffId. Dates and times use the business timezone.

nameRequired

string

Customer name for the availability notification.

emailRequired

string

Customer email address for one requested availability notification; does not grant marketing consent.

idempotencyKeyRequired

string

Generate a UUID per intended mutation. Reuse the same key and identical parameters only when retrying that action.

businessIdRequired

string

Published business ID from search_businesses, or the business's booking-page slug (e.g. "studio-nine"); owner calls may also use the business ID shown in the dashboard.

Example call

Pass this object to the MCP client's callTool method. Replace placeholders with returned IDs, saved credentials and the customer's details; use future dates appropriate to their request.

join_booking_waitlist · MCP client arguments

json

{
  "name": "join_booking_waitlist",
  "arguments": {
    "params": {
      "checkIn": "2026-11-14",
      "checkOut": "2026-11-16",
      "adults": 2
    },
    "name": "Asha Perera",
    "email": "asha@example.com",
    "idempotencyKey": "<new-UUID-for-this-action>",
    "businessId": "<businessId>"
  }
}

JSON schemas

Nested fields, formats, enums and constraints are included in the complete schemas. Successful data is returned in structuredContent. SDK input validation and domain errors use different error shapes.

Input schemaJSON Schema

Input JSON Schema

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "offeringId": {
      "type": "string",
      "minLength": 1,
      "description": "Offering ID from list_offerings, belonging to this business."
    },
    "params": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Booking parameters from get_business.bookingParamsSchema. Hotel: checkIn/checkOut YYYY-MM-DD, adults. Restaurant: date, time HH:mm, partySize. Salon: offeringId, date, optional time/staffId. Dates and times use the business timezone."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Customer name for the availability notification."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Customer email address for one requested availability notification; does not grant marketing consent."
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 8,
      "maxLength": 200,
      "description": "Generate a UUID per intended mutation. Reuse the same key and identical parameters only when retrying that action."
    },
    "businessId": {
      "type": "string",
      "minLength": 1,
      "description": "Published business ID from search_businesses, or the business's booking-page slug (e.g. \"studio-nine\"); owner calls may also use the business ID shown in the dashboard."
    }
  },
  "required": [
    "params",
    "name",
    "email",
    "idempotencyKey",
    "businessId"
  ]
}

Output schemaJSON Schema

Output JSON Schema

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "waitlistId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "const": "waiting"
    },
    "expiresAt": {
      "type": "string"
    },
    "currentlyAvailable": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "waitlistId",
    "status",
    "expiresAt",
    "currentlyAvailable",
    "message"
  ],
  "additionalProperties": false
}

Behavior annotationsMCP

Tool annotations

json

{
  "readOnlyHint": false,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}

Errors & next steps

Check isError before reading a success response. Follow nextStep where supplied, and never treat a pending booking as confirmed. See Errors and retries and the booking lifecycle for recovery paths.

Back to all tools