rhombus-node-mcp 0.1.55 → 0.1.57

package/dist/tools-console/faces-tool.js

@@ -1,6 +1,8 @@
-import { getFaceEvents, getFaceEventsByPerson, getFaceMatchmakers, getPersonLabels, getRegisteredFaces, searchSimilarFaces } from "../api/faces-tool-api.js";
+import { isDeepStrictEqual } from "node:util";
+import { changePersonLabel, createPerson, deleteFaceMatchmaker, deletePerson, findPerson, getFaceEvents, getFaceEventsByPerson, getFaceMatchmakers, getPersonLabels, getRegisteredFaces, searchSimilarFaces, updatePerson, } from "../api/faces-tool-api.js";
 import { logger } from "../logger.js";
 import { OUTPUT_SCHEMA, RequestType, TOOL_ARGS, } from "../types/faces-tools-types.js";
+import { protectFields } from "../filtering-utils.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "faces-tool";
 /**
@@ -39,35 +41,90 @@ function resolveNamesToRegisteredFaces(userNames, registeredPeople) {
         };
     });
 }
+/**
+ * Roll a page of face events up into a distinct-person roster.
+ *
+ * Enumerating "who was seen" from a 200-event page is exactly the operation the
+ * response model does badly: the raw page is well over the chatbot's compaction
+ * threshold, so the model never sees it directly, and when it reads the compacted
+ * form it tends to answer from whatever chunk arrived last. Doing the dedupe here
+ * means the answer is a field lookup rather than a 200-row scan.
+ */
+function summarizeFaceEvents(faceEvents, morePagesAvailable) {
+    const byName = new Map();
+    let unnamedEvents = 0;
+    for (const event of faceEvents) {
+        const name = event.faceName?.trim();
+        if (!name) {
+            unnamedEvents++;
+            continue;
+        }
+        const ms = event.eventTimestampMs ?? 0;
+        const label = event.eventTimestamp ?? String(ms);
+        const existing = byName.get(name);
+        if (!existing) {
+            byName.set(name, { name, eventCount: 1, firstMs: ms, lastMs: ms, firstSeen: label, lastSeen: label });
+            continue;
+        }
+        existing.eventCount++;
+        if (ms < existing.firstMs) {
+            existing.firstMs = ms;
+            existing.firstSeen = label;
+        }
+        if (ms > existing.lastMs) {
+            existing.lastMs = ms;
+            existing.lastSeen = label;
+        }
+    }
+    const identifiedPeople = [...byName.values()]
+        // Most-seen first, then alphabetical so the ordering is stable across pages.
+        .sort((a, b) => b.eventCount - a.eventCount || a.name.localeCompare(b.name))
+        .map(({ name, eventCount, firstSeen, lastSeen }) => ({ name, eventCount, firstSeen, lastSeen }));
+    return {
+        totalEventsThisPage: faceEvents.length,
+        namedEvents: faceEvents.length - unnamedEvents,
+        unnamedEvents,
+        identifiedPeople,
+        morePagesAvailable,
+    };
+}
 const TOOL_DESCRIPTION = `
-This tool interacts with the Rhombus face recognition system to retrieve information about face sightings and registered faces.
-
-If the user is asking about how many people were seen (head count / occupancy), use the report-tool with GET_OCCUPANCY_ENABLED_CAMERAS and GET_OCCUPANCY_COUNT_REPORT instead. This tool (faces-tool) is best for identifying *who* was seen (unique individuals by name), and its face count data is also automatically included in report-tool people-counting responses via the faceCountEnrichment field.
+Rhombus **face recognition**: face sightings and registered faces. Use it to identify *who* was seen (unique individuals by name) — "who was in the office", "who was seen today" — to list the people registered in the org, or to work with person label groups (e.g. "Engineering", "Visitors").
 
-**Important for person-presence questions:** When asked whether specific people were seen or are present, you should ALSO call events-tool with eventType "access-control" to check badge-in records. Face recognition and access control are complementary — someone may badge in without face recognition triggering, or be seen by a camera without badging in.
+**Head counts are a different tool:** if the user asks how MANY people were seen (head count / occupancy), use report-tool with GET_OCCUPANCY_ENABLED_CAMERAS and GET_OCCUPANCY_COUNT_REPORT instead. Its people-counting responses already carry this tool's unique-face data in the faceCountEnrichment field.
 
-If the requestType is "get-face-events":
-- Use this tool to answer questions about face sightings, including questions like "who was in the office" or "who was seen today". Can be used for reporting, to generate a report on who was seen by the camera system.
-- **Automatic name resolution:** You can pass partial or first-name-only names in faceNames (e.g., "Brandon", "Omar"). The tool automatically looks up the registered faces directory and resolves them to exact names and person UUIDs before searching. Check the "resolvedNames" field in the response to see what each queried name was matched to (null means no match found).
-- You can filter face events using parameters like 'faceNames', 'hasEmbedding', 'hasName', 'labels', 'locationUuids', 'personUuids', and a time range using 'rangeStart' and 'rangeEnd' (timestamps in milliseconds).
-- If you'd like to know about all face events at a location, pass in a location UUID and no device UUIDs. This will correctly return all face events at that location.
-- When the user asks about a specific person at a location (e.g. "Jane Doe at Main Office"), call get-registered-faces first to get the list of registered names, find the best match, then call get-face-events with that precise name. The tool expects precise names as stored in the system.
-- When querying faces at a location, pass only the location UUID in searchFilter; do not pass device UUIDs in searchFilter.deviceUuids, so the API returns all faces detected at that location.
+**Important for person-presence questions:** when asked whether specific people were seen or are present, you should ALSO check badge-in records for the same time range — the vendor badge tools (onguard-events-tool / elements-events-tool / netbox-events-tool; call all three in parallel, each returns empty when not configured) and events-tool with eventType "access-control" (native Rhombus doors) or "brivo-access-control" (Brivo). Face recognition and access control are complementary: someone may badge in without face recognition triggering, or be seen by a camera without badging in.
 
-If the requestType is "get-registered-faces":
-- This tool retrieves a list of all people (registered faces) currently known to the Rhombus system for your organization. This list includes information about each registered person, including their assigned labels.
-- This returns ALL people registered in the system, regardless of the provided timestampFilter.
-- Each person in the response includes a "labels" array showing which label groups they belong to (e.g., "Engineering", "Visitors"). Use these labels to answer questions about groups of people.
-
-If the requestType is "get-person-labels":
-- This retrieves a mapping of all person UUIDs to their assigned labels across the organization.
-- Use this to discover what label groups exist and which registered faces belong to each group.
-- Useful when the user asks about a group (e.g., "was anyone from Engineering seen today?") — get the labels first, find the person UUIDs for that label, then query face events filtered by those personUuids or labels.
+Per-requestType behaviour — automatic name resolution, the available filters, and how to query a whole location — is documented on the requestType parameter.
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
     if (args.requestType === RequestType.GET_FACE_EVENTS) {
-        const faceEventArgs = args.faceEventFilter;
+        // Accept the misplaced top-level filter seen in production without ever
+        // dropping its person/location/time constraints or silently broadening a query.
+        const nestedFilter = args.faceEventFilter?.searchFilter;
+        if (nestedFilter && args.searchFilter && !isDeepStrictEqual(nestedFilter, args.searchFilter)) {
+            return {
+                isError: true,
+                ...createToolStructuredContent({
+                    requestType: args.requestType,
+                    error: "Conflicting searchFilter and faceEventFilter.searchFilter. No search was performed. Retry once with the intended filter inside faceEventFilter.searchFilter only.",
+                }),
+            };
+        }
+        if (nestedFilter === undefined && args.searchFilter == null) {
+            return {
+                isError: true,
+                ...createToolStructuredContent({
+                    requestType: args.requestType,
+                    error: "get-face-events requires faceEventFilter.searchFilter. No search was performed. Retry once with {faceEventFilter: {pageRequest: null, searchFilter: {...}}}; use an explicit null searchFilter only for an unfiltered search.",
+                }),
+            };
+        }
+        const faceEventArgs = {
+            pageRequest: args.faceEventFilter?.pageRequest ?? null,
+            searchFilter: nestedFilter ?? args.searchFilter ?? null,
+        };
         let resolvedNamesOutput;
         const providedNames = faceEventArgs.searchFilter?.faceNames ?? [];
         if (providedNames.length > 0 && faceEventArgs.searchFilter) {
@@ -103,10 +160,11 @@ const TOOL_HANDLER = async (args, extra) => {
             }
         }
         let { faceEvents, lastEvaluatedKey } = await getFaceEvents(faceEventArgs, args.timeZone, requestModifiers, sessionId);
-        const hadLocationFilter = faceEventArgs.searchFilter?.locationUuids &&
-            faceEventArgs.searchFilter.locationUuids.length > 0;
+        const requestedLocationUuids = faceEventArgs.searchFilter?.locationUuids ?? [];
+        const hadLocationFilter = requestedLocationUuids.length > 0;
+        let note;
         if (faceEvents.length === 0 && hadLocationFilter) {
-            logger.info(`[faces-tool] Empty results with locationUuids filter ${JSON.stringify(faceEventArgs.searchFilter.locationUuids)}, retrying without location filter`);
+            logger.info(`[faces-tool] Empty results with locationUuids filter ${JSON.stringify(requestedLocationUuids)}, retrying without location filter`);
             const retryArgs = {
                 ...faceEventArgs,
                 searchFilter: { ...faceEventArgs.searchFilter, locationUuids: [] },
@@ -114,12 +172,29 @@ const TOOL_HANDLER = async (args, extra) => {
             const retry = await getFaceEvents(retryArgs, args.timeZone, requestModifiers, sessionId);
             faceEvents = retry.faceEvents;
             lastEvaluatedKey = retry.lastEvaluatedKey;
+            // Without this the caller cannot tell a location-scoped result from an
+            // org-wide one, and reports org-wide sightings as having happened at the
+            // requested location (observed in prod, 2026-08-03).
+            if (faceEvents.length > 0) {
+                note =
+                    `SCOPE CHANGED: no face events were found at the requested location(s) ` +
+                        `[${requestedLocationUuids.join(", ")}], so this search was re-run ACROSS THE WHOLE ORG. ` +
+                        `The events below are NOT limited to those locations — check each event's locationUuid before ` +
+                        `attributing a sighting to the location the user asked about, and tell the user the scope was widened.`;
+            }
+            else {
+                note =
+                    `No face events at the requested location(s) [${requestedLocationUuids.join(", ")}], ` +
+                        `and none org-wide for this time range either.`;
+            }
         }
         return createToolStructuredContent({
             requestType: RequestType.GET_FACE_EVENTS,
             getFaceEventsResponse: faceEvents,
+            faceEventSummary: summarizeFaceEvents(faceEvents, Boolean(lastEvaluatedKey)),
             lastEvaluatedKey: lastEvaluatedKey ?? undefined,
             resolvedNames: resolvedNamesOutput ?? undefined,
+            note,
         });
     }
     if (args.requestType === RequestType.GET_REGISTERED_FACES) {
@@ -134,6 +209,10 @@ const TOOL_HANDLER = async (args, extra) => {
                 getSavedFacesResponse: peopleResponse.people.map(p => ({
                     createdOn: p.createdOn ? parseInt(p.createdOn, 10) : undefined,
                     name: p.name ?? undefined,
+                    // As of 2026-08-05 api2 never serializes Person.email, so this is
+                    // always undefined today — mapped anyway so it surfaces for free if
+                    // the API starts returning it.
+                    email: p.email ?? undefined,
                     orgUuid: p.orgUuid ?? undefined,
                     updatedOn: p.updatedOn ? parseInt(p.updatedOn, 10) : undefined,
                     uuid: p.uuid ?? undefined,
@@ -161,6 +240,11 @@ const TOOL_HANDLER = async (args, extra) => {
         return createToolStructuredContent({
             requestType: RequestType.GET_PERSON_LABELS,
             getPersonLabelsResponse: cleaned,
+            // A bare {} reads as "the lookup returned nothing" — say what the empty
+            // result actually means so the model doesn't have to interpret it.
+            note: Object.keys(cleaned).length === 0
+                ? "This organization has no person labels at all: the query succeeded and every registered person currently has zero labels."
+                : undefined,
         });
     }
     if (args.requestType === RequestType.SEARCH_SIMILAR_FACES) {
@@ -196,14 +280,158 @@ const TOOL_HANDLER = async (args, extra) => {
             personFaceEvents: personEvents,
         });
     }
+    // -------------------------------------------------------------------------
+    // Person write paths
+    //
+    // These act on enrolled biometric records, so every branch verifies the person
+    // exists first: a plausible-but-wrong personUuid would otherwise rename or
+    // delete someone else's face record with a success response either way.
+    // -------------------------------------------------------------------------
+    if (args.requestType === RequestType.CREATE_PERSON) {
+        if (!args.personName?.trim()) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: "personName is required for create-person",
+            });
+        }
+        const created = await createPerson(args.personName.trim(), requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: args.requestType,
+            created: { success: created.success, uuid: created.uuid },
+            warningMsg: created.warningMsg,
+            note: `Created the person "${args.personName.trim()}". They have no enrolled face images yet, so face recognition will NOT identify them until a photo is enrolled — that has to be done in the Rhombus Console.`,
+        });
+    }
+    if (args.requestType === RequestType.UPDATE_PERSON) {
+        if (!args.personUuid) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: "personUuid is required for update-person",
+            });
+        }
+        if (!args.personName?.trim() && !args.personEmail?.trim()) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: "update-person needs at least one of personName or personEmail — both were empty, so there is nothing to change",
+            });
+        }
+        const existing = await findPerson(args.personUuid, requestModifiers, sessionId);
+        if (!existing) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: `No registered person has the uuid "${args.personUuid}". Use get-registered-faces to see who is registered — do not guess a uuid.`,
+            });
+        }
+        const updated = await updatePerson(args.personUuid, {
+            name: args.personName?.trim() || undefined,
+            email: args.personEmail?.trim() || undefined,
+        }, requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: args.requestType,
+            updated: { success: updated.success, uuid: updated.uuid },
+            warningMsg: updated.warningMsg,
+            note: `Updated ${existing.name ?? args.personUuid}${args.personName?.trim() ? ` — now named "${args.personName.trim()}"` : ""}. Their enrolled face images are unchanged, so recognition still matches the same face to this record.` +
+                // api2 accepts the email write but no read path — findPeopleByOrg,
+                // getPerson, or even the update response's own echo — ever returns it
+                // (verified against api2.itg 2026-08-05). Without this caveat the model
+                // would tell the user the email is saved and then fail to show it.
+                (args.personEmail?.trim()
+                    ? " NOTE: the API does not return a person's email on any read path, so the stored email cannot be displayed or verified later."
+                    : ""),
+        });
+    }
+    if (args.requestType === RequestType.DELETE_PERSON) {
+        if (!args.personUuid) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: "personUuid is required for delete-person",
+            });
+        }
+        const existing = await findPerson(args.personUuid, requestModifiers, sessionId);
+        if (!existing) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: `No registered person has the uuid "${args.personUuid}". Use get-registered-faces to see who is registered.`,
+            });
+        }
+        if (!args.confirmDelete) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                note: `NOT DELETED — nothing was changed. Deleting "${existing.name ?? args.personUuid}" removes their enrolled face images and ` +
+                    `cannot be undone: re-registering them needs new photos, and face alerts naming this person stop working. Past face events ` +
+                    `stay in the history but will no longer be attributed to them. Confirm with the user, then call again with confirmDelete: true.`,
+            });
+        }
+        const deleted = await deletePerson(args.personUuid, requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: args.requestType,
+            deleted: { success: deleted.success, uuid: deleted.uuid },
+            warningMsg: deleted.warningMsg,
+            note: `Deleted the registered person "${existing.name ?? args.personUuid}" and their enrolled faces. Face recognition will no longer identify them.`,
+        });
+    }
+    if (args.requestType === RequestType.ADD_PERSON_LABEL ||
+        args.requestType === RequestType.REMOVE_PERSON_LABEL) {
+        const removing = args.requestType === RequestType.REMOVE_PERSON_LABEL;
+        if (!args.personUuid || !args.personLabel?.trim()) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: `personUuid and personLabel are both required for ${args.requestType}`,
+            });
+        }
+        const existing = await findPerson(args.personUuid, requestModifiers, sessionId);
+        if (!existing) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: `No registered person has the uuid "${args.personUuid}". Use get-registered-faces to see who is registered.`,
+            });
+        }
+        const label = args.personLabel.trim();
+        const updated = await changePersonLabel(args.personUuid, label, removing ? "remove" : "add", requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: args.requestType,
+            updated: { success: updated.success, uuid: updated.uuid, label: updated.label },
+            warningMsg: updated.warningMsg,
+            note: `${removing ? "Removed" : "Added"} the label "${label}" ${removing ? "from" : "for"} ${existing.name ?? args.personUuid}. Camera policies that alert on person labels use these, so this can change which alerts fire.`,
+        });
+    }
+    if (args.requestType === RequestType.DELETE_FACE_MATCHMAKER) {
+        if (!args.faceId?.trim()) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                error: "faceId is required for delete-face-matchmaker",
+            });
+        }
+        if (!args.confirmDelete) {
+            return createToolStructuredContent({
+                requestType: args.requestType,
+                note: `NOT DELETED — nothing was changed. Deleting enrolled face ${args.faceId.trim()} removes that face image from recognition and ` +
+                    `cannot be undone; re-enrolling needs a new photo. The person record and any other enrolled faces they have are kept. ` +
+                    `Confirm with the user, then call again with confirmDelete: true.`,
+            });
+        }
+        const deleted = await deleteFaceMatchmaker(args.faceId.trim(), requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: args.requestType,
+            deleted: { success: deleted.success, faceId: deleted.faceId },
+            warningMsg: deleted.warningMsg,
+            note: "Deleted that enrolled face image. The person record and their other enrolled faces are unchanged — recognition may still identify them from those.",
+        });
+    }
     return createToolStructuredContent({
         requestType: args.requestType,
+        error: `Invalid requestType "${args.requestType}". Valid values are: ${Object.values(RequestType).join(", ")}.`,
     });
 };
 export function createTool(server) {
-    server.registerTool(TOOL_NAME, {
+    server.registerTool(TOOL_NAME, 
+    // faceEventSummary is the whole point of the roster: a caller that projects
+    // down to the raw event rows must not lose the deduplicated person list.
+    protectFields({
+        title: "Faces",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
-    }, TOOL_HANDLER);
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, ["faceEventSummary"]), TOOL_HANDLER);
 }

package/dist/tools-console/guest-management-tool.js

@@ -1,4 +1,4 @@
-import { getAllGuestsByOrg, getGuestActivityLogs, getActivitiesForLocation, } from "../api/guest-management-tool-api.js";
+import { getAllGuestsByOrg, getGuestActivityLogs, getActivitiesForLocation, createGuest, deleteGuest, getGuestPasses, changeGuestPassState, } from "../api/guest-management-tool-api.js";
 import { GuestManagementRequestType, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/guest-management-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "guest-management-tool";
@@ -9,6 +9,14 @@ It has the following modes of operation, determined by the "requestType" paramet
 - ${GuestManagementRequestType.GET_ALL_GUESTS}: List all guests across the organization with their check-in status, host, company, and contact info.
 - ${GuestManagementRequestType.GET_ACTIVITY_LOGS}: Get org-wide guest activity logs (sign-ins, sign-outs). Supports optional time range filtering via startTimeMs/endTimeMs.
 - ${GuestManagementRequestType.GET_ACTIVITIES_FOR_LOCATION}: Get guest activity logs for a specific location. Requires locationUuid. Supports optional time range filtering.
+- ${GuestManagementRequestType.CREATE_GUEST}: Register a guest. Requires guestFirstName, guestLastName, guestEmail and locationUuid.
+- ${GuestManagementRequestType.DELETE_GUEST}: Remove a guest record. Requires guestEmail and confirmDelete.
+- ${GuestManagementRequestType.GET_GUEST_PASSES}: List guest passes (the door-access credentials issued to guests), optionally filtered by time range.
+- ${GuestManagementRequestType.EXPIRE_GUEST_PASS}: End a guest pass's access while keeping its record. Requires guestPassUuid.
+- ${GuestManagementRequestType.SUSPEND_GUEST_PASS} / ${GuestManagementRequestType.UNSUSPEND_GUEST_PASS}: Temporarily disable / re-enable a guest pass. Requires guestPassUuid.
+- ${GuestManagementRequestType.DELETE_GUEST_PASS}: Destroy a guest pass record and its history. Requires guestPassUuid and confirmDelete.
+
+A guest is identified by EMAIL, not a UUID, so creating a guest whose email already exists overwrites that record rather than adding a second one. Guest passes control physical door access — confirm the guest by name before changing one.
 `;
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
@@ -31,6 +39,123 @@ const TOOL_HANDLER = async (args, _extra) => {
                 const activities = await getActivitiesForLocation(args.locationUuid, args.startTimeMs ?? undefined, args.endTimeMs ?? undefined, requestModifiers, sessionId);
                 return createToolStructuredContent({ activities });
             }
+            case GuestManagementRequestType.CREATE_GUEST: {
+                if (!args.guestFirstName?.trim() ||
+                    !args.guestLastName?.trim() ||
+                    !args.guestEmail?.trim() ||
+                    !args.locationUuid) {
+                    return createToolStructuredContent({
+                        error: "guestFirstName, guestLastName, guestEmail and locationUuid are all required for create-guest.",
+                    });
+                }
+                const email = args.guestEmail.trim();
+                // A guest is keyed on email, so creating one that already exists would
+                // overwrite the existing visit rather than adding a second guest.
+                const guests = await getAllGuestsByOrg(requestModifiers, sessionId);
+                const existing = guests.find(guest => guest.email?.trim().toLowerCase() === email.toLowerCase());
+                if (existing) {
+                    return createToolStructuredContent({
+                        guests: [existing],
+                        note: `Nothing was created — ${email} is already registered as a guest (${[existing.firstName, existing.lastName].filter(Boolean).join(" ") || "no name"}). Guests are identified by email, so creating again would overwrite that record. Confirm with the user whether they meant to replace it.`,
+                    });
+                }
+                const created = await createGuest({
+                    firstName: args.guestFirstName.trim(),
+                    lastName: args.guestLastName.trim(),
+                    email,
+                    locationUuid: args.locationUuid,
+                    hostUserUuid: args.hostUserUuid ?? undefined,
+                    companyName: args.guestCompanyName?.trim() || undefined,
+                    guestType: args.guestType ?? "GENERAL_VISITOR",
+                    accessStartTimeMs: args.accessStartTimeMs ?? undefined,
+                    accessEndTimeMs: args.accessEndTimeMs ?? undefined,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    created,
+                    warningMsg: created.warningMsg,
+                    note: args.accessEndTimeMs
+                        ? `Registered ${args.guestFirstName.trim()} ${args.guestLastName.trim()} (${email}) as a guest.`
+                        : `Registered ${args.guestFirstName.trim()} ${args.guestLastName.trim()} (${email}) as a guest with NO access end time, so their access does not expire on its own. Offer to set accessEndTimeMs.`,
+                });
+            }
+            case GuestManagementRequestType.DELETE_GUEST: {
+                if (!args.guestEmail?.trim()) {
+                    return createToolStructuredContent({
+                        error: "guestEmail is required for delete-guest — guests are identified by email, not a UUID.",
+                    });
+                }
+                const email = args.guestEmail.trim();
+                const guests = await getAllGuestsByOrg(requestModifiers, sessionId);
+                const existing = guests.find(guest => guest.email?.trim().toLowerCase() === email.toLowerCase());
+                if (!existing) {
+                    return createToolStructuredContent({
+                        error: `No guest in this organization has the email ${email}, so there is nothing to delete. Use get-all-guests to see the registered guests.`,
+                    });
+                }
+                if (!args.confirmDelete) {
+                    return createToolStructuredContent({
+                        guests: [existing],
+                        note: `NOT DELETED — nothing was changed. Deleting the guest ${[existing.firstName, existing.lastName].filter(Boolean).join(" ") || email} ` +
+                            `removes their record and their site access, and cannot be undone. Confirm with the user, then call again with confirmDelete: true.`,
+                    });
+                }
+                const deleted = await deleteGuest(email, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleted,
+                    warningMsg: deleted.warningMsg,
+                    note: `Deleted the guest record for ${email}. Their past check-in activity remains in the activity log.`,
+                });
+            }
+            case GuestManagementRequestType.GET_GUEST_PASSES: {
+                const { guestPasses, lastEvaluatedKey } = await getGuestPasses({
+                    startAfterMs: args.startTimeMs ?? undefined,
+                    startBeforeMs: args.endTimeMs ?? undefined,
+                }, requestModifiers, sessionId);
+                const active = guestPasses.filter(pass => pass.lifecycle === "ACTIVE").length;
+                return createToolStructuredContent({
+                    guestPasses,
+                    lastEvaluatedKey,
+                    note: guestPasses.length === 0
+                        ? "No guest passes match this time range. That is not the same as the organization having none — widen startTimeMs / endTimeMs to check."
+                        : `${active} of ${guestPasses.length} pass(es) in this range are ACTIVE; the rest are suspended, expired or archived.`,
+                });
+            }
+            case GuestManagementRequestType.EXPIRE_GUEST_PASS:
+            case GuestManagementRequestType.SUSPEND_GUEST_PASS:
+            case GuestManagementRequestType.UNSUSPEND_GUEST_PASS:
+            case GuestManagementRequestType.DELETE_GUEST_PASS: {
+                const action = args.requestType === GuestManagementRequestType.EXPIRE_GUEST_PASS
+                    ? "expire"
+                    : args.requestType === GuestManagementRequestType.SUSPEND_GUEST_PASS
+                        ? "suspend"
+                        : args.requestType === GuestManagementRequestType.UNSUSPEND_GUEST_PASS
+                            ? "unsuspend"
+                            : "delete";
+                if (!args.guestPassUuid) {
+                    return createToolStructuredContent({
+                        error: `guestPassUuid is required for ${args.requestType}. Use get-guest-passes to find it.`,
+                    });
+                }
+                if (action === "delete" && !args.confirmDelete) {
+                    return createToolStructuredContent({
+                        note: `NOT DELETED — nothing was changed. Deleting guest pass ${args.guestPassUuid} destroys the record and its history. ` +
+                            `To end the access while keeping the record, use expire-guest-pass instead. To delete anyway, confirm with the user and ` +
+                            `call again with confirmDelete: true.`,
+                    });
+                }
+                const guestPassChange = await changeGuestPassState(args.guestPassUuid, action, requestModifiers, sessionId);
+                const notes = {
+                    expire: "Expired the guest pass. It no longer opens any door; the record and its history are kept.",
+                    suspend: "Suspended the guest pass. It will not open any door until unsuspend-guest-pass is used.",
+                    unsuspend: "Un-suspended the guest pass. It opens doors again.",
+                    delete: "Deleted the guest pass record permanently, along with its history.",
+                };
+                return createToolStructuredContent({
+                    guestPassChange,
+                    warningMsg: guestPassChange.warningMsg,
+                    note: notes[action],
+                });
+            }
         }
     }
     catch (error) {
@@ -43,8 +168,10 @@ const TOOL_HANDLER = async (args, _extra) => {
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
+        title: "Guest Management",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }