Cortex booking

Read the business card: what it is, where the work happens, its hours and time zone, its services with prices and lengths, what a booking needs (the customer's details and the questions to answer), whether a booking is confirmed at once or sent as a request, the limits and the cancel rule. Call it first.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Find the start times that are open for what is being booked, between two dates (at most 14 days). Pass `windows` (the customer's free time from their calendar) to get only the starts that fit both calendars. Returns ISO 8601 times with offsets. Only open times are ever shown.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "What is being booked. May be left out only when the business offers exactly one service (a consulting business's one kind of call). A window tint business takes `tint` instead, never items.",
      "items": {
        "type": "object",
        "description": "One service being booked. Use the `slug` of a service from the business card. For a business that works on a car, give each car its package and any add-ons as separate items that share the same `label` (the car, as a person would say it: \"2023 Porsche 911\"), and a `label` is required on every item.",
        "properties": {
          "slug": {
            "type": "string",
            "description": "The service's slug, from the card's services list.",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "integer",
            "description": "How many of it. Default 1.",
            "minimum": 1,
            "maximum": 50,
            "default": 1
          },
          "label": {
            "type": "string",
            "description": "What the service is for: the car (\"2023 Porsche 911\"). Required for a detailing business; leave out for a meeting.",
            "maxLength": 300
          }
        },
        "required": [
          "slug"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50
    },
    "tint": {
      "type": "object",
      "description": "What is being booked at a window tint business, in place of `items` (the card says which a business takes): the class of the customer's car, the windows, the film and the shade, each chosen from the card's `tint` section. The business prices and times it; a shade never changes the price. Choosing the front two windows and the rear sides books the full vehicle, at its price.",
      "properties": {
        "vehicle_class": {
          "type": "string",
          "enum": [
            "coupe",
            "sedan",
            "truck",
            "suv",
            "suv_xl"
          ],
          "description": "The class of the customer's car: an id from the card's tint.vehicleClasses, each of which lists example models."
        },
        "glass": {
          "type": "array",
          "description": "The windows to tint: slugs from the card's tint.glass, each once.",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "minItems": 1,
          "maxItems": 50,
          "uniqueItems": true
        },
        "film": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "The film: a slug from the card's tint.films."
        },
        "shade": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "description": "The percentage of light the film lets through (lower is darker), for every window: one of the chosen film's shades."
        },
        "zone_shades": {
          "type": "object",
          "description": "Optional: a different shade for a window group the chosen glass covers, by the group's id from the card's tint.windowGroups ({\"fr\": 35, \"rr\": 20}). Each is one of the film's shades; a group left out takes `shade`.",
          "additionalProperties": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          }
        }
      },
      "required": [
        "vehicle_class",
        "glass",
        "film",
        "shade"
      ],
      "additionalProperties": false
    },
    "from": {
      "type": "string",
      "format": "date",
      "description": "First day, YYYY-MM-DD, in the business's time zone (the card names it). Not in the past."
    },
    "to": {
      "type": "string",
      "format": "date",
      "description": "Last day, YYYY-MM-DD. At most 14 days from `from`, counting both, and at most 60 days from today."
    },
    "windows": {
      "type": "array",
      "description": "The customer's free time, as intervals with offsets. When given, only starts whose whole job or meeting fits inside one window come back. Leave out to see every open start.",
      "items": {
        "description": "A stretch of time the customer is free, from their own calendar. Both ends are ISO 8601 with an offset (\"2026-10-12T09:00:00-07:00\" or \"...Z\"), and the end is after the start. Written either as {start, end} or as one ISO 8601 interval string \"start/end\".",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "start": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})$"
              },
              "end": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})$"
              }
            },
            "required": [
              "start",
              "end"
            ],
            "additionalProperties": false
          },
          {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})/\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})$",
            "description": "An ISO 8601 interval: \"2026-10-12T09:00:00-07:00/2026-10-12T17:00:00-07:00\"."
          }
        ]
      },
      "maxItems": 50
    }
  },
  "required": [
    "from",
    "to"
  ],
  "description": "Ask for the start times that are open. Only the business's own open times come back, narrowed to the customer's free windows when given.",
  "additionalProperties": false,
  "examples": [
    {
      "items": [
        {
          "slug": "discovery-call"
        }
      ],
      "from": "2026-10-07",
      "to": "2026-10-13",
      "windows": [
        {
          "start": "2026-10-07T08:00:00-07:00",
          "end": "2026-10-07T18:00:00-07:00"
        }
      ]
    }
  ]
}

For a business that comes to the customer: check the service address before booking. Send it as one line, as fields, or as a place_id saved from an earlier check. The answer says whether Google confirmed it (`verdict`), the address to book with (send it as answers.address), its place_id (save both for this customer; next time send the place_id, with the apartment or unit as extended_address if there is one), and whether it is inside the area the business serves. Book when `bookable` is true; when the verdict is `confirm`, read the corrected address to the customer first. `next` says what to do otherwise.

{
  "type": "object",
  "properties": {
    "address": {
      "oneOf": [
        {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "The address as one line: \"123 Main St, Poway, CA 92064\"."
        },
        {
          "type": "object",
          "description": "The address as fields, in any one of three spellings: schema.org PostalAddress (streetAddress, extendedAddress, addressLocality, addressRegion, postalCode, addressCountry), the same in snake_case (street_address, extended_address, address_locality, address_region, postal_code, address_country), or line_one, line_two, city, state, postal_code, country. A street is required. Or send `place_id`, a Google Place ID saved from an earlier check of this customer's address, with the apartment or unit as extended_address if there is one.",
          "properties": {
            "street_address": {
              "type": "string",
              "maxLength": 200
            },
            "extended_address": {
              "type": "string",
              "maxLength": 200,
              "description": "Apartment, suite or unit."
            },
            "address_locality": {
              "type": "string",
              "maxLength": 200,
              "description": "The city."
            },
            "address_region": {
              "type": "string",
              "maxLength": 200,
              "description": "The state, as its two-letter code."
            },
            "postal_code": {
              "type": "string",
              "maxLength": 200
            },
            "address_country": {
              "type": "string",
              "maxLength": 200,
              "description": "A two-letter country code; US when left out."
            },
            "place_id": {
              "type": "string",
              "maxLength": 300,
              "description": "A Google Place ID from an earlier check, alone."
            }
          },
          "additionalProperties": true
        }
      ]
    }
  },
  "required": [
    "address"
  ],
  "description": "Check a service address before booking a business that comes to the customer: whether Google confirms it, the address to book with, and whether it is inside the area the business serves.",
  "additionalProperties": false,
  "examples": [
    {
      "address": "123 Main St, Poway, CA 92064"
    },
    {
      "address": {
        "street_address": "123 Main St",
        "address_locality": "Poway",
        "address_region": "CA",
        "postal_code": "92064"
      }
    }
  ]
}

