rhombus-node-mcp 0.1.56 → 0.1.57

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

@@ -1,50 +1,171 @@
-import { getLocations, createLocation, updateLocation, getLocationLabels } from "../api/location-tool-api.js";
-import { TOOL_ARGS } from "../types/location-tool-types.js";
+import { matchesEntityName } from "../utils/entity-name-match.js";
+import { addLocationLabel, createLocation, deleteLocation, findLocation, getLocationLabels, getLocations, removeLocationLabel, updateLocation, } from "../api/location-tool-api.js";
+import { LocationToolAction, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/location-tool-types.js";
+import { createToolStructuredContent, createToolTextContent, extractFromToolExtra, } from "../util.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.
-- '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.`;
+- '${LocationToolAction.GET}': Retrieves locations with their address, timezone and labels. Pass locationName to search names ignoring case, spaces and punctuation ("iceblocks" matches "Ice Blocks - Headquarters"), or omit it to list all locations. All matches are returned; disambiguate when more than one location matches. When generating reports with location details, use location names not uuids.
+- '${LocationToolAction.CREATE}': Creates a new location with a name and optional address.
+- '${LocationToolAction.UPDATE}': Updates an existing location. Requires locationUuid plus at least one of locationName, locationAddress, postalCode, countryCode, timezoneId. Fields you omit are left unchanged.
+- '${LocationToolAction.DELETE}': Deletes a location. Requires locationUuid. Refuses by default — see confirmDelete.
+- '${LocationToolAction.GET_LABELS}': Retrieves all location labels for the organization.
+- '${LocationToolAction.ADD_LABEL}' / '${LocationToolAction.REMOVE_LABEL}': Attaches or detaches one label on one location. Requires locationUuid and label.`;
 const TOOL_HANDLER = async (args, extra) => {
-    const { action } = args;
-    let ret;
-    switch (action) {
-        case "get":
-            ret = await getLocations(extra._meta?.requestModifiers, extra.sessionId);
-            break;
-        case "create": {
-            if (!args.locationName) {
-                ret = { error: true, status: "locationName is required for 'create'" };
-                break;
+    const { requestModifiers, sessionId } = extractFromToolExtra(extra);
+    try {
+        switch (args.action) {
+            case LocationToolAction.GET: {
+                const { locations, warningMsg } = await getLocations(requestModifiers, sessionId);
+                const query = args.locationName?.trim();
+                const matches = query
+                    ? locations.filter(location => location.name && matchesEntityName(location.name, query))
+                    : locations;
+                return createToolStructuredContent({
+                    locations: matches,
+                    warningMsg,
+                    note: locations.length === 0
+                        ? "This organization has no locations configured, so the empty result is not a failed lookup."
+                        : query && matches.length === 0
+                            ? `No locations matched "${query}". Retry 'get' with locationName omitted to inspect available names.`
+                            : query && matches.length > 1
+                                ? `Multiple locations matched "${query}". Resolve the intended location before applying a location filter.`
+                                : undefined,
+                });
             }
-            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;
+            case LocationToolAction.CREATE: {
+                if (!args.locationName?.trim()) {
+                    return createToolTextContent("locationName is required for 'create'.");
+                }
+                const created = await createLocation(args.locationName.trim(), args.locationAddress ?? undefined, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    createdLocation: { uuid: created.uuid, success: created.success },
+                    warningMsg: created.warningMsg,
+                    note: `Created "${args.locationName.trim()}". Its timezone has not been set — schedules and reports at a location are interpreted in its timezone, so set one with 'update' (timezoneId) if it is not the org default.`,
+                });
+            }
+            case LocationToolAction.UPDATE: {
+                if (!args.locationUuid) {
+                    return createToolTextContent("locationUuid is required for 'update'.");
+                }
+                const hasChange = !!args.locationName?.trim() ||
+                    !!args.locationAddress?.trim() ||
+                    !!args.postalCode?.trim() ||
+                    !!args.countryCode?.trim() ||
+                    !!args.timezoneId?.trim();
+                if (!hasChange) {
+                    return createToolTextContent("'update' needs at least one of locationName, locationAddress, postalCode, countryCode or timezoneId — all were empty, so there is nothing to change.");
+                }
+                const existing = await findLocation(args.locationUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`No location in this organization has the uuid "${args.locationUuid}". Use action 'get' to see the locations that exist — do not guess a uuid.`);
+                }
+                const { updated, warningMsg } = await updateLocation({
+                    locationUuid: args.locationUuid,
+                    // selectiveUpdateLocation leaves omitted fields alone, so only the
+                    // fields the caller actually set are sent.
+                    name: args.locationName?.trim() || undefined,
+                    address1: args.locationAddress?.trim() || undefined,
+                    postalCode: args.postalCode?.trim() || undefined,
+                    countryCode: args.countryCode?.trim() || undefined,
+                    timezoneId: args.timezoneId?.trim() || undefined,
+                }, requestModifiers, sessionId);
+                const notes = [];
+                if (args.timezoneId?.trim() && args.timezoneId.trim() !== existing.timezone) {
+                    notes.push(`The timezone changed from ${existing.timezone ?? "unset"} to ${args.timezoneId.trim()}. Every schedule and report at "${existing.name ?? args.locationUuid}" is now interpreted in the new zone, which shifts when they take effect.`);
+                }
+                return createToolStructuredContent({
+                    updated,
+                    warningMsg,
+                    note: notes.length > 0 ? notes.join(" ") : undefined,
+                });
+            }
+            case LocationToolAction.DELETE: {
+                if (!args.locationUuid) {
+                    return createToolTextContent("locationUuid is required for 'delete'.");
+                }
+                const existing = await findLocation(args.locationUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`No location in this organization has the uuid "${args.locationUuid}". Use action 'get' to see the locations that exist.`);
+                }
+                if (!args.confirmDelete) {
+                    // Deleting a location is not reversible and cascades to every device
+                    // assigned to it, so never do it on an inferred intent.
+                    return createToolStructuredContent({
+                        locations: [existing],
+                        note: `NOT DELETED — nothing was changed. Deleting the location "${existing.name ?? args.locationUuid}" cannot be undone and ` +
+                            `affects every camera, door and sensor assigned to it, plus its schedules and reports. Confirm with the user ` +
+                            `explicitly, then call this tool again with confirmDelete: true.`,
+                    });
+                }
+                const { deleted, warningMsg } = await deleteLocation(args.locationUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleted,
+                    warningMsg,
+                    note: `Deleted the location "${existing.name ?? args.locationUuid}".`,
+                });
+            }
+            case LocationToolAction.GET_LABELS: {
+                const locationLabels = await getLocationLabels(requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    locationLabels,
+                    note: locationLabels.length === 0
+                        ? "This organization has no location labels defined. 'add-label' creates a label by using it."
+                        : undefined,
+                });
+            }
+            case LocationToolAction.ADD_LABEL:
+            case LocationToolAction.REMOVE_LABEL: {
+                const removing = args.action === LocationToolAction.REMOVE_LABEL;
+                if (!args.locationUuid) {
+                    return createToolTextContent(`locationUuid is required for '${args.action}'.`);
+                }
+                if (!args.label?.trim()) {
+                    return createToolTextContent(`label is required for '${args.action}'.`);
+                }
+                const existing = await findLocation(args.locationUuid, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolTextContent(`No location in this organization has the uuid "${args.locationUuid}". Use action 'get' to see the locations that exist.`);
+                }
+                const label = args.label.trim();
+                const alreadyHas = existing.labels?.includes(label) ?? false;
+                if (removing && !alreadyHas) {
+                    return createToolStructuredContent({
+                        locations: [existing],
+                        note: `Nothing was changed — "${existing.name ?? args.locationUuid}" does not have the label "${label}". Its labels are: ${existing.labels?.length ? existing.labels.join(", ") : "(none)"}.`,
+                    });
+                }
+                if (!removing && alreadyHas) {
+                    return createToolStructuredContent({
+                        locations: [existing],
+                        note: `Nothing was changed — "${existing.name ?? args.locationUuid}" already has the label "${label}".`,
+                    });
+                }
+                const { labelChanged, warningMsg } = removing
+                    ? await removeLocationLabel(args.locationUuid, label, requestModifiers, sessionId)
+                    : await addLocationLabel(args.locationUuid, label, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    labelChanged,
+                    warningMsg,
+                    note: `${removing ? "Removed" : "Added"} the label "${label}" ${removing ? "from" : "to"} "${existing.name ?? args.locationUuid}".`,
+                });
             }
-            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}` };
-            break;
     }
