Skip to main content
Glama

Create appointment

create_appointment
Destructive

Book a client for one or more services from a start time, with Booksy verifying each staff member's availability first so busy slots are refused instead of double-booked.

Instructions

Book a client for one or more services at a start time; Booksy checks the slots first.

Books one client card for service_id, or for several services in one appointment, each with its own staff member, back to back from start. Each end follows the service's duration. Booksy's dry run checks every staff member is free first; a busy slot is refused, never double-booked. The client gets Booksy's confirmation only with notify_client. dry_run returns the same answer with saved false and keeps nothing.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "client_id": "<client_id>",
      "start": "<start>"
    },
    "name": "create_appointment"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoInternal note, only staff see it.
startYesISO 8601. Without a time zone it is the business's local time.
dry_runNoOnly check the time and price; nothing is saved. Default: false.
servicesNoServices of the appointment in order, each starting when the one before ends.
staff_idNoStaff ID from list_staff, with service_id. Default: the first one who offers the service.
client_idYesClient ID from list_clients or add_client.
service_idNoservice_id from list_services (its first variant), or a variant_id. Or use services.
notify_clientNoSend Booksy's booking confirmation to the client. Default: false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.0.5
    • changedInput schema / properties / service_id / description
      Previous value: -"service_id from list_services (its first variant), or a variant_id."New value: +"service_id from list_services (its first variant), or a variant_id. Or use services."
    • addedInput schema / properties / services
      Added value: +{
      +  "description": "Services of the appointment in order, each starting when the one before ends.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "service_id": {
      +        "description": "service_id or variant_id from list_services.",
      +        "type": "string"
      +      },
      +      "staff_id": {
      +        "description": "Staff ID from list_staff. Default: the first one who offers the service.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "service_id"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 10,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / staff_id / description
      Previous value: -"Staff ID from list_staff. Default: the first one who offers the service."New value: +"Staff ID from list_staff, with service_id. Default: the first one who offers the service."
    • changedInput schema / required
      Previous value: -[
      -  "client_id",
      -  "service_id",
      -  "start"
      -]New value: +[
      +  "client_id",
      +  "start"
      +]
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructive/non-idempotent annotations, it discloses that slots are validated before booking, that double-booking is impossible, that each service's end time follows the service duration, that no confirmation is sent unless notify_client is set, and that dry_run saves nothing. That is substantial behavioral context an agent could not get from the annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and availability check are front-loaded, and the dry_run/notify_client behavior comes last where it belongs. A few clauses ("each end follows the service's duration", the repeated dry-run phrasing) are slightly dense but every sentence carries real information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with 8 parameters and no output schema, the description covers booking semantics, validation, dry-run behavior, and notification side effects. It stops short of stating what is returned on success (e.g. an appointment ID) or error behavior for invalid client/service IDs, which would complete the picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter meaning: service_id versus the services array, per-service staff assignment, back-to-back scheduling from start, and the notify_client/dry_run semantics. It does not add much on client_id or note, but the interaction rules are genuinely valuable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource ("Book a client for one or more services at a start time") and states the scope (single client card, one or several services). It is clearly distinguishable from siblings like find_open_slots (which only checks availability) and reschedule_appointment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says availability is checked first and a busy slot is refused, and it explains that notify_client is required to send a confirmation and dry_run is the non-committing path. It gives clear usage context but never explicitly names an alternative tool or exclusion (e.g. when to use find_open_slots first, or reschedule vs create).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.