Book one of the open times for the customer. The business then either confirms it at once or receives it as a request it approves (or, for a business that takes its bookings by email, confirms with the customer itself); the answer says which, what happens next, and a `manage.token` to check or cancel the booking later. The customer is emailed. Confirm the service, the time and the customer's details with the customer before calling it. `idempotency_key` is required: choose a new random one for each booking (a UUID without hyphens) and send the same one to retry after a timeout, so a retry cannot make a second booking.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "What is being booked. May be left out only when the business offers exactly one service (a consulting business's one kind of call). A window tint business takes `tint` instead, never items.",
      "items": {
        "type": "object",
        "description": "One service being booked. Use the `slug` of a service from the business card. For a business that works on a car, give each car its package and any add-ons as separate items that share the same `label` (the car, as a person would say it: \"2023 Porsche 911\"), and a `label` is required on every item.",
        "properties": {
          "slug": {
            "type": "string",
            "description": "The service's slug, from the card's services list.",
            "minLength": 1,
            "maxLength": 200
          },
          "quantity": {
            "type": "integer",
            "description": "How many of it. Default 1.",
            "minimum": 1,
            "maximum": 50,
            "default": 1
          },
          "label": {
            "type": "string",
            "description": "What the service is for: the car (\"2023 Porsche 911\"). Required for a detailing business; leave out for a meeting.",
            "maxLength": 300
          }
        },
        "required": [
          "slug"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50
    },
    "tint": {
      "type": "object",
      "description": "What is being booked at a window tint business, in place of `items` (the card says which a business takes): the class of the customer's car, the windows, the film and the shade, each chosen from the card's `tint` section. The business prices and times it; a shade never changes the price. Choosing the front two windows and the rear sides books the full vehicle, at its price.",
      "properties": {
        "vehicle_class": {
          "type": "string",
          "enum": [
            "coupe",
            "sedan",
            "truck",
            "suv",
            "suv_xl"
          ],
          "description": "The class of the customer's car: an id from the card's tint.vehicleClasses, each of which lists example models."
        },
        "glass": {
          "type": "array",
          "description": "The windows to tint: slugs from the card's tint.glass, each once.",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "minItems": 1,
          "maxItems": 50,
          "uniqueItems": true
        },
        "film": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "The film: a slug from the card's tint.films."
        },
        "shade": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "description": "The percentage of light the film lets through (lower is darker), for every window: one of the chosen film's shades."
        },
        "zone_shades": {
          "type": "object",
          "description": "Optional: a different shade for a window group the chosen glass covers, by the group's id from the card's tint.windowGroups ({\"fr\": 35, \"rr\": 20}). Each is one of the film's shades; a group left out takes `shade`.",
          "additionalProperties": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          }
        }
      },
      "required": [
        "vehicle_class",
        "glass",
        "film",
        "shade"
      ],
      "additionalProperties": false
    },
    "start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::00(?:\\.0+)?)?(?:Z|[+-]\\d{2}:\\d{2})$",
      "description": "A start time from `times`, ISO 8601 with an offset, on a whole minute: seconds, when written, are 00 (\"2026-10-12T10:00:00-07:00\" or \"2026-10-12T17:00Z\"). It is checked again, and refused with `time_not_open` if it is no longer open."
    },
    "customer": {
      "type": "object",
      "description": "The person the booking is for. They receive the confirmation email.",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Full name."
        },
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 320
        },
        "phone": {
          "type": "string",
          "maxLength": 50,
          "description": "Optional, unless the business's questions say it is required."
        },
        "time_zone": {
          "type": "string",
          "maxLength": 64,
          "description": "Optional IANA zone of the customer (\"Europe/London\"): a meeting's confirmation then shows their clock too."
        }
      },
      "required": [
        "name",
        "email"
      ],
      "additionalProperties": false
    },
    "answers": {
      "type": "object",
      "description": "Answers to the questions the card lists under booking.answers, by their `id`. Each question there says its exact format and shows an example that passes: a select takes exactly one of its option strings, copied character for character; a multiselect takes a list of its option strings (at most its `maxSelections`, each once); a text, a long text, an email, a phone number and a web address each have a stated length limit; a select with `allowOther` takes \"Other\" with the customer's own words under `<id>_other`; and a question with a `none` phrase takes exactly that phrase when there is no answer. A business that comes to the customer (a mobile detailer or tint shop) asks for `address`: check it first (POST /agent/address, the MCP tool check_address) and send the `address` that answers. The address is checked again here, and refused with `address_invalid`, `address_unconfirmed` (with the corrected address) or `outside_service_area`. When Google could not confirm it or corrected it, and the customer says theirs is right as they gave it, send theirs with `address_confirmed: true`: it is filed as given, for the business to check (never past `outside_service_area`). Leave out when the card lists none.",
      "additionalProperties": true
    },
    "agent": {
      "type": "object",
      "description": "Who is booking, so the business sees that an agent made the booking and which one.",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80,
          "description": "What the agent is called (\"Muse\", \"ChatGPT\")."
        },
        "acting_for": {
          "type": "string",
          "maxLength": 120,
          "description": "Optional: the person it acts for, if that is not the customer."
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{32,255}$",
      "minLength": 32,
      "maxLength": 255,
      "description": "Required. A key you choose, new for each booking: 32 to 255 letters, digits, dashes or underscores, and RANDOM, never a counter, a word or a pattern (a UUID without hyphens is right; a key with fewer than 8 distinct characters is refused). Calling book again with the same key and customer email answers the first booking again, with the same manage token, instead of making a second one: use it to retry safely after a timeout."
    }
  },
  "required": [
    "start",
    "customer",
    "agent",
    "idempotency_key"
  ],
  "description": "Book. The same checks as the business's booking page: a real open start, the questions the card lists, the same limits on every text.",
  "additionalProperties": false,
  "examples": [
    {
      "items": [
        {
          "slug": "discovery-call"
        }
      ],
      "start": "2026-10-07T08:00:00-07:00",
      "customer": {
        "name": "Ada Lovelace",
        "email": "[email protected]",
        "phone": "(619) 555-0123",
        "time_zone": "Europe/London"
      },
      "answers": {
        "business_name": "Analytical Engines Ltd",
        "website": "analyticalengines.example",
        "industry": "Professional services",
        "team_size": "Just me",
        "decider": "I decide with a partner",
        "pains": [
          "Slow replies to new leads",
          "Hours of admin and data entry"
        ],
        "notes": "We lose leads that message after hours.",
        "timeline": "In the next three months",
        "budget": "Not sure yet"
      },
      "agent": {
        "name": "Your agent name"
      },
      "idempotency_key": "replace-this-with-a-fresh-random-key-0000"
    }
  ]
}

Check a booking made through this door: whether it is requested, confirmed, declined or cancelled, and whether it can still be cancelled here.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "The booking's `reference`, from book."
    },
    "token": {
      "type": "string",
      "description": "The booking's `manage.token`, from book."
    }
  },
  "required": [
    "reference",
    "token"
  ],
  "additionalProperties": false
}

Cancel a booking made through this door: withdraws a request still waiting, or cancels a booking the business confirmed at once. A booking the business has approved must be changed with the business directly (the answer says how). Ask the customer first.

{
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "description": "The booking's `reference`, from book."
    },
    "token": {
      "type": "string",
      "description": "The booking's `manage.token`, from book."
    }
  },
  "required": [
    "reference",
    "token"
  ],
  "additionalProperties": false
}