-    return {
-        content: [{ type: "text", text: JSON.stringify(ret) }],
-    };
+    catch (error) {
+        return createToolStructuredContent({
+            error: error instanceof Error ? error.message : "Unknown error",
+        });
+    }
+    return createToolTextContent(`Invalid action. Valid values are: ${Object.values(LocationToolAction).join(", ")}.`);
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
         title: "Locations",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
-        annotations: { readOnlyHint: false, destructiveHint: false },
+        // Previously declared but never passed, so results came back as raw text
+        // and the filtering proxy had nothing to project.
+        outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }

package/dist/tools-console/lost-badge-tool.js

@@ -1,24 +1,9 @@
 import { getLostBadgeResponse } from "../api/lost-badge-tool-api.js";
 import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/lost-badge-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+import { buildLostBadgeToolDescription } from "../types/lost-badge-tool-types.js";
 const TOOL_NAME = "lost-badge-tool";
-const TOOL_DESCRIPTION = `
-Lost / stolen-badge live response for Honeywell OnGuard (Lenel) access. Use for "a lost badge was just used —
-who is it and where did they go?", or to review lost/inactive-badge use over a window.
-
-For each lost/inactive-badge use it returns:
-- cardholderOfRecord (who the badge belongs to — may NOT be who used it) and badgeStatus
-- the door deviceUuid + time, plus clipHint / stillHint for the door footage
-- facesAtDoor: the face(s) captured at the door at that moment — a recognized name, or UNIDENTIFIED (an unknown
-  face on a valid badge is the strongest stolen/shared-badge signal), with a thumbnail
-- sightings: that same face tracked across cameras, ordered in time, ending in lastKnownSighting (last-known location)
-
-Resolve relative times (e.g. "in the last hour") to ISO 8601 first via the timestamp tool.
-
-To present: show the door still/clip (camera-tool image / clips-tool createClip with the hints), the face at the
-door, and the cross-camera track to last-known location. Detection + door evidence are reliable; the face track
-depends on face-recognition coverage, so treat it as investigative, not proof.
-`;
+const TOOL_DESCRIPTION = buildLostBadgeToolDescription("Honeywell OnGuard (Lenel)");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

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

