rhombus-node-mcp 0.1.21 → 0.1.23

package/dist/tools/events-tool.js

@@ -1,4 +1,4 @@
-import { getAccessControlEvents, getEventsForEnvironmentalGateway, getClimateEventsForSensor, getComponentEventsByLocation, getHumanMotionEvents, } from "../api/events-tool-api.js";
+import { getAccessControlEvents, getEventsForEnvironmentalGateway, getClimateEventsForSensor, getComponentEventsByLocation, getHumanMotionEvents, getButtonPressEvents, getOccupancyEvents, getProximityEvents, getDoorbellEvents, } from "../api/events-tool-api.js";
 import { EventsToolRequestType, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/events-tools-types.js";
 import { createToolStructuredContent } from "../util.js";
 import { getLogger } from "../logger.js";
@@ -7,56 +7,59 @@ const logger = getLogger("events-tool");
 const TOOL_NAME = "events-tool";
 // "faces" | "people" | "human" | "access-control"
 const TOOL_DESCRIPTION = `
-This tool interacts with the Rhombus events system to retrieve information about various types of events within the system. It has 5 modes of operation, determined by the "eventType" parameter: access-control, environmental-gateway, climate-sensor, component-events, and camera
+**Scope:** This tool returns **raw, event-level data** (individual events with timestamps). Use **report-tool** when you need aggregated counts, time-series summaries, or analytics over intervals.
 
-This tool should should be used any time someone is asking for specifics or reports for access control related events like unlocks, badge ins, credentials, arrivals etc., environmental gateway events, climate sensor events, camera motion events, or any other component events.
+This tool has 5 modes, set by "eventType": access-control, environmental-gateway, climate-sensor, component-events, camera. Use it when the user asks for specific events (unlocks, badge ins, credentials, arrivals, environmental readings, climate data, camera motion, or other component events). It can return large result sets; keep time ranges narrow. For ranges spanning more than ~24 hours, prefer report-tool for aggregates. For maximum flexibility across event types at a location, use eventType "component-events".
 
-For maximum flexibility, use eventType "component-events" which allows querying any combination of event types (doorbell pushes, badge scans, door state changes, button presses, etc.) for a location.
+---
 
-This tool retrieves a list of events captured by the access control door system pertaining to arrivals, badge ins, credentials received, etc. 
+When eventType is "access-control":
 
-This tool can return a lot of data. Please make sure the time range provided is not too large.
-  This tool takes 3 arguments:
-  * **accessControlledDoorUuid (string):** The unique identifier for the access controlled door.
-  * **startTime (string):** The timestamp (in ISO 8601 format) representing the start or earliest time of access control events.
-  * **endTime (string):** The timestamp (in ISO 8601 format) representing the end or latest time of access control events.
+Retrieves access control events (arrivals, badge ins, credentials, unlocks) for the given door(s). Can return a lot of data—use a narrow time range.
 
-  The tool returns a JSON object with access control events data.
+Arguments:
+  * **accessControlledDoorUuids (array of strings):** UUIDs of the access-controlled doors.
+  * **startTime (string):** Start of the time range (ISO 8601).
+  * **endTime (string):** End of the time range (ISO 8601).
 
-When eventType is "environmental-gateway":
+The \`credSource\` field indicates how the event was triggered:
+  * **REMOTE:** Rhombus Key app remote unlock.
+  * **REMOTE (Admin):** Unlock via Rhombus console or browser/mobile app.
+  * **BLE_WAVE:** User waved hand over the reader.
+  * **NFC:** User tapped badge or phone on the reader.
 
-This tool retrieves environmental gateway events for a specific environmental gateway device within a time range. The data returned will have a timestamp that is in
-the timezone of the **device**, not necessarily UTC time.
+---
 
-This tool takes 3 arguments:
-  * **deviceUuid (string):** The unique identifier for the environmental gateway device.
-  * **startTime (string):** The timestamp (in ISO 8601 format) representing the start time of events.
-  * **endTime (string):** The timestamp (in ISO 8601 format) representing the end time of events.
+Retrieves environmental gateway events (sensor readings, derived values) for a device in a time range. Timestamps are in the **device** timezone, not necessarily UTC.
 
-The tool returns a JSON object with environmental gateway events data.
+Arguments:
+  * **deviceUuid (string):** UUID of the environmental gateway device.
+  * **startTime (string):** Start of range (ISO 8601).
+  * **endTime (string):** End of range (ISO 8601).
+
+---
 
 When eventType is "climate-sensor":
 
-This tool retrieves climate sensor events for a specific climate sensor within a time range. The data returned will have a timestamp that is in
-the timezone of the **sensor**, not necessarily UTC time.
+Retrieves climate sensor events (temperature, humidity, air quality, etc.) for a sensor in a time range. Timestamps are in the **sensor** timezone, not necessarily UTC.
 
-This tool takes 4 arguments:
-  * **sensorUuid (string):** The unique identifier for the climate sensor.
-  * **startTime (string):** The timestamp (in ISO 8601 format) representing the start time of events.
-  * **endTime (string):** The timestamp (in ISO 8601 format) representing the end time of events.
-  * **limit (number, optional):** Maximum number of climate events to return. Default is 1000.
+Arguments:
+  * **sensorUuid (string):** UUID of the climate sensor.
+  * **startTime (string):** Start of range (ISO 8601).
+  * **endTime (string):** End of range (ISO 8601).
+  * **limit (number, optional):** Max events to return. Default 1000.
 
-The tool returns a JSON object with climate sensor events data.
+---
 
 When eventType is "component-events":
 
-This tool retrieves ALL types of component events for a specific location within a time range. This is the most flexible option and allows filtering by specific event types. The data returned will have a timestamp that is in the timezone of the **location**, not necessarily UTC time.
+Retrieves all component event types for a location in a time range. Most flexible option; filter by event type via componentEventTypes. Timestamps are in the **location** timezone, not necessarily UTC.
 
-This tool takes 4 arguments:
-  * **locationUuid (string):** The unique identifier for the location.
-  * **componentEventTypes (array of strings, optional):** Array of event types to filter by. If empty or not provided, returns all event types.
-  * **startTime (string):** The timestamp (in ISO 8601 format) representing the start time of events.
-  * **endTime (string):** The timestamp (in ISO 8601 format) representing the end time of events.
+Arguments:
+  * **locationUuid (string):** UUID of the location.
+  * **componentEventTypes (array, optional):** Event types to include. If empty or omitted, returns all types.
+  * **startTime (string):** Start of range (ISO 8601).
+  * **endTime (string):** End of range (ISO 8601).
 
 Valid event types include:
   * **DoorbellEvent:** Doorbell button press events
@@ -71,108 +74,127 @@ Valid event types include:
   * **WaveToUnlockIntentExpiredEvent:** Wave-to-unlock timeout events
   * **DoorAuthFirstInStateEvent:** First-in authentication state events
   * **DoorScheduleFirstInStateEvent:** First-in schedule state events
-  * And more...
+  * And more (see input schema for full list).
+
+---
 
 When eventType is "camera":
 
-This tool retrieves human motion events detected by a specific camera within a time range. The data returned will have timestamps in milliseconds.
+Retrieves human motion events for a camera in a time range. Timestamps in milliseconds.
 
-This tool takes 3 arguments:
-  * **cameraUuid (string):** The unique identifier for the camera.
-  * **startTime (string):** The timestamp (in ISO 8601 format) representing the start time of events.
-  * **duration (number):** Duration in seconds to search for human motion events. Default is 3600 (1 hour).
+Arguments:
+  * **cameraUuid (string):** UUID of the camera.
+  * **startTime (string):** Start of range (ISO 8601).
+  * **duration (number):** Search window in seconds. Default 3600 (1 hour).
 
-The tool returns a JSON object with camera events data.
 `;
 const TOOL_HANDLER = async (args, extra) => {
-    const { eventType, accessControlledDoorUuids, deviceUuid, sensorUuid, locationUuid, componentEventTypes, startTime, endTime, limit, timeZone, tempUnit, cameraUuid, duration, } = args;
+    const { eventType, accessControlledDoorUuids, deviceUuid, sensorUuid, locationUuid, componentEventTypes, startTime, endTime, limit, timeZone, tempUnit, cameraUuid, duration, buttonSensorUuid, occupancySensorUuid, proximityTagUuids, doorbellCameraUuid, } = args;
     logger.debug(`eventType: ${eventType}`);
     switch (eventType) {
         case "access-control": {
             if (!accessControlledDoorUuids || accessControlledDoorUuids.length === 0) {
-                const result = {
+                return createToolStructuredContent({
                     needUserInput: true,
                     commandForUser: "Which door are you asking about?",
-                };
-                return createToolStructuredContent(result);
+                });
             }
             else {
                 const events = await getAccessControlEvents(accessControlledDoorUuids, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
-                const result = {
-                    eventType: "access-control",
-                    accessControlEvents: events,
-                };
-                return createToolStructuredContent(result);
+                return createToolStructuredContent({ eventType: "access-control", accessControlEvents: events });
             }
         }
         case "environmental-gateway": {
             if (!deviceUuid) {
-                const result = {
+                return createToolStructuredContent({
                     needUserInput: true,
                     commandForUser: "Which environmental gateway device are you asking about?",
-                };
-                return createToolStructuredContent(result);
+                });
             }
             else {
                 const events = await getEventsForEnvironmentalGateway(deviceUuid, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, tempUnit ?? TempUnit.CELSIUS, extra._meta?.requestModifiers, extra.sessionId);
-                const result = {
-                    eventType: "environmental-gateway",
-                    environmentalGatewayEvents: events,
-                };
-                return createToolStructuredContent(result);
+                return createToolStructuredContent({ eventType: "environmental-gateway", environmentalGatewayEvents: events });
             }
         }
         case "climate-sensor": {
             if (!sensorUuid) {
-                const result = {
+                return createToolStructuredContent({
                     needUserInput: true,
                     commandForUser: "Which climate sensor are you asking about?",
-                };
-                return createToolStructuredContent(result);
+                });
             }
             else {
                 const events = await getClimateEventsForSensor(sensorUuid, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, limit ?? null, timeZone, tempUnit ?? TempUnit.CELSIUS, extra._meta?.requestModifiers, extra.sessionId);
-                const result = {
-                    eventType: "climate-sensor",
-                    climateSensorEvents: events,
-                };
-                return createToolStructuredContent(result);
+                return createToolStructuredContent({ eventType: "climate-sensor", climateSensorEvents: events });
             }
         }
         case "component-events": {
             if (!locationUuid) {
-                const result = {
+                return createToolStructuredContent({
                     needUserInput: true,
                     commandForUser: "Which location are you asking about?",
-                };
-                return createToolStructuredContent(result);
+                });
             }
             else {
                 const events = await getComponentEventsByLocation(locationUuid, componentEventTypes || [], startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
-                const result = {
-                    eventType: "component-events",
-                    componentEvents: events,
-                };
-                return createToolStructuredContent(result);
+                return createToolStructuredContent({ eventType: "component-events", componentEvents: events });
             }
         }
         case EventsToolRequestType.CAMERA: {
             if (!cameraUuid) {
-                const result = {
+                return createToolStructuredContent({
                     needUserInput: true,
                     commandForUser: "Which camera are you asking about?",
-                };
-                return createToolStructuredContent(result);
+                });
             }
             else {
-                const events = await getHumanMotionEvents(cameraUuid, duration ?? 3600, // Default to 1 hour if not provided
-                startTime ? new Date(startTime).getTime() : Date.now() - 3600000, // Default to 1 hour ago if not provided
-                extra._meta?.requestModifiers, extra.sessionId);
+                const events = await getHumanMotionEvents(cameraUuid, duration ?? 3600, startTime ? new Date(startTime).getTime() : Date.now() - 3600000, extra._meta?.requestModifiers, extra.sessionId);
+                return createToolStructuredContent({ eventType: "camera", cameraEvents: events.uniqueHumanEvents });
+            }
+        }
+        case EventsToolRequestType.BUTTON_PRESS: {
+            const bSensorUuid = args.buttonSensorUuid;
+            if (!bSensorUuid) {
+                return createToolStructuredContent({
+                    needUserInput: true,
+                    commandForUser: "Which button sensor are you asking about?",
+                });
+            }
+            const buttonEvents = await getButtonPressEvents(bSensorUuid, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
+            return createToolStructuredContent({ eventType: "button-press", buttonPressEvents: buttonEvents });
+        }
+        case EventsToolRequestType.OCCUPANCY: {
+            const occSensorUuid = args.occupancySensorUuid;
+            if (!occSensorUuid) {
                 return createToolStructuredContent({
-                    eventType: "camera",
-                    cameraEvents: events.uniqueHumanEvents,
+                    needUserInput: true,
+                    commandForUser: "Which occupancy sensor are you asking about?",
+                });
+            }
+            const occupancyEvts = await getOccupancyEvents(occSensorUuid, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
+            return createToolStructuredContent({ eventType: "occupancy", occupancyEvents: occupancyEvts });
+        }
+        case EventsToolRequestType.PROXIMITY: {
+            const tagUuids = args.proximityTagUuids;
+            if (!tagUuids || tagUuids.length === 0) {
+                return createToolStructuredContent({
+                    needUserInput: true,
+                    commandForUser: "Which proximity tags are you asking about?",
+                });
+            }
+            const proxEvents = await getProximityEvents(tagUuids, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
+            return createToolStructuredContent({ eventType: "proximity", proximityEvents: proxEvents });
+        }
+        case EventsToolRequestType.DOORBELL: {
+            const dbCamUuid = args.doorbellCameraUuid;
+            if (!dbCamUuid) {
+                return createToolStructuredContent({
+                    needUserInput: true,
+                    commandForUser: "Which doorbell camera are you asking about?",
                 });
             }
+            const doorbellEvts = await getDoorbellEvents(dbCamUuid, startTime ? new Date(startTime).getTime() : undefined, endTime ? new Date(endTime).getTime() : undefined, timeZone, extra._meta?.requestModifiers, extra.sessionId);
+            return createToolStructuredContent({ eventType: "doorbell", doorbellEvents: doorbellEvts });
         }
     }
     // This should not happen, but return empty result if eventType is unknown

package/dist/tools/faces-tool.js

@@ -1,61 +1,204 @@
-import { getFaceEvents, getRegisteredFaces } from "../api/faces-tool-api.js";
+import { getFaceEvents, getFaceEventsByPerson, getFaceMatchmakers, getPersonLabels, getRegisteredFaces, searchSimilarFaces } from "../api/faces-tool-api.js";
+import { logger } from "../logger.js";
 import { OUTPUT_SCHEMA, RequestType, TOOL_ARGS, } from "../types/faces-tools-types.js";
-import { extractFromToolExtra } from "../util.js";
+import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "faces-tool";
-// TODO: deviceUuids filter was removed, see TOOL_ARGS for reason
+/**
+ * Fuzzy-match user-provided names against the registered faces directory.
+ * Scoring: 4 = exact full name, 3 = first name, 2 = last name, 1 = substring (min 3 chars).
+ * Returns the best match per queried name.
+ */
+function resolveNamesToRegisteredFaces(userNames, registeredPeople) {
+    return userNames.map(userName => {
+        const input = userName.toLowerCase().trim();
+        if (!input)
+            return { queriedName: userName, resolvedName: null, resolvedPersonUuid: null };
+        let best = null;
+        for (const person of registeredPeople) {
+            if (!person.name || !person.uuid)
+                continue;
+            const fullName = person.name.toLowerCase().trim();
+            const parts = fullName.split(/\s+/);
+            let score = 0;
+            if (fullName === input)
+                score = 4;
+            else if (parts[0] === input)
+                score = 3;
+            else if (parts.length > 1 && parts[parts.length - 1] === input)
+                score = 2;
+            else if (input.length >= 3 && fullName.includes(input))
+                score = 1;
+            if (score > 0 && (!best || score > best.score)) {
+                best = { name: person.name, uuid: person.uuid, score };
+            }
+        }
+        return {
+            queriedName: userName,
+            resolvedName: best?.name ?? null,
+            resolvedPersonUuid: best?.uuid ?? null,
+        };
+    });
+}
 const TOOL_DESCRIPTION = `
-This tool interacts with the Rhombus face recognition system to retrieve information about face sightings and registered faces. It has two primary modes of operation, determined by the "requestType" parameter:
+This tool interacts with the Rhombus face recognition system to retrieve information about face sightings and registered faces.
 
-It should only be used if someone is specifically asking about faces.  If they are asking about people or humans, you should use the events-tool with eventType "people" instead as this tool is for face sightings only.
+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.
+
+**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.
 
 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.
-- This tool retrieves detailed face events such as detections and recognitions. It provides comprehensive information about each event, including details about the detected face, the person matched (if any), and the event context.
+- 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.
 
 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.
-- this returns ALL people registered in the system, regardless of the provided timestampFilter.
-- This is useful to call before calling "get-face-events" to get a list of all people that have been seen by the camera system, and then you can use personUuids or the name *in the system* to filter face events.
+- 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.
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
-    let ret = {
-        requestType: args.requestType,
-    };
     if (args.requestType === RequestType.GET_FACE_EVENTS) {
-        const response = await getFaceEvents(args.faceEventFilter, args.timeZone, requestModifiers, sessionId);
-        ret = {
+        const faceEventArgs = args.faceEventFilter;
+        let resolvedNamesOutput;
+        const providedNames = faceEventArgs.searchFilter?.faceNames ?? [];
+        if (providedNames.length > 0 && faceEventArgs.searchFilter) {
+            try {
+                const peopleResponse = await getRegisteredFaces({}, requestModifiers, sessionId);
+                if (peopleResponse.people) {
+                    const resolutions = resolveNamesToRegisteredFaces(providedNames, peopleResponse.people);
+                    resolvedNamesOutput = {};
+                    const resolvedUuids = [];
+                    const resolvedExactNames = [];
+                    const unresolvedNames = [];
+                    for (const r of resolutions) {
+                        resolvedNamesOutput[r.queriedName] = r.resolvedName;
+                        if (r.resolvedPersonUuid && r.resolvedName) {
+                            resolvedUuids.push(r.resolvedPersonUuid);
+                            resolvedExactNames.push(r.resolvedName);
+                        }
+                        else {
+                            unresolvedNames.push(r.queriedName);
+                        }
+                    }
+                    if (resolvedUuids.length > 0) {
+                        const existingUuids = faceEventArgs.searchFilter.personUuids ?? [];
+                        const mergedUuids = [...new Set([...existingUuids, ...resolvedUuids])];
+                        faceEventArgs.searchFilter.personUuids = mergedUuids;
+                        faceEventArgs.searchFilter.faceNames = [...resolvedExactNames, ...unresolvedNames];
+                        logger.info(`[faces-tool] Auto-resolved names: ${JSON.stringify(resolvedNamesOutput)}`);
+                    }
+                }
+            }
+            catch (e) {
+                logger.warn("[faces-tool] Name resolution failed, proceeding with original args", e);
+            }
+        }
+        let { faceEvents, lastEvaluatedKey } = await getFaceEvents(faceEventArgs, args.timeZone, requestModifiers, sessionId);
+        const hadLocationFilter = faceEventArgs.searchFilter?.locationUuids &&
+            faceEventArgs.searchFilter.locationUuids.length > 0;
+        if (faceEvents.length === 0 && hadLocationFilter) {
+            logger.info(`[faces-tool] Empty results with locationUuids filter ${JSON.stringify(faceEventArgs.searchFilter.locationUuids)}, retrying without location filter`);
+            const retryArgs = {
+                ...faceEventArgs,
+                searchFilter: { ...faceEventArgs.searchFilter, locationUuids: [] },
+            };
+            const retry = await getFaceEvents(retryArgs, args.timeZone, requestModifiers, sessionId);
+            faceEvents = retry.faceEvents;
+            lastEvaluatedKey = retry.lastEvaluatedKey;
+        }
+        return createToolStructuredContent({
             requestType: RequestType.GET_FACE_EVENTS,
-            getFaceEventsResponse: response,
-        };
+            getFaceEventsResponse: faceEvents,
+            lastEvaluatedKey: lastEvaluatedKey ?? undefined,
+            resolvedNames: resolvedNamesOutput ?? undefined,
+        });
     }
-    else if (args.requestType === RequestType.GET_REGISTERED_FACES) {
-        const response = await getRegisteredFaces(args, requestModifiers, sessionId);
-        if (response.people) {
-            ret = {
+    if (args.requestType === RequestType.GET_REGISTERED_FACES) {
+        const [peopleResponse, labelsResponse] = await Promise.all([
+            getRegisteredFaces(args, requestModifiers, sessionId),
+            getPersonLabels(requestModifiers, sessionId),
+        ]);
+        const labelsByPerson = labelsResponse.labelsByPerson ?? {};
+        if (peopleResponse.people) {
+            return createToolStructuredContent({
                 requestType: RequestType.GET_REGISTERED_FACES,
-                getSavedFacesResponse: response.people.map(p => ({
+                getSavedFacesResponse: peopleResponse.people.map(p => ({
                     createdOn: p.createdOn ? parseInt(p.createdOn, 10) : undefined,
                     name: p.name ?? undefined,
                     orgUuid: p.orgUuid ?? undefined,
                     updatedOn: p.updatedOn ? parseInt(p.updatedOn, 10) : undefined,
                     uuid: p.uuid ?? undefined,
+                    labels: p.uuid
+                        ? (labelsByPerson[p.uuid] ?? []).filter((l) => l != null)
+                        : undefined,
                 })),
-            };
+            });
         }
-        else {
-            ret = {
-                requestType: RequestType.GET_REGISTERED_FACES,
-                error: String(response.error),
-            };
+        return createToolStructuredContent({
+            requestType: RequestType.GET_REGISTERED_FACES,
+            error: String(peopleResponse.error),
+        });
+    }
+    if (args.requestType === RequestType.GET_PERSON_LABELS) {
+        const response = await getPersonLabels(requestModifiers, sessionId);
+        const cleaned = {};
+        if (response.labelsByPerson) {
+            for (const [personUuid, labels] of Object.entries(response.labelsByPerson)) {
+                if (labels) {
+                    cleaned[personUuid] = labels.filter((l) => l != null);
+                }
+            }
+        }
+        return createToolStructuredContent({
+            requestType: RequestType.GET_PERSON_LABELS,
+            getPersonLabelsResponse: cleaned,
+        });
+    }
+    if (args.requestType === RequestType.SEARCH_SIMILAR_FACES) {
+        if (!args.faceEventUuid) {
+            return createToolStructuredContent({
+                requestType: RequestType.SEARCH_SIMILAR_FACES,
+                error: "faceEventUuid is required for search-similar-faces",
+            });
         }
+        const similarEvents = await searchSimilarFaces(args.faceEventUuid, args.timeZone, requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: RequestType.SEARCH_SIMILAR_FACES,
+            similarFaceEvents: similarEvents,
+        });
+    }
+    if (args.requestType === RequestType.GET_FACE_MATCHMAKERS) {
+        const matchmakers = await getFaceMatchmakers(requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: RequestType.GET_FACE_MATCHMAKERS,
+            faceMatchmakers: matchmakers,
+        });
     }
-    return {
-        content: [{ type: "text", text: JSON.stringify(ret) }],
-        structuredContent: ret,
-    };
+    if (args.requestType === RequestType.GET_FACE_EVENTS_BY_PERSON) {
+        if (!args.personUuid) {
+            return createToolStructuredContent({
+                requestType: RequestType.GET_FACE_EVENTS_BY_PERSON,
+                error: "personUuid is required for get-face-events-by-person",
+            });
+        }
+        const { faceEvents: personEvents } = await getFaceEventsByPerson(args.personUuid, args.timeZone, requestModifiers, sessionId);
+        return createToolStructuredContent({
+            requestType: RequestType.GET_FACE_EVENTS_BY_PERSON,
+            personFaceEvents: personEvents,
+        });
+    }
+    return createToolStructuredContent({
+        requestType: args.requestType,
+    });
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {

package/dist/tools/get-entity-tool.js

@@ -7,7 +7,12 @@ const TOOL_DESCRIPTION = `
 Retrieves entities (or devices) of certain types.
 Can request multiple entity types at once.
 The return structure is a JSON string that contains the states of the requested entities.
-This data is exact. Whatever entities exist will be returned here.`;
+This data is exact. Whatever entities exist will be returned here.
+
+This is the primary tool for checking device health and connectivity status. Each device in the response
+includes a "connected" boolean field indicating whether it is currently online (true) or offline (false).
+When asked about device health, offline devices, or connectivity issues, use this tool to fetch all device
+types and check the "connected" field to identify which devices are offline or unreachable.`;
 const TOOL_HANDLER = async (args, extra) => {
     const { entityTypes, timeZone, filterBy, tempUnit } = args;
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);

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

@@ -0,0 +1,50 @@
+import { getAllGuestsByOrg, getGuestActivityLogs, getActivitiesForLocation, } 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";
+const TOOL_DESCRIPTION = `
+This tool manages Rhombus guest/visitor operations. It can list all guests, retrieve activity logs, and filter activities by location.
+
+It has the following modes of operation, determined by the "requestType" parameter:
+- ${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.
+`;
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        switch (args.requestType) {
+            case GuestManagementRequestType.GET_ALL_GUESTS: {
+                const guests = await getAllGuestsByOrg(requestModifiers, sessionId);
+                return createToolStructuredContent({ guests });
+            }
+            case GuestManagementRequestType.GET_ACTIVITY_LOGS: {
+                const activities = await getGuestActivityLogs(args.startTimeMs ?? undefined, args.endTimeMs ?? undefined, requestModifiers, sessionId);
+                return createToolStructuredContent({ activities });
+            }
+            case GuestManagementRequestType.GET_ACTIVITIES_FOR_LOCATION: {
+                if (!args.locationUuid) {
+                    return createToolStructuredContent({
+                        error: "locationUuid is required for get-activities-for-location.",
+                    });
+                }
+                const activities = await getActivitiesForLocation(args.locationUuid, args.startTimeMs ?? undefined, args.endTimeMs ?? undefined, requestModifiers, sessionId);
+                return createToolStructuredContent({ activities });
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return createToolStructuredContent({ error: error.message });
+        }
+        return createToolStructuredContent({ error: "Unknown error" });
+    }
+    return createToolStructuredContent({ error: "Invalid request type" });
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/tools/location-tool.js

@@ -1,8 +1,11 @@
-import { getLocations } from "../api/location-tool-api.js";
+import { getLocations, createLocation, updateLocation, getLocationLabels } from "../api/location-tool-api.js";
 import { TOOL_ARGS } from "../types/location-tool-types.js";
 const TOOL_NAME = "location-tool";
 const TOOL_DESCRIPTION = `This tool performs operations on locations.
-- 'get': Retrieves all locations.  When generating reports with location details, use location names not uuids.`;
+- 'get': Retrieves all locations.  When generating reports with location details, use location names not uuids.
+- 'create': Creates a new location with a name and optional address.
+- 'update': Updates an existing location (requires locationUuid).
+- 'get-labels': Retrieves all location labels for the organization.`;
 const TOOL_HANDLER = async (args, extra) => {
     const { action } = args;
     let ret;
@@ -10,8 +13,24 @@ const TOOL_HANDLER = async (args, extra) => {
         case "get":
             ret = await getLocations(extra._meta?.requestModifiers, extra.sessionId);
             break;
-        case "update":
-            ret = { error: true, status: "not implemented" };
+        case "create": {
+            if (!args.locationName) {
+                ret = { error: true, status: "locationName is required for 'create'" };
+                break;
+            }
+            ret = await createLocation(args.locationName, args.locationAddress ?? undefined, extra._meta?.requestModifiers, extra.sessionId);
+            break;
+        }
+        case "update": {
+            if (!args.locationUuid) {
+                ret = { error: true, status: "locationUuid is required for 'update'" };
+                break;
+            }
+            ret = await updateLocation(args.locationUuid, args.locationUpdate?.name, args.locationAddress ?? undefined, extra._meta?.requestModifiers, extra.sessionId);
+            break;
+        }
+        case "get-labels":
+            ret = await getLocationLabels(extra._meta?.requestModifiers, extra.sessionId);
             break;
         default:
             ret = { error: true, status: `unsupported location tool call: ${action}` };