SetLuca

Official

by setluca

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Book a call with a lead

luca_book_call

Destructive

Book an open call slot on the coach's calendar, invite the lead by email, and queue a confirmation draft for the coach to review.

Instructions

Book a call on the coach's calendar provider and have the provider invite the lead's email; Luca can also queue a booking confirmation draft for the coach to review. Works for call types on Calendly, Cal.com, or Google Calendar. Reads the open slots of the call type first and books the one that starts at slotAt. When that slot is taken it books nothing and returns the open slots instead, so pick one of them and call again. The answer is usually pending while the provider confirms; check it with luca_bookings_provider_requests_get. The booking puts an event on the coach's calendar and invites the lead, so pass confirm: true only after the coach approves this exact slot. If a retry answers slot_not_available, the first attempt may have taken the slot, so check luca_bookings_list before booking again. To record a call that is already on a calendar, use luca_bookings_create instead. Example: call with { leadId, bookingTypeId, slotAt: "2026-07-14T15:00:00Z", inviteeEmail: "sam@example.com", confirm: true } after the lead agreed to a time.

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": {
      "leadId": "<leadId>",
      "bookingTypeId": "<bookingTypeId>",
      "slotAt": "<slotAt>",
      "inviteeEmail": "<inviteeEmail>"
    },
    "name": "luca_book_call"
  }
}

Input Schema

Name	Required	Description
`leadId`	Yes	The lead to book.
`slotAt`	Yes	ISO-8601 start time for the call, with an offset. It must be an open slot of the call type, as luca_bookings_managed_availability lists them.
`confirm`	No	This tool has a real-world side effect: it messages real leads, books, moves, or cancels a call, changes a lead's consent, imports leads, writes to a connected calendar or CRM, sends workspace events to an outside URL, or re-triggers downstream automations. Pass confirm: true to proceed; the call is rejected without it.
`timezone`	No	IANA time zone the booking is shown in, such as Europe/Madrid. Defaults to UTC.
`inviteeName`	No	The lead's name as the invite should show it.
`workspaceId`	No	Optional Luca workspace id override.
`inviteeEmail`	Yes	The lead's email. The provider sends the invite there.
`bookingTypeId`	Yes	The call type to book, from luca_bookings_types_list. Its provider is the calendar the call lands on.
`workspaceSlug`	No	Optional Luca workspace slug override.
`idempotencyKey`	No	Reuse the same key when retrying this exact booking, so a repeat of a request that already reached the API cannot book the call twice.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.4.1Oct 28, 2026

changedInput schema / properties / bookingTypeId / description

Previous value: -"The booking type to book under, from luca_bookings_types_list. Required when provider is google_calendar, and it must be an active google_calendar type."New value: +"The call type to book, from luca_bookings_types_list. Its provider is the calendar the call lands on."

changedInput schema / properties / idempotencyKey / description

Previous value: -"Reuse the same key when retrying this exact booking. A keyed call skips the availability check and lets the API replay the first result."New value: +"Reuse the same key when retrying this exact booking, so a repeat of a request that already reached the API cannot book the call twice."

addedInput schema / properties / inviteeEmail