@@ -1,31 +1,15 @@
-import { getSavedVehicles, getVehicleEvents, getVehicleLabels, searchLicensePlates, saveVehicle } from "../api/lpr-tool-api.js";
+import { addVehicleLabel, deleteVehicle, findSavedVehicle, getSavedVehicles, getVehicleEvents, getVehicleLabels, removeVehicleLabel, saveVehicle, searchLicensePlates, } from "../api/lpr-tool-api.js";
 import { LprToolRequestType, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/lpr-tool-types.js";
 import { createToolStructuredContent, createToolTextContent, extractFromToolExtra, } from "../util.js";
 const TOOL_NAME = "lpr-tool";
 const TOOL_DESCRIPTION = `
-This tool interacts with the Rhombus LPR system to retrieve information about license plate recognition events and registered license plates.
+Rhombus LPR (license plate recognition): plate/vehicle events, saved vehicles, vehicle labels, and org-wide plate search. Users say "vehicle", "car" and "license plate" interchangeably — all route here.
 
-**Vs events-tool (camera):** **events-tool** with eventType **camera** returns that camera’s **VOD footage seekpoints** (many activity types on the timeline, including vehicle-related activity when present). **lpr-tool** is for the **LPR product surface**: plate events, **saved vehicles**, **labels**, and plate **search** APIs across the org—use it when the user needs registry, labeling, or org-wide LPR queries, not only “what showed up on this camera’s timeline.”
+**Vs events-tool (camera):** events-tool with eventType camera returns that camera's VOD timeline seekpoints (which include vehicle activity). lpr-tool is the LPR product surface — the plate registry, labeling, and org-wide LPR queries. Use lpr-tool when the user needs plates/vehicles as entities, not just "what showed up on this camera's timeline".
 
-The system's cameras may have LPR enabled, and when it is enabled, it will detect "license plate recognition" events when it sees a license plate
-come into view. However, it is possible that the recognized license is only a partial match, so keep that in mind when using this tool.
-Users will be able to save license plates into the system, and then additionally label them with a name.
+Modes via "requestType": ${LprToolRequestType.GET_VEHICLE_EVENTS}, ${LprToolRequestType.GET_SAVED_VEHICLES}, ${LprToolRequestType.GET_VEHICLE_LABELS}, ${LprToolRequestType.SEARCH_LICENSE_PLATES}, ${LprToolRequestType.SAVE_VEHICLE}, ${LprToolRequestType.UPDATE_VEHICLE}, ${LprToolRequestType.DELETE_VEHICLE}, ${LprToolRequestType.ADD_VEHICLE_LABEL}, ${LprToolRequestType.REMOVE_VEHICLE_LABEL} — usage details, label workflow and defaults are documented on the parameters.
 
-Regarding vehicle labels:  Users in the Rhombus LPR system can assign labels to vehicles.  When a vehicle (license plate) is assigned a label, and then later
-is recognized by a rhombus security camera, it will attach the label to the event and will be available on the events returned from (${LprToolRequestType.GET_SAVED_VEHICLES}).
-
-You should use the location-tool if trying to pair vehicle events to a particular location.  Never use location UUIDs in reports, use names.
-
-As such, if the user is asking anything about a label or labels it would be best practice to first call ${LprToolRequestType.GET_VEHICLE_LABELS} and then ${LprToolRequestType.GET_VEHICLE_EVENTS}
-or ${LprToolRequestType.GET_VEHICLE_EVENTS}.
-
-This tool has 3 modes of operation, determined by the "requestType" parameter:
-- ${LprToolRequestType.GET_VEHICLE_EVENTS}: Retrieves a list of vehicle events that have been detected by the system. Please keep in mind that this has the *potential*
-  to return a lot of data. However, 7 days should be a reasonable time range to start from if the user is not specific.
-- ${LprToolRequestType.GET_SAVED_VEHICLES}: Retrieves a list of saved vehicles that have been saved in the organization.
-- ${LprToolRequestType.GET_VEHICLE_LABELS}: Retrieves a list of vehicle labels that have been saved in the organization.
-
-Its very likely that "vehicle", "car", and "license plates" are used interchangeably. Please keep this in mind.
+A saved vehicle is identified by its PLATE, not a UUID, and the plate itself cannot be edited: correcting a mistyped plate means delete-vehicle then save-vehicle. Deleting a saved vehicle does not delete its past detection events.
 `;
 const TOOL_HANDLER = async (args, _extra) => {
     const responseType = args.requestType;
@@ -65,8 +49,90 @@ const TOOL_HANDLER = async (args, _extra) => {
                         error: "vehicleName and vehicleLicensePlate are required for save-vehicle.",
                     });
                 }
