@setluca/mcp 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -10,6 +10,35 @@ input schema, or changing what a tool does to a workspace.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-22
+
+### Fixed
+
+- Tool annotations now match what each tool does, as the October 2026 audit
+  for the OpenAI app directory listed them. All 203 tools it covered match its
+  corrected values, and the 21 tools added in 0.5.0 follow the same rules.
+  - `idempotentHint` is true for 33 writes that a repeat with the same input
+    cannot move further, such as `luca_leads_notes_delete`,
+    `luca_insights_dismiss`, `luca_broadcasts_cancel`, and
+    `luca_pause_cadence`. It was true only for reads before.
+  - `openWorldHint` is true for writes the coach's webhook subscribers hear
+    about (`luca_leads_create`, `luca_leads_update`,
+    `luca_leads_identities_attach`, `luca_review_queue_reject`,
+    `luca_review_queue_bulk_reject`, `luca_broadcasts_pause`) and for the call
+    summaries that later reach the CRM (`luca_call_events_summary_generate`,
+    `luca_call_events_backfill`). None of them needs `confirm: true`.
+  - `luca_leads_import_preview` is read-only. It saves nothing.
+  - `luca_integrations_crm_connections_schema` is no longer read-only, because
+    it refreshes Luca's cached copy of the CRM schema.
+  - `luca_review_queue_objection_variant` is no longer destructive. It adds a
+    learning event and leaves the draft as it was.
+- `luca_integrations_crm_sync_runs_create` is titled "Preview a CRM sync" and
+  no longer asks for `confirm: true` or claims to reach the CRM. The API
+  refuses a live sync, so the tool only records a dry-run preview.
+- `luca_reschedule_call` says that a Cal.com or Google Calendar move waits for
+  the provider: until it confirms, the booking reads `pending_provider` and
+  keeps its old time.
+
 ## [0.5.0] - 2026-10-22
 
 ### Breaking

package/dist/annotations.js

@@ -10,6 +10,7 @@ export function operationAnnotationSource(operation) {
         title: operation.title,
         readOnly: operation.readOnly,
         mutatesExisting: operation.mutatesExisting,
+        idempotent: operation.idempotent,
         ...optionalField("confirm", operation.confirm),
         openWorld: operation.openWorld,
     };