Added value: +{
+  "description": "The lead's email. The provider sends the invite there.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / inviteeName

Added value: +{
+  "description": "The lead's name as the invite should show it.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}

removedInput schema / properties / provider

Removed value: -{
-  "description": "The coach's booking provider. Sent with the booking and used for the availability check. Pass it when the coach is not on Calendly, or the availability check reads the wrong calendar. Left off, the check reads Calendly and the API records the booking as manual.",
-  "enum": [
-    "manual",
-    "calendly",
-    "cal_com",
-    "google_calendar",
-    "iclosed",
-    "gohighlevel"
-  ],
-  "type": "string"
-}

changedInput schema / properties / slotAt / description

Previous value: -"ISO-8601 start time for the call, with an offset."New value: +"ISO-8601 start time for the call, with an offset. It must be an open slot of the call type, as luca_bookings_managed_availability lists them."

addedInput schema / properties / timezone

Added value: +{
+  "description": "IANA time zone the booking is shown in, such as Europe/Madrid. Defaults to UTC.",
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "leadId",
-  "slotAt"
-]New value: +[
+  "leadId",
+  "bookingTypeId",
+  "slotAt",
+  "inviteeEmail"
+]

removedOutput schema / properties / provenance

Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "note": {
-      "type": "string"
-    },
-    "untrusted": {
-      "enum": [
-        true
-      ],
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "untrusted",
-    "note"
-  ],
-  "type": "object"
-}

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "booked": {
-        "enum": [
-          false
-        ],
-        "type": "boolean"
-      },
-      "openSlots": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "reason": {
-        "enum": [
-          "slot_not_available"
-        ],
-        "type": "string"
-      },
-      "requestedSlotAt": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "booked",
-      "reason",
-      "requestedSlotAt",
-      "openSlots"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": true,
-    "properties": {
-      "booking": {
-        "additionalProperties": true,
-        "properties": {
-          "bookingTypeId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "calendlyEventId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "calendlyInviteeId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "cancellationReason": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "cancelledAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "coachId": {
-            "type": "string"
-          },
-          "createdAt": {
-            "type": "string"
-          },
-          "endAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "id": {
-            "type": "string"
-          },
-          "leadId": {
-            "type": "string"
-          },
-          "locationDetails": {
-            "type": "object"
-          },
-          "locationType": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "outcomeObservedAt": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "outcomeSource": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "provider": {
-            "type": "string"
-          },
-          "providerEventId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "providerInviteeId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "providerVersion": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "rawPayload": {
-            "type": "object"
-          },
-          "reconciliationState": {
-            "type": "string"
-          },
-          "rescheduledFromBookingId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "slotAt": {
-            "type": "string"
-          },
-          "status": {
-            "type": "string"
-          },
-          "timezone": {
-            "type": "string"
-          },
-          "updatedAt": {
-            "type": "string"
-          }
-        },
-        "type": "object"
-      },
-      "operation": {
-        "additionalProperties": true,
-        "properties": {
-          "providerSyncId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "state": {
-            "type": "string"
-          }
-        },
-        "type": "object"
-      }
-    },
-    "type": "object",
-    "x-luca-redacted-fields": [
-      "booking.rawPayload"
-    ]
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "booked": {
+        "enum": [
+          false
+        ],
+        "type": "boolean"
+      },
+      "openSlots": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "reason": {
+        "enum": [
+          "slot_not_available"
+        ],
+        "type": "string"
+      },
+      "requestedSlotAt": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "booked",
+      "reason",
+      "requestedSlotAt",
+      "openSlots"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": true,
+    "properties": {
+      "bookingId": {
+        "type": "string"
+      },
+      "displayText": {
+        "type": "string"
+      },
+      "finalStartsAt": {
+        "type": "string"
+      },
+      "id": {
+        "type": "string"
+      },
+      "managementUrl": {
+        "type": "string"
+      },
+      "meetingUrl": {
+        "type": "string"
+      },
+      "reason": {
+        "type": "string"
+      },
+      "state": {
+        "type": "string"
+      },
+      "timezone": {
+        "type": "string"
+      }
+    },
+    "type": "object"
+  }
+]

First observedv0.4.0Oct 21, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the destructive/openWorld annotations, it discloses the actual failure semantics: a taken slot books nothing and returns open slots, the result is usually pending provider confirmation, and a slot_not_available retry may mean the first attempt already booked. It also states the real-world effect (event on the coach's calendar, invite sent to the lead).

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?

Front-loaded with purpose, then slot behavior, then confirmation, retry, and alternative — a sensible reading order with no filler sentences. It runs long and the aside about queueing a confirmation draft lacks a corresponding parameter, so that clause is slightly orphaned.

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

Completeness5/5

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

For a 10-parameter, destructive, open-world booking tool with an output schema already covering return values, the description supplies the remaining essentials: approval gating, slot collision behavior, pending-state polling, and duplicate-booking avoidance on retry.

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 100%, so the schema baseline is 3, but the description adds interpretation: slotAt must be an open slot and drives what gets booked, confirm is an approval gate rather than a flag, and inviteeEmail is where the provider sends the invite. It does not extend meaning for timezone, workspaceId/workspaceSlug, or idempotencyKey, leaving those to the schema alone.

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 opening sentence states a specific verb and resource ("Book a call on the coach's calendar provider") plus the invite side effect, and the closing paragraph explicitly routes to luca_bookings_create for a different need. An agent can distinguish this from the sibling recording tool without reading either schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use (book an open slot of a call type), when-not (use luca_bookings_create to record an already-scheduled call), and a hard gating rule: pass confirm: true only after the coach approves this exact slot. It also names the follow-up tools for pending and retry states (luca_bookings_provider_requests_get, luca_bookings_list).

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

Deploy Server