+                // The plate is the key, so saving one that already exists overwrites it.
+                // Say which happened rather than reporting a create either way.
+                const existing = await findSavedVehicle(args.vehicleLicensePlate, requestModifiers, sessionId);
                 const result = await saveVehicle(args.vehicleName, args.vehicleLicensePlate, args.vehicleDescription ?? undefined, requestModifiers, sessionId);
-                return createToolStructuredContent({ saveVehicleResult: result });
+                return createToolStructuredContent({
+                    saveVehicleResult: { success: result.success, licensePlate: result.licensePlate },
+                    warningMsg: result.warningMsg,
+                    note: existing
+                        ? `Plate ${args.vehicleLicensePlate} was already saved as "${existing.name ?? "unnamed"}" and has been OVERWRITTEN with the new name and description, not added a second time.`
+                        : undefined,
+                });
+            }
+            case LprToolRequestType.UPDATE_VEHICLE: {
+                if (!args.vehicleLicensePlate) {
+                    return createToolStructuredContent({
+                        error: "vehicleLicensePlate is required for update-vehicle.",
+                    });
+                }
+                if (!args.vehicleName?.trim() && !args.vehicleDescription?.trim()) {
+                    return createToolStructuredContent({
+                        error: "update-vehicle needs at least one of vehicleName or vehicleDescription — both were empty, so there is nothing to change.",
+                    });
+                }
+                const existing = await findSavedVehicle(args.vehicleLicensePlate, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolStructuredContent({
+                        error: `No saved vehicle has the plate ${args.vehicleLicensePlate}. Use get-saved-vehicles to see the plates that are saved. To save a new one, use save-vehicle.`,
+                    });
+                }
+                // saveVehicle is a whole-record write keyed on the plate, so resend the
+                // fields the caller did not change.
+                const result = await saveVehicle(args.vehicleName?.trim() || existing.name || "", args.vehicleLicensePlate, args.vehicleDescription?.trim() || existing.description || undefined, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    saveVehicleResult: { success: result.success, licensePlate: result.licensePlate },
+                    warningMsg: result.warningMsg,
+                    note: `Updated the saved vehicle for plate ${args.vehicleLicensePlate}. Fields you did not pass were left as they were. The plate itself cannot be changed — delete and re-save to correct one.`,
+                });
+            }
+            case LprToolRequestType.DELETE_VEHICLE: {
+                if (!args.vehicleLicensePlate) {
+                    return createToolStructuredContent({
+                        error: "vehicleLicensePlate is required for delete-vehicle.",
+                    });
+                }
+                const existing = await findSavedVehicle(args.vehicleLicensePlate, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolStructuredContent({
+                        error: `No saved vehicle has the plate ${args.vehicleLicensePlate}, so there is nothing to delete. Use get-saved-vehicles to see the plates that are saved.`,
+                    });
+                }
+                const result = await deleteVehicle(args.vehicleLicensePlate, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleteVehicleResult: { success: result.success, licensePlate: result.licensePlate },
+                    warningMsg: result.warningMsg,
+                    note: `Removed "${existing.name ?? "unnamed"}" (plate ${args.vehicleLicensePlate}) from the saved-vehicle registry, along with its labels. Past detection events for this plate are NOT deleted — they remain in the vehicle event history.`,
+                });
+            }
+            case LprToolRequestType.ADD_VEHICLE_LABEL:
+            case LprToolRequestType.REMOVE_VEHICLE_LABEL: {
+                const removing = responseType === LprToolRequestType.REMOVE_VEHICLE_LABEL;
+                if (!args.vehicleLicensePlate || !args.vehicleLabel?.trim()) {
+                    return createToolStructuredContent({
+                        error: `vehicleLicensePlate and vehicleLabel are both required for ${responseType}.`,
+                    });
+                }
+                const existing = await findSavedVehicle(args.vehicleLicensePlate, requestModifiers, sessionId);
+                if (!existing) {
+                    return createToolStructuredContent({
+                        error: `No saved vehicle has the plate ${args.vehicleLicensePlate}. A label can only be attached to a SAVED vehicle — save it first with save-vehicle.`,
+                    });
+                }
+                const label = args.vehicleLabel.trim();
+                const result = removing
+                    ? await removeVehicleLabel(args.vehicleLicensePlate, label, requestModifiers, sessionId)
+                    : await addVehicleLabel(args.vehicleLicensePlate, label, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    vehicleLabelResult: {
+                        success: result.success,
+                        licensePlate: result.licensePlate,
+                        label: result.label,
+                    },
+                    warningMsg: result.warningMsg,
+                    note: `${removing ? "Removed" : "Added"} the label "${label}" ${removing ? "from" : "to"} plate ${args.vehicleLicensePlate}. Labels flow through to that plate's detection events, so ${removing ? "past events will stop showing" : "past and future events will show"} this label.`,
+                });
             }
         }
     }