@@ -34,11 +35,11 @@ export function toolAnnotations(source) {
         // existed before the call.
         destructiveHint: !source.readOnly &&
             (source.confirm !== undefined || source.mutatesExisting),
-        // The idempotency key is optional in the MCP input. The HTTP layer mints a
-        // new key when it is absent, so two otherwise identical writes can still
-        // have different effects. Only advertise the unconditional read guarantee
-        // until the key becomes a required tool argument.
-        idempotentHint: source.readOnly,
+        // Stated per operation: every read, plus the writes a repeat cannot move
+        // further, such as a delete, a dismiss, or a whole-value replace. It never
+        // leans on the idempotency key, which the HTTP layer mints fresh when the
+        // caller leaves it out.
+        idempotentHint: source.idempotent,
         // Every call goes to the Luca API, but most only touch the coach's own
         // workspace. The hint is true only when the call can reach past it: a
         // lead's inbox, an outside URL, or a connected calendar or CRM.

package/dist/operations/groups/bookings.js

@@ -169,6 +169,7 @@ export const bookingsOperations = [
     op({
         id: "bookings.guestLinks.revoke",
         title: "Revoke a booking's guest links",
+        idempotent: true,
         mutatesExisting: true,
         description: "Kill every outstanding guest link on a booking at once.",
     }),
@@ -197,11 +198,13 @@ export const bookingsOperations = [
     op({
         id: "bookings.types.delete",
         title: "Delete a booking type",
+        idempotent: true,
         description: "Remove a booking type and get back the types that are left. Calls already booked against it are not cancelled.",
     }),
     op({
         id: "bookings.types.schedule.replace",
         title: "Replace a booking type schedule",
+        idempotent: true,
         mutatesExisting: true,
         description: "Replace a booking type's schedule outright. Send every rule and override you want to keep \u2014 anything left out is dropped, which is also how you clear a day. Read the current schedule first unless you mean to start over.",
     }),
@@ -213,12 +216,14 @@ export const bookingsOperations = [
     op({
         id: "bookings.types.attendees.remove",
         title: "Remove a booking type attendee",
+        idempotent: true,
         mutatesExisting: true,
         description: "Remove a standing attendee from one booking type and get back the ones that are left. Calls already booked keep the invitees they were created with.",
     }),
     op({
         id: "bookings.calendars.select",
         title: "Select a booking calendar",
+        idempotent: true,
         mutatesExisting: true,
         // Selection checks that the calendar exists in the connected Google account.
         openWorld: true,
@@ -227,6 +232,7 @@ export const bookingsOperations = [
     op({
         id: "bookings.calendars.remove",
         title: "Remove a booking calendar",
+        idempotent: true,
         mutatesExisting: true,
         description: "Stop using a calendar for conflict checks or as the booking destination. The calendar itself is left alone in Google; only Luca's selection changes.",
     }),
@@ -238,6 +244,7 @@ export const bookingsOperations = [
     op({
         id: "bookings.recovery.stop",
         title: "Stop a no-show recovery",
+        idempotent: true,
         mutatesExisting: true,
         description: "Stop a booking's no-show recovery so no further follow-up is scheduled. A follow-up already being sent may still arrive. Send recovery.id as recoveryCaseId and recovery.outcomeVersion from luca_bookings_recovery_get; a recovery that changed since that read returns 409 booking_recovery_changed.",
     }),

package/dist/operations/groups/broadcasts.js

@@ -51,6 +51,9 @@ export const broadcastsOperations = [
     op({
         id: "broadcasts.pause",
         title: "Pause a broadcast",
+        idempotent: true,
+        // Sends broadcast.paused to the coach's webhook subscribers.
+        openWorld: true,
         mutatesExisting: true,
         // Recipient snapshot, see the note above this list.
         untrustedContent: true,
@@ -69,6 +72,7 @@ export const broadcastsOperations = [
     op({
         id: "broadcasts.cancel",
         title: "Cancel a broadcast",
+        idempotent: true,
         mutatesExisting: true,
         // Recipient snapshot, see the note above this list.
         untrustedContent: true,

package/dist/operations/groups/cadences.js

@@ -10,6 +10,7 @@ export const cadencesOperations = [
     op({
         id: "cadences.pause",
         title: "Pause a lead's cadence",
+        idempotent: true,
         mutatesExisting: true,
         description: "Pause (cancel) a lead's running rescue cadence with an optional reason.",
     }),

package/dist/operations/groups/callEvents.js

@@ -45,6 +45,8 @@ export const callEventsOperations = [
     op({
         id: "callEvents.summary.generate",
         title: "Generate a call summary",
+        // The summary is pushed to the coach's connected CRM after its review window.
+        openWorld: true,
         mutatesExisting: true,
         untrustedContent: true,
         description: "Queue a fresh summary and return straight away. Poll the call event for the result.",
@@ -75,6 +77,7 @@ export const callEventsOperations = [
     op({
         id: "callEvents.undoOutcome",
         title: "Undo a call's outcome",
+        idempotent: true,
         mutatesExisting: true,
         untrustedContent: true,
         description: "Clear a mistaken attendance mark and put the call back in the queue. The window is 48 hours from when the outcome was set.",
@@ -82,6 +85,9 @@ export const callEventsOperations = [
     op({
         id: "callEvents.backfill",
         title: "Backfill a booking's call event",
+        idempotent: true,
+        // The summary it queues later syncs to the coach's connected CRM.
+        openWorld: true,
         untrustedContent: true,
         description: "Create a call event for a booking that predates automatic creation, then queue its summary. Safe to call twice: an existing call event comes back as is.",
     }),

package/dist/operations/groups/conversations.js

@@ -53,6 +53,7 @@ export const conversationsOperations = [
     }),
     op({
         id: "conversations.reply_failure_dismiss",
+        idempotent: true,
         // Answers with a flag only; no lead-authored text.
         untrustedContent: false,
         title: "Dismiss a failed reply",

package/dist/operations/groups/insights.js

@@ -8,18 +8,21 @@ export const insightsOperations = [
     op({
         id: "insights.markRead",
         title: "Mark an insight read",
+        idempotent: true,
         mutatesExisting: true,
         description: "Mark one insight read, so it stops coming back at the top of the feed.",
     }),
     op({
         id: "insights.dismiss",
         title: "Dismiss an insight",
+        idempotent: true,
         mutatesExisting: true,
         description: "Dismiss one insight the coach does not want to act on. Use this rather than leaving it unread forever.",
     }),
     op({
         id: "insights.markActioned",
         title: "Mark an insight actioned",
+        idempotent: true,
         mutatesExisting: true,
         description: "Record that the thing an insight asked for was actually done. Use it after doing the work, not instead of it.",
     }),
@@ -31,6 +34,7 @@ export const insightsOperations = [
     op({
         id: "insights.settings.update",
         title: "Update alert delivery settings",
+        idempotent: true,
         mutatesExisting: true,
         description: "Merge-patch the coach's alert-delivery settings. Send only what you are changing; anything left out keeps its current value.",
     }),

package/dist/operations/groups/integrations.js

@@ -20,12 +20,16 @@ export const integrationsOperations = [
     op({
         id: "integrations.crm.connections.create",
         title: "Create a CRM connection",
+        idempotent: true,
         mutatesExisting: true,
         description: "Create or update a workspace-scoped CRM connection.",
     }),
     op({
         id: "integrations.crm.connections.schema",
         title: "Read a CRM's field schema",
+        // Refreshes Luca's cached copy of the CRM schema, the same copy every time.
+        readOnly: false,
+        idempotent: true,
         openWorld: true,
         // sampleRecords are literal contact and deal rows from the coach's CRM, which leads and other people filled in.
         untrustedContent: true,
@@ -48,11 +52,13 @@ export const integrationsOperations = [
     op({
         id: "integrations.crm.mappings.suggest",
         title: "Suggest CRM field mappings",
+        idempotent: true,
         description: "Suggest CRM field mappings.",
     }),
     op({
         id: "integrations.crm.mappings.confirm",
         title: "Confirm CRM field mappings",
+        idempotent: true,
         mutatesExisting: true,
         description: "Confirm CRM field mappings.",
     }),
@@ -65,12 +71,10 @@ export const integrationsOperations = [
     }),
     op({
         id: "integrations.crm.syncRuns.create",
-        title: "Start a CRM sync",
-        openWorld: true,
-        confirm: "always",
+        title: "Preview a CRM sync",
         // Mutations carry CRM record values: names, emails, notes.
         untrustedContent: true,
-        description: "Create a CRM dry-run or live sync run.",
+        description: "Record a dry-run preview of the changes a CRM sync would make, as a new sync run. Nothing is written to the CRM: the API refuses a live sync.",
     }),
     op({
         id: "integrations.events.list",
@@ -82,6 +86,7 @@ export const integrationsOperations = [
     op({
         id: "integrations.crm.connections.disconnect",
         title: "Disconnect a CRM",
+        idempotent: true,
         mutatesExisting: true,
         // Stops every sync with that CRM until the coach signs in to it again.
         confirm: "always",

package/dist/operations/groups/knowledge.js

@@ -15,6 +15,7 @@ export const knowledgeOperations = [
     op({
         id: "knowledge.rejectSuggestion",
         title: "Reject a knowledge suggestion",
+        idempotent: true,
         mutatesExisting: true,
         description: "Reject a profile suggestion so it stops being offered. The profile is left as it stands.",
     }),
@@ -33,6 +34,7 @@ export const knowledgeOperations = [
     op({
         id: "knowledge.sources.disconnect",
         title: "Disconnect a knowledge source",
+        idempotent: true,
         mutatesExisting: true,
         description: "Delete a knowledge source. Its pending suggestions go with it; values the coach already approved stay in the profile, because approving copies them there.",
     }),

package/dist/operations/groups/leads.js

@@ -18,12 +18,17 @@ export const leadsOperations = [
     op({
         id: "leads.create",
         title: "Create or upsert a lead",
+        // Sends lead.created to the coach's webhook subscribers.
+        openWorld: true,
         mutatesExisting: true,
         description: "Create or upsert a lead identity. Body requires channel and externalUserId.",
     }),
     op({
         id: "leads.update",
         title: "Update a lead",
+        // Sends lead.updated to the coach's webhook subscribers, and a tag change
+        // can resume a campaign step that messages the lead.
+        openWorld: true,
         description: "Update a lead's display name, stage, score, tags, or custom fields.",
     }),
     op({
@@ -33,6 +38,7 @@ export const leadsOperations = [
     }),
     op({
         id: "leads.fieldDefinitions.upsert",
+        idempotent: true,
         // Echoes the coach's own field definition back.
         untrustedContent: false,
         title: "Define a custom lead field",
@@ -42,6 +48,8 @@ export const leadsOperations = [
     op({
         id: "leads.importPreview",
         title: "Preview a lead import",
+        // A POST only so the CSV fits in a body. It checks the mapping and saves nothing.
+        readOnly: true,
         description: "Preview a mapped CSV lead import before applying it.",
     }),
     op({
@@ -55,6 +63,8 @@ export const leadsOperations = [
     op({
         id: "leads.identities.attach",
         title: "Attach a channel identity to a lead",
+        // Sends lead.updated to the coach's webhook subscribers.
+        openWorld: true,
         mutatesExisting: true,
         description: "Attach a verified or claimed identity to a lead.",
     }),
@@ -71,6 +81,7 @@ export const leadsOperations = [
     }),
     op({
         id: "leads.consents.revoke",
+        idempotent: true,
         // Echoes the consent record the coach revoked.
         untrustedContent: false,
         title: "Revoke a lead's consent",
@@ -92,6 +103,7 @@ export const leadsOperations = [
     }),
     op({
         id: "leads.notes.delete",
+        idempotent: true,
         // Answers with ids and status flags only; no lead-authored text.
         untrustedContent: false,
         title: "Delete a lead note",

package/dist/operations/groups/learning.js

@@ -27,6 +27,7 @@ export const learningOperations = [
     }),
     op({
         id: "learning.proposals.dismiss",
+        idempotent: true,
         // Answers with ids and status flags only; no lead-authored text.
         untrustedContent: false,
         title: "Dismiss a learning proposal",

package/dist/operations/groups/memory.js

@@ -16,6 +16,7 @@ export const memoryOperations = [
     }),
     op({
         id: "memory.setArchived",
+        idempotent: true,
         // Answers with ids and status flags only; no lead-authored text.
         untrustedContent: false,
         title: "Archive or restore memories",

package/dist/operations/groups/reviewQueue.js

@@ -22,6 +22,8 @@ export const reviewQueueOperations = [
     }),
     op({
         id: "reviewQueue.reject",
+        // Sends review.rejected to the coach's webhook subscribers.
+        openWorld: true,
         // Answers with ids and status flags only; no lead-authored text.
         untrustedContent: false,
         title: "Reject a queued draft",
@@ -54,7 +56,6 @@ export const reviewQueueOperations = [
         // Answers with ids and status flags only; no lead-authored text.
         untrustedContent: false,
         title: "Record an objection variant choice",
-        mutatesExisting: true,
         description: "Record which objection-specialist variant was picked for one queued draft. It is how the objection tests learn which handling works, so record the variant the coach actually chose.",
     }),
     op({
@@ -76,6 +77,7 @@ export const reviewQueueOperations = [
     }),
     op({
         id: "reviewQueue.drafting.cancel",
+        idempotent: true,
         // Answers with a turn id and state only; no lead-authored text.
         untrustedContent: false,
         title: "Cancel a draft in progress",
@@ -95,6 +97,7 @@ export const reviewQueueOperations = [
     }),
     op({
         id: "reviewQueue.drafting.dismiss",
+        idempotent: true,
         // Answers with no body.
         untrustedContent: false,
         title: "Dismiss a stopped draft",
@@ -124,6 +127,9 @@ export const reviewQueueOperations = [
     }),
     op({
         id: "reviewQueue.bulkReject",
+        idempotent: true,
+        // Sends review.rejected for each draft to the coach's webhook subscribers.
+        openWorld: true,
         // Answers with one outcome per id; no lead-authored text.
         untrustedContent: false,
         title: "Reject several drafts",

package/dist/operations/groups/webhooks.js

@@ -29,6 +29,7 @@ export const webhooksOperations = [
     op({
         id: "webhooks.subscriptions.delete",
         title: "Delete a webhook subscription",
+        idempotent: true,
         // Deleting by id is naturally idempotent (the route matches its policy
         // entry, which carries no requireIdempotency), so no Idempotency-Key is
         // sent and it stays out of the confirm-gated tier that re-triggers live

package/dist/operations/registry.js

@@ -286,6 +286,7 @@ export function op(input) {
     const pageContract = pageContractFor(method, path);
     const group = operationGroupForId(input.id);
     const untrustedContent = input.untrustedContent ?? HashSet.has(UNTRUSTED_CONTENT_GROUPS, group);
+    const readOnly = input.readOnly ?? method === "GET";
     const operation = {
         id: input.id,
         group,
@@ -295,7 +296,8 @@ export function op(input) {
         path,
         scopes,
         mutatesExisting: mutatesExistingRoute,
-        readOnly: input.readOnly ?? method === "GET",
+        readOnly,
+        idempotent: input.idempotent ?? readOnly,
         idempotencyRequired,
         ...optionalField("confirm", input.confirm),
         openWorld: input.openWorld ?? false,

package/dist/task-tools/bookings.js

@@ -239,7 +239,7 @@ const DEFAULT_GUEST_LINK_HOURS = 168;
 const rescheduleCall = taskTool({
     name: "luca_reschedule_call",
     title: "Move a call to a new time",
-    description: 'Move a booked call to a new time and hand back a fresh reschedule link for the lead. Checks the new slot is open first, against the schedule of its booking type when it has one, and returns the open slots instead of moving the call when it is taken. A call with an idempotencyKey skips that check so a retry gets the original result back. A manual booking moves in Luca only. A Cal.com or Google Calendar booking moves on that calendar too. A Calendly, GoHighLevel or iClosed booking is refused so the coach can move it with the provider, and so is a provider booking with no calendar event, such as one recorded with luca_bookings_create. Moving the call re-arms the lead\'s reminder for the new time, so pass confirm: true only after the coach approves the move. Example: call with { bookingId, slotAt: "2026-07-16T15:00:00Z", confirm: true } after the lead asked to push the call. No message about the move is sent: send the lead the link yourself, or draft the message through the review queue.',
+    description: "Move a booked call to a new time and hand back a fresh reschedule link for the lead. Checks the new slot is open first, against the schedule of its booking type when it has one, and returns the open slots instead of moving the call when it is taken. A call with an idempotencyKey skips that check so a retry gets the original result back. A manual booking moves in Luca only. A Cal.com or Google Calendar booking moves on that calendar too, but only once the provider confirms: until then the booking's operation.state reads pending_provider and it keeps its old time, so read the booking again before telling the coach the call moved. A Calendly, GoHighLevel or iClosed booking is refused so the coach can move it with the provider, and so is a provider booking with no calendar event, such as one recorded with luca_bookings_create. Moving the call re-arms the lead's reminder for the new time, so pass confirm: true only after the coach approves the move. Example: call with { bookingId, slotAt: \"2026-07-16T15:00:00Z\", confirm: true } after the lead asked to push the call. No message about the move is sent: send the lead the link yourself, or draft the message through the review queue.",
     inputSchema: {
         ...WORKSPACE_INPUT_FIELDS,
         bookingId: NonEmptyString.annotate({ description: "The booking to move." }),

package/dist/tool.js

@@ -95,6 +95,9 @@ function buildFromTaskTool(tool) {
         // A task tool overwrites or removes existing state when any write it
         // composes does.
         mutatesExisting: composed.some((operation) => operation.mutatesExisting),
+        // Repeating a task tool has no further effect only when that holds for
+        // every operation it composes.
+        idempotent: composed.every((operation) => operation.idempotent),
         ...optionalField("confirm", confirm),
         untrustedContent,
         // A task tool reaches as far as the furthest operation it composes.

package/dist/version.js

@@ -9,6 +9,6 @@
  *
  * Bump this in the same commit as package.json and server.json.
  */
-export const LUCA_MCP_VERSION = "0.5.0";
+export const LUCA_MCP_VERSION = "0.5.1";
 /** The user-agent every outbound Luca API call identifies itself with. */
 export const LUCA_MCP_USER_AGENT = `luca-mcp/${LUCA_MCP_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@setluca/mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "private": false,
   "description": "Connect SetLuca to Claude, ChatGPT, Cursor, or any MCP client to triage the review queue, look up leads, draft replies, and check campaigns.",
   "keywords": [