> ## Documentation Index
> Fetch the complete documentation index at: https://cal.id/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cal ID MCP Tool Reference

> Every tool the Cal ID MCP server exposes, grouped by what it does, plus the input types and booking rules that catch people out.

The Cal ID MCP server exposes **58 tools**. You rarely need to call them by name — describe what you want and your assistant picks the right one. This reference is for when you're debugging, checking whether something is possible, or writing a prompt that has to be precise.

<Info>
  Every tool runs the equivalent REST API call as you. Each tool's own description ends with the route it maps to — for example `create_booking` reports `[POST /booking/]` — so you can always trace a tool back to the [API reference](/docs/api-reference/introduction).
</Info>

## Bookings

| Tool                                          | What it does                                                                       |
| --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `get_booking`                                 | List your bookings, with filters for status, attendee, event type, and date ranges |
| `get_booking_by_id`                           | Get a single booking by ID                                                         |
| `create_booking`                              | Create a booking — see [Booking through MCP](#booking-through-mcp) first           |
| `cancel_booking`                              | Cancel a booking, with options for cancellation scope, seated events, and refunds  |
| `reschedule_booking`                          | Move a booking to a new time                                                       |
| `change_booking_confirmation_status`          | Accept or decline a booking that requires confirmation                             |
| `update_booking_reassignbookingautomatically` | Reassign a round-robin booking to the next available host                          |
| `update_booking_reassignbookingtouser`        | Reassign a round-robin booking to a specific host                                  |

<Note>
  Despite the singular name, `get_booking` **lists** bookings. Use `get_booking_by_id` for one specific booking. This mirrors the REST API, where the collection lives at `/booking/`.
</Note>

## Slots

| Tool                   | What it does                                         |
| ---------------------- | ---------------------------------------------------- |
| `get_slots`            | Get bookable times for an event type or set of users |
| `create_slots_reserve` | Hold a slot temporarily so nobody else takes it      |
| `get_slot`             | Look up a reserved slot by UID                       |
| `update_slots`         | Update a reserved slot                               |
| `delete_slots`         | Release a reserved slot                              |

## Event types

| Tool                    | What it does                      |
| ----------------------- | --------------------------------- |
| `get_event_types`       | List your event types (paginated) |
| `get_event_types_by_id` | Get one event type by ID          |
| `create_eventtype`      | Create an event type              |
| `update_eventtype`      | Update an event type              |
| `delete_eventtype`      | Delete an event type              |

## Availability and schedules

A **schedule** is a named set of working hours. An **availability** is a rule inside one.

| Tool                  | What it does                   |
| --------------------- | ------------------------------ |
| `get_schedule`        | List your schedules            |
| `create_schedule`     | Create a schedule              |
| `update_schedule`     | Update a schedule              |
| `delete_schedule`     | Delete a schedule              |
| `get_availability`    | Get your current availability  |
| `create_availability` | Add availability to a schedule |
| `update_availability` | Update an availability rule    |
| `delete_availability` | Delete an availability rule    |

## Contacts

| Tool                   | What it does                                          |
| ---------------------- | ----------------------------------------------------- |
| `list_contacts`        | List and search contacts, with sorting and pagination |
| `get_contact`          | Get a contact by ID                                   |
| `create_contact`       | Create a contact                                      |
| `update_contact`       | Update a contact                                      |
| `delete_contact`       | Delete a contact                                      |
| `get_contact_meetings` | Get a contact's meeting history                       |

## Teams

| Tool                  | What it does                     |
| --------------------- | -------------------------------- |
| `get_teams`           | List your teams (paginated)      |
| `get_team`            | Get a team by ID                 |
| `create_team`         | Create a team                    |
| `update_team_details` | Update a team's details          |
| `delete_team`         | Delete a team                    |
| `get_team_schedules`  | Get every team member's schedule |

<Warning>
  **Team slugs are globally unique across all of Cal ID**, not just your account. `create_team` can fail with a conflict even when you have no teams at all — the slug is simply taken by someone else. Pick a more specific slug and retry.
</Warning>

### Team event types

| Tool                    | What it does                                                   |
| ----------------------- | -------------------------------------------------------------- |
| `get_team_event_types`  | List a team's event types                                      |
| `get_team_event_type`   | Get one team event type                                        |
| `create_team_eventtype` | Create a team event type (collective, round-robin, or managed) |
| `update_team_eventtype` | Update a team event type                                       |
| `delete_team_eventtype` | Delete a team event type                                       |

### Team members

| Tool                     | What it does                         |
| ------------------------ | ------------------------------------ |
| `get_team_memberships`   | List a team's members                |
| `get_team_membership`    | Get one membership                   |
| `add_team_member`        | Add a member to a team               |
| `update_team_membership` | Update a member's role or membership |
| `remove_team_member`     | Remove a member from a team          |

## Webhooks

MCP can **manage** webhook subscriptions. It cannot receive deliveries — those go to your own server. See [Build a webhook receiver](/docs/developers/guides/webhook-receiver).

| Tool                | What it does                  |
| ------------------- | ----------------------------- |
| `get_webhook`       | List your webhooks            |
| `get_webhook_by_id` | Get one webhook by ID         |
| `create_webhook`    | Create a webhook subscription |
| `update_webhook`    | Update a webhook              |
| `delete_webhook`    | Delete a webhook              |

## Profile

| Tool                               | What it does                                |
| ---------------------------------- | ------------------------------------------- |
| `get_users_me`                     | Get your own profile                        |
| `get_users`                        | Get a user's public event types by username |
| `update_user_profile`              | Update your profile                         |
| `create_users_edit_profile_avatar` | Upload a profile picture                    |

## Diagnostics

| Tool                        | What it does                          |
| --------------------------- | ------------------------------------- |
| `get_diagnostics_client_ip` | Returns the client IP the server sees |

<Note>
  `get_diagnostics_client_ip` is a temporary internal diagnostic. Don't build anything on it — it may be removed without notice.
</Note>

## Booking through MCP

This is the single most common failure, and it is not a bug.

<Warning>
  **You cannot work out bookable times yourself.** A time that looks perfectly valid — a weekday, inside your working hours, matching what your booking page shows — can still be rejected with `no_available_users_found_error`.

  Always call `get_slots` first, then book a time it actually returned.
</Warning>

The correct sequence:

<Steps>
  <Step title="Find the event type">
    Use `get_event_types` and note the `id` of the event you want.
  </Step>

  <Step title="Ask for real slots">
    Call `get_slots` with that event type ID and a date range. It returns only genuinely bookable times.

    Pass the ID as a **string** here — `"106371"`, not `106371`.
  </Step>

  <Step title="Book one of them">
    Pass a time `get_slots` returned into `create_booking` as `start`. Don't round it, adjust it, or compute your own.

    Two shape changes catch people between these steps: `create_booking` wants the same `eventTypeId` back as a **number**, and all of its arguments go inside a `body` object.

    ```json theme={null}
    {
      "body": {
        "eventTypeId": 106371,
        "start": "2026-08-31T03:45:00.000Z",
        "end": "2026-08-31T04:15:00.000Z",
        "responses": { "name": "Ada Lovelace", "email": "ada@example.com" }
      }
    }
    ```
  </Step>
</Steps>

The response nests times two levels deeper than you might expect. `content[1]` holds the usual `success`/`data` envelope, and the times sit under `data.slots`, grouped by date:

```json theme={null}
{
  "success": true,
  "data": {
    "slots": {
      "2026-08-31": [
        { "time": "2026-08-31T03:45:00.000Z" },
        { "time": "2026-08-31T04:00:00.000Z" }
      ],
      "2026-09-01": [
        { "time": "2026-09-01T03:45:00.000Z" }
      ]
    }
  }
}
```

The full path to a bookable time is therefore `content[1].data.slots["2026-08-31"][0].time`. Reading the date keys from the wrong level — straight off `content[1]`, or off a `slots` key at the top — makes a healthy response look like "no availability."

<Info>
  The first offered day is often later than you'd assume — minimum booking notice, buffers, and calendar conflicts all push it out. Treat whatever `get_slots` returns as the truth.
</Info>

## Input gotchas

Worth knowing if you call tools directly rather than prompting conversationally.

<AccordionGroup>
  <Accordion title="Write tools nest everything under a body object">
    Every tool that sends data — all 25 that create, update, cancel, or reschedule something — takes its fields inside a `body` object rather than at the top level. (Delete tools send no data, so they have no `body`.) This is the most common shape error, and the message it produces doesn't name the field you forgot:

    ```
    path: ["body"], "Required"
    ```

    `create_booking` puts everything in `body`:

    ```json theme={null}
    {
      "body": {
        "eventTypeId": 106371,
        "start": "2026-08-31T03:45:00.000Z",
        "end": "2026-08-31T04:15:00.000Z",
        "responses": { "name": "Ada Lovelace", "email": "ada@example.com" }
      }
    }
    ```

    Tools that act on an existing record keep the **identifier outside** `body` and the changes inside it. `cancel_booking`:

    ```json theme={null}
    {
      "id": 4820193,
      "body": { "cancellationReason": "Rescheduling to next week" }
    }
    ```

    Read-only tools take their parameters flat — `get_slots` has no `body`.
  </Accordion>

  <Accordion title="eventTypeId is a string for slots and a number for booking">
    The same ID changes type between the two halves of the booking flow, so the value that just worked fails on the next call.

    | Tool             | Type       | Example    |
    | ---------------- | ---------- | ---------- |
    | `get_slots`      | **String** | `"106371"` |
    | `create_booking` | **Number** | `106371`   |

    Passing a number to `get_slots` returns `Expected string, received number`. Passing a string to `create_booking` returns `Expected number, received string`. Neither message tells you which direction to convert, so check the table.

    `get_event_types` returns `id` as a **number**, which is the form `create_booking` wants and `get_slots` doesn't.

    These tools also want `eventTypeId` as a **number**: `create_slots_reserve`, `update_slots`, `get_availability`, `get_team_event_type`, `update_team_eventtype`, and `delete_team_eventtype`. `get_slots` is the outlier.
  </Accordion>

  <Accordion title="Date parameters are named inconsistently">
    `get_slots` takes `start` and `end`. So does `create_booking`, inside its `body`. `reschedule_booking` takes only `start`.

    `startTime` and `endTime` are a different concept entirely — they are the clock times on an availability rule, used by `create_availability` and `update_availability`. **No booking tool uses them.** Sending `startTime` to `create_booking` fails as a missing `start`.
  </Accordion>

  <Accordion title="Responses contain two text blocks, not one">
    Every tool result returns a status line first, then the JSON payload:

    ```
    content[0] → "HTTP 200 GET /event-types/"
    content[1] → { "success": true, "data": [ ... ] }
    ```

    Parsing `content[0]` as JSON gets you the status line and fails. Read `content[1]`.
  </Accordion>

  <Accordion title="Write tools have no undo">
    35 of the 58 tools write, and `delete_eventtype`, `delete_team`, and `cancel_booking` take effect immediately. Keep tool-approval prompts enabled in your client so these need a confirmation, or filter them out at the bridge with `--ignore-tool` — see [How access and permissions work](/docs/mcp/overview#how-access-and-permissions-work).
  </Accordion>
</AccordionGroup>

## MCP setup and API details

<CardGroup cols={2}>
  <Card title="Connect a client" icon="link" href="/docs/mcp/connect">
    Setup for Claude, Cursor, ChatGPT, and other MCP clients.
  </Card>

  <Card title="MCP overview" icon="plug" href="/docs/mcp/overview">
    What MCP covers, and how permissions work.
  </Card>

  <Card title="Create a booking" icon="calendar-plus" href="/docs/developers/guides/create-a-booking">
    The same slots-then-book flow using the REST API directly.
  </Card>

  <Card title="API reference" icon="code" href="/docs/api-reference/introduction">
    Full reference for every endpoint behind these tools.
  </Card>
</CardGroup>


## Related topics

- [Cal ID MCP Server](/docs/mcp/overview.md)
- [Connect Your AI Assistant to Cal ID](/docs/mcp/connect.md)
- [Cal ID Scheduling API Reference](/docs/api-reference/introduction.md)
- [Book a Meeting with the Cal ID API](/docs/developers/guides/create-a-booking.md)