@@ -84,6 +150,6 @@ export function createTool(server) {
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
-        annotations: { readOnlyHint: false, destructiveHint: false },
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }

package/dist/tools-console/netbox-access-anomaly-tool.js

@@ -1,26 +1,9 @@
 import { getNetboxAccessAnomalies } from "../api/netbox-access-anomaly-tool-api.js";
 import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/netbox-access-anomaly-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+import { buildAccessAnomalyToolDescription } from "../types/access-anomaly-tool-types.js";
 const TOOL_NAME = "netbox-access-anomaly-tool";
-const TOOL_DESCRIPTION = `
-Scans Lenel S2 NetBox (Honeywell NetBox) access events over a time window and flags anomalous badge activity. Use for
-"find unusual badge activity", "anything suspicious in access this week", or proactive access review.
-
-Runs deterministic rules and returns ranked findings (high severity first):
-- lost_or_inactive_badge: a non-active badge (lost/suspended) was used
-- entry_not_made: access granted but no entry made (possible tailgating)
-- off_hours: entry outside business hours (configurable)
-- impossible_travel: one cardholder at two different areas seconds apart
-- area_novelty: a cardholder's first-ever entry to an area vs their prior history (needs a baseline window)
-
-Each finding includes cardholderName, the rule, severity, datetime, area, the camera deviceUuid, a plain-language
-rationale, and clip/still hints. Resolve relative times (e.g. "this week") to ISO 8601 first via the timestamp tool.
-
-This is a triage aid: present findings grouped by severity, and for the notable ones call the camera-tool
-(requestType "image", cameraUuid = finding.deviceUuid, timestamp = finding.timestampMs) and/or clips-tool
-("createClip" using finding.clipHint) — in PARALLEL — so a human can confirm. Don't assert wrongdoing; surface the
-evidence.
-`;
+const TOOL_DESCRIPTION = buildAccessAnomalyToolDescription("Lenel S2 NetBox (Honeywell NetBox)");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

package/dist/tools-console/netbox-badge-timeline-tool.js

@@ -1,28 +1,9 @@
 import { getNetboxBadgeTimeline } from "../api/netbox-badge-timeline-tool-api.js";
 import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/netbox-badge-timeline-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+import { buildBadgeTimelineToolDescription } from "../types/badge-timeline-tool-types.js";
 const TOOL_NAME = "netbox-badge-timeline-tool";
-const TOOL_DESCRIPTION = `
-Reconstructs one person's movements through a building from their Lenel S2 NetBox (Honeywell NetBox) badge taps.
-Use this for incident reconstruction / "follow the badge" requests, e.g. "reconstruct Eve's movements
-yesterday" or "where did this cardholder go".
-
-Returns the cardholder's badge taps in CHRONOLOGICAL order (oldest first), each with:
-- datetime / timestampMs and the area entered
-- deviceUuid: the camera at that door
-- clipHint (camera + start/end window) and stillHint (camera + timestamp)
-- gapToNextSeconds: time until the next tap (a large gap = unobserved movement between doors)
-plus a "path" array summarizing the areas traversed in order.
-
-Resolve relative times like "yesterday" to ISO 8601 first (use the timestamp tool), then pass
-startTime/endTime. cardholderQuery is a full-text name match; if "ambiguousCardholders" is returned the
-query matched more than one person — ask the user which one before trusting the timeline.
-
-IMPORTANT — to show the movement visually: for each stop (or the key transitions), call the camera-tool
-(requestType "image", cameraUuid = stop.deviceUuid, timestamp = stop.timestampMs) for a still you can see,
-and/or the clips-tool (requestType "createClip", using stop.clipHint) for video. Issue those per-stop
-media calls in PARALLEL, then present the timeline as a chronological narrative.
-`;
+const TOOL_DESCRIPTION = buildBadgeTimelineToolDescription("Lenel S2 NetBox (Honeywell NetBox)");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

package/dist/tools-console/netbox-lost-badge-tool.js

@@ -1,24 +1,9 @@
 import { getNetboxLostBadgeResponse } from "../api/netbox-lost-badge-tool-api.js";
 import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/netbox-lost-badge-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
+import { buildLostBadgeToolDescription } from "../types/lost-badge-tool-types.js";
 const TOOL_NAME = "netbox-lost-badge-tool";
-const TOOL_DESCRIPTION = `
-Lost / stolen-badge live response for Lenel S2 NetBox (Honeywell NetBox) access. Use for "a lost badge was just used —
-who is it and where did they go?", or to review lost/inactive-badge use over a window.
-
-For each lost/inactive-badge use it returns:
-- cardholderOfRecord (who the badge belongs to — may NOT be who used it) and badgeStatus
-- the door deviceUuid + time, plus clipHint / stillHint for the door footage
-- facesAtDoor: the face(s) captured at the door at that moment — a recognized name, or UNIDENTIFIED (an unknown
-  face on a valid badge is the strongest stolen/shared-badge signal), with a thumbnail
-- sightings: that same face tracked across cameras, ordered in time, ending in lastKnownSighting (last-known location)
-
-Resolve relative times (e.g. "in the last hour") to ISO 8601 first via the timestamp tool.
-
-To present: show the door still/clip (camera-tool image / clips-tool createClip with the hints), the face at the
-door, and the cross-camera track to last-known location. Detection + door evidence are reliable; the face track
-depends on face-recognition coverage, so treat it as investigative, not proof.
-`;
+const TOOL_DESCRIPTION = buildLostBadgeToolDescription("Lenel S2 NetBox (Honeywell NetBox)");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

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

@@ -1,36 +1,9 @@
 import { searchNetboxEvents } from "../api/netbox-tool-api.js";
 import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/netbox-tool-types.js";
+import { buildBadgeEventsToolDescription } from "../types/onguard-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "netbox-events-tool";
-const TOOL_DESCRIPTION = `
-Searches Lenel S2 NetBox (Honeywell NetBox) badge / access-control events for the organization. Use this to answer
-"who entered WHERE and WHEN" questions, e.g. "who entered the back office yesterday".
-
-NOTE: an organization may run any combination of Honeywell OnGuard (Lenel), Honeywell Elements (LenelS2
-Elements), and Lenel S2 NetBox badge integrations — each searched by its own sibling tool
-(onguard-events-tool / elements-events-tool / netbox-events-tool), all taking identical arguments and
-returning the same shape. For a general "who badged in / did anyone enter" question you usually do NOT
-know which integration recorded the event, so call ALL THREE sibling tools (in parallel) and combine the
-results — each returns an empty list when its integration isn't configured. Restrict to one vendor only
-when the user explicitly names it.
-
-Each returned event includes:
-- cardholderName: the person's name
-- deviceUuid: the camera that saw the event
-- timestampMs / datetime: when it happened
-- label: e.g. "NetBox: Badge Authorized" (a grant) or an anomaly label
-- badgeStatus, badgeType, areaEntering, areaExiting, entryMade, isAnomaly
-
-Filters (all optional): area, locationUuids, deviceUuids, cardholderQuery, badgeStatus, badgeType,
-anomalyOnly, entryMade, startTime, endTime, limit. Resolve relative times like "yesterday" to ISO 8601
-first (use the timestamp tool), then pass startTime/endTime.
-
-IMPORTANT — to show pictures and video of each person so the user can visually identify them: after this
-returns, for each event (or the most relevant ones) call the camera-tool (requestType "image",
-cameraUuid = the event's deviceUuid, timestamp = the event's time) to get a still you can see, and/or the
-clips-tool (requestType "createClip") with a short window around the timestamp for video. Issue those
-per-event media calls in PARALLEL.
-`;
+const TOOL_DESCRIPTION = buildBadgeEventsToolDescription("Lenel S2 NetBox (Honeywell NetBox)", "NetBox");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

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

@@ -1,36 +1,8 @@
 import { searchOnGuardEvents } from "../api/onguard-tool-api.js";
-import { OUTPUT_SCHEMA, TOOL_ARGS } from "../types/onguard-tool-types.js";
+import { buildBadgeEventsToolDescription, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/onguard-tool-types.js";
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "onguard-events-tool";
-const TOOL_DESCRIPTION = `
-Searches Honeywell OnGuard (Lenel) badge / access-control events for the organization. Use this to answer
-"who entered WHERE and WHEN" questions, e.g. "who entered the back office yesterday".
-
-NOTE: an organization may run any combination of Honeywell OnGuard (Lenel), Honeywell Elements (LenelS2
-Elements), and Lenel S2 NetBox badge integrations — each searched by its own sibling tool
-(onguard-events-tool / elements-events-tool / netbox-events-tool), all taking identical arguments and
-returning the same shape. For a general "who badged in / did anyone enter" question you usually do NOT
-know which integration recorded the event, so call ALL THREE sibling tools (in parallel) and combine the
-results — each returns an empty list when its integration isn't configured. Restrict to one vendor only
-when the user explicitly names it.
-
-Each returned event includes:
-- cardholderName: the person's name
-- deviceUuid: the camera that saw the event
-- timestampMs / datetime: when it happened
-- label: e.g. "OnGuard: Badge Authorized" (a grant) or an anomaly label
-- badgeStatus, badgeType, areaEntering, areaExiting, entryMade, isAnomaly
-
-Filters (all optional): area, locationUuids, deviceUuids, cardholderQuery, badgeStatus, badgeType,
-anomalyOnly, entryMade, startTime, endTime, limit. Resolve relative times like "yesterday" to ISO 8601
-first (use the timestamp tool), then pass startTime/endTime.
-
-IMPORTANT — to show pictures and video of each person so the user can visually identify them: after this
-returns, for each event (or the most relevant ones) call the camera-tool (requestType "image",
-cameraUuid = the event's deviceUuid, timestamp = the event's time) to get a still you can see, and/or the
-clips-tool (requestType "createClip") with a short window around the timestamp for video. Issue those
-per-event media calls in PARALLEL.
-`;
+const TOOL_DESCRIPTION = buildBadgeEventsToolDescription("Honeywell OnGuard (Lenel)", "OnGuard");
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
     try {

package/dist/tools-console/person-tracking-tool.js

@@ -20,11 +20,11 @@ Returns:
 - path (camera sequence) and lastKnownSighting (last-known location).
 - note: set when no badge tap was found, or no re-id embedding existed on the door camera.
 
-Resolve relative times like "yesterday" to ISO 8601 first (use the timestamp tool), then pass
+Resolve relative times like "yesterday" to ISO 8601 first (use time-tool), then pass
 startTime/endTime. Re-id depends on human-detection coverage, so treat the track as investigative, not proof.
 
 IMPORTANT — to show the movement visually: for each sighting (or the key transitions), call the camera-tool
-(requestType "image", cameraUuid = sighting.deviceUuid, timestamp = sighting.timestampMs) for a still, and/or
+(requestType "image", cameraUuid = sighting.deviceUuid, timestampISO = the sighting's time as ISO 8601 — convert sighting.timestampMs via time-conversion-tool) for a still, and/or
 the clips-tool (requestType "createClip", using sighting.clipHint) for video. Issue those per-sighting media
 calls in PARALLEL, then present the track as a chronological narrative.
 `;

package/dist/tools-console/policy-alerts-tool.js

@@ -3,35 +3,10 @@ import { ApiPayloadSchema, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/policy-ale
 import { extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "policy-alerts-tool";
 const TOOL_DESCRIPTION = `
-Retrieves Rhombus policy alerts. Policy alerts in the Rhombus system are generated based on user-defined alert
-policies configured in the Rhombus Console. These policies trigger alerts when specific events occur, such as:
-* AI & Computer Vision Events: Based on intelligent video analytics for motion, people, vehicles, facial recognition,
-  license plate recognition, or unusual behavior.
-* Device Status Changes: Like camera disconnections or sensor low battery.
-* Physical or Visual Tamper: Detection of physical movement of a device or obstruction of a camera's field of view.
-* Access Control Events: Such as unauthorized access attempts in restricted areas.
+Retrieves Rhombus policy alerts — alerts generated by user-defined alert policies when configured events occur: AI/computer-vision events (motion, people, vehicles, faces, license plates, unusual behavior), device status changes (disconnection, low battery), physical/visual tamper, and access-control events. Alerts are NOT the same as notifications (only some alerts notify, per user settings). Can also report which alert labels have been seen. Supports filtering by existing/expiring, time range, device UUIDs or location UUIDs — pagination and per-queryType requirements are documented on the parameters.
 
-Alerts are generated on triggers, but are NOT the same as notifications. Only certain alerts generate notifications based on user settings.
-
-Can inquire about labels that have been seen.
-
-Please note, this is not an exhaustive list, and there may be other types of triggers or events that generate
-policy alerts within the Rhombus system.
-
-This tool allows you to filter existing alerts by existing/expiring, a specific time range (before or after a timestamp in ISO 8601 format),
-by a list of device UUIDs, or by a list of location UUIDs.
-You can also specify the maximum number of results to return.
-The output is provided in JSON format.
-
-**Pagination**: Results are paginated and have a maximum page size. If the response includes a \`lastEvaluatedKey\` (for queryType "expiringSoon") or both \`lastTimestampISO\` and \`lastUuid\` (for queryTypes "existing" and "alert-groups"), more results are available. Pass these values back in the next call using the corresponding input parameters (lastEvaluatedKey, or lastTimestampISO and lastUuid) to retrieve the next page. Repeat until the response no longer includes these fields.
-
-IMPORTANT: The "unhealthy-devices" queryType returns historical alert notifications that were triggered for device health issues.
-It does NOT return live/real-time device connection status. If no device health alert policies are configured, or alerts were
-dismissed, this may return empty even when devices are offline.
-
-**To check which devices are currently online/offline, use the get-entity-tool instead.** The get-entity-tool returns the
-current state of all devices including their live connection status (the "connected" field). Request all entity types
-(CAMERA, DOORBELL_CAMERA, BADGE_READER, etc.) and check the "connected" field on each device to determine which are offline.`;
+IMPORTANT: queryType "unhealthy-devices" returns HISTORICAL device-health alert notifications, not live status — it can be empty while devices are offline. To check which devices are currently online/offline, use get-entity-tool instead (filterBy on its "connected" field).
+`;
 const TOOL_HANDLER = async (args, extra) => {
     const payload = ApiPayloadSchema.parse(args);
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
@@ -75,6 +50,7 @@ export function createTool(server) {
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
         outputSchema: OUTPUT_SCHEMA.shape,
-        annotations: { readOnlyHint: false, destructiveHint: false },
+        // `dismiss` cannot be undone, which is what destructiveHint is for.
+        annotations: { readOnlyHint: false, destructiveHint: true },
     }, TOOL_HANDLER);
 }