rhombus-node-mcp 0.1.56 → 0.1.57

package/dist/types/faces-tools-types.js

@@ -10,6 +10,12 @@ export var RequestType;
     RequestType["SEARCH_SIMILAR_FACES"] = "search-similar-faces";
     RequestType["GET_FACE_MATCHMAKERS"] = "get-face-matchmakers";
     RequestType["GET_FACE_EVENTS_BY_PERSON"] = "get-face-events-by-person";
+    RequestType["CREATE_PERSON"] = "create-person";
+    RequestType["UPDATE_PERSON"] = "update-person";
+    RequestType["DELETE_PERSON"] = "delete-person";
+    RequestType["ADD_PERSON_LABEL"] = "add-person-label";
+    RequestType["REMOVE_PERSON_LABEL"] = "remove-person-label";
+    RequestType["DELETE_FACE_MATCHMAKER"] = "delete-face-matchmaker";
 })(RequestType || (RequestType = {}));
 export const GetRegisteredFacesArgsSchema = z.object({
     requestType: z.literal(RequestType.GET_REGISTERED_FACES),
@@ -88,13 +94,59 @@ export const GetFaceEventsArgs = z.object({
         .describe("Search criteria for filtering face events. Only applies to tool calls with requestType 'get-face-events'."),
 });
 export const TOOL_ARGS = {
-    requestType: z.nativeEnum(RequestType),
-    faceEventFilter: GetFaceEventsArgs,
+    requestType: z.nativeEnum(RequestType).describe(`Which face-recognition request to run.
+
+"get-face-events" — face sightings; use it for reporting on who was seen by the camera system.
+- **Automatic name resolution:** faceNames accepts partial or first-name-only names (e.g. "Brandon", "Omar"); the tool looks up the registered-faces directory and resolves them to exact names and person UUIDs before searching. The response's "resolvedNames" field shows what each queried name matched (null = no match).
+- Filter with faceNames, hasEmbedding, hasName, labels, locationUuids, personUuids, and a time range via searchFilter.timestampFilter.rangeStart / rangeEnd, which are ISO 8601 strings WITH a UTC offset (e.g. "2026-08-03T00:00:00-07:00") — not epoch milliseconds.
+- **For "who was seen" questions, set searchFilter.hasName to true.** Unnamed detections cannot answer a who-question and they consume the page budget: an unfiltered page is typically ~85% nameless, so the named people you need get pushed onto later pages.
+- **Read the faceEventSummary field in the response.** It lists every distinct identified person on the page with their event count and first/last sighting, already deduplicated. Enumerate people from it rather than by scanning getFaceEventsResponse by hand, and page until morePagesAvailable is false before saying who was or wasn't seen.
+- For all face events at a location, pass only the location UUID in searchFilter and NO device UUIDs (searchFilter.deviceUuids), so the API returns every face detected there. If that location has no face events the tool falls back to an org-wide search and says so in the "note" field — read it before attributing results to the requested location.
+- When the user asks about a specific person at a location (e.g. "Jane Doe at Main Office"), call get-registered-faces first, find the best match, then call get-face-events with that precise name — this request expects names exactly as stored.
+
+"get-registered-faces" — every person (registered face) known to the org, each with a "labels" array showing the label groups they belong to. Returns ALL people regardless of any timestamp filter.
+
+"get-person-labels" — a mapping of person UUIDs to their assigned labels across the org. Use it to discover what label groups exist; for a group question ("was anyone from Engineering seen today?") get the labels first, then query face events filtered by those personUuids or labels.`),
+    faceEventFilter: GetFaceEventsArgs.partial().nullish().describe("For get-face-events, put pageRequest and searchFilter inside this object: " +
+        "{pageRequest: {lastEvaluatedKey: null, maxPageSize: 200}, searchFilter: {...}}. " +
+        "Omit or pass null for get-registered-faces and other requests that do not search events."),
+    searchFilter: GetFaceEventsArgs.shape.searchFilter.nullish().describe("Compatibility alias for faceEventFilter.searchFilter. Prefer nesting searchFilter " +
+        "inside faceEventFilter; leave this null when using the nested form. " +
+        "If both filters are provided, they must be identical."),
+    // pageRequest and searchFilter belong inside faceEventFilter. Everything
+    // below is a top-level sibling — nesting these under faceEventFilter is the
+    // most common way this tool gets called wrong and costs a rejected round trip.
     timeZone: z
         .string()
         .describe("The timezone for formatting timestamps which should come from the location of the camera for the face event. This is necessary for the tool to produce accurate formatted timestamps."),
     faceEventUuid: z.string().nullable().describe("UUID of a face event to search similar faces from. Required for 'search-similar-faces'."),
-    personUuid: z.string().nullable().describe("UUID of a person to get face events for. Required for 'get-face-events-by-person'."),
+    personUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of a person. Required for 'get-face-events-by-person', 'update-person', 'delete-person', 'add-person-label' and 'remove-person-label'. Get it from 'get-registered-faces' — do not guess one, because acting on the wrong person's biometric record is not visible in the response."),
+    personName: z
+        .string()
+        .nullable()
+        .describe("A person's name. Required for 'create-person'; for 'update-person' it is the new name (omit to leave it unchanged)."),
+    personEmail: z
+        .string()
+        .nullable()
+        .describe("A person's email address. Optional for 'update-person'; omit to leave it unchanged. " +
+        "CAVEAT: the Rhombus API never returns a person's email on any read path (verified " +
+        "2026-08-05), so a stored email cannot be displayed or verified afterwards — tell the " +
+        "user that if they ask to see it."),
+    personLabel: z
+        .string()
+        .nullable()
+        .describe("A single person label. Required for 'add-person-label' and 'remove-person-label'."),
+    faceId: z
+        .string()
+        .nullable()
+        .describe("The id of ONE enrolled face image (a 'face matchmaker'). Required for 'delete-face-matchmaker'. Get it from 'get-face-matchmakers'. A person can have several enrolled faces; deleting one leaves the person and their other faces in place."),
+    confirmDelete: z
+        .boolean()
+        .nullable()
+        .describe("Required to be true for 'delete-person' and 'delete-face-matchmaker'. Both destroy enrolled biometric data and cannot be undone — re-enrolling needs new photos. They refuse without explicit confirmation from the user."),
     includeFields: INCLUDE_FIELDS_ARG,
     filterBy: FILTER_BY_ARG,
 };
@@ -143,6 +195,9 @@ export const OUTPUT_SCHEMA = z.object({
         .optional(z.array(z.object({
         createdOn: z.optional(z.number()),
         name: z.optional(z.string()),
+        email: z
+            .optional(z.string())
+            .describe("Currently always absent — api2 does not serialize Person.email on any read path (verified 2026-08-05). Mapped so it appears automatically if that changes."),
         orgUuid: z.optional(z.string()),
         updatedOn: z.optional(z.number()),
         uuid: z.optional(z.string()),
@@ -174,6 +229,54 @@ export const OUTPUT_SCHEMA = z.object({
         eventTimestamp: z.string().optional(),
         deviceUuid: z.string().optional(),
     })).optional().describe("Face events for a specific person"),
+    faceEventSummary: z
+        .optional(z.object({
+        totalEventsThisPage: z.number().describe("How many face events this page contains."),
+        namedEvents: z.number().describe("How many of them resolved to a registered person."),
+        unnamedEvents: z
+            .number()
+            .describe("How many were unrecognized faces. These cannot answer a 'who' question."),
+        identifiedPeople: z
+            .array(z.object({
+            name: z.string(),
+            eventCount: z.number(),
+            firstSeen: z.string().describe("Human-readable timestamp of their earliest sighting on this page."),
+            lastSeen: z.string().describe("Human-readable timestamp of their latest sighting on this page."),
+        }))
+            .describe("Every DISTINCT identified person on this page, most-seen first. This is the complete roster for this page — report all of these names, not a sample."),
+        morePagesAvailable: z
+            .boolean()
+            .describe("True when lastEvaluatedKey is set. More people may appear on later pages; do not state who was or wasn't seen until this is false."),
+    }))
+        .describe("Pre-computed roster of distinct people on this page of face events. Enumerate people from here instead of deduplicating getFaceEventsResponse by hand."),
     lastEvaluatedKey: z.string().optional().describe("For paginated requests, this is the returned last evaluated key that can be passed back in on the next request to get the next page of results"),
+    created: z
+        .object({ success: z.boolean().optional(), uuid: z.string().optional() })
+        .optional()
+        .describe("Result of 'create-person'."),
+    updated: z
+        .object({
+        success: z.boolean().optional(),
+        uuid: z.string().optional(),
+        label: z.string().optional(),
+    })
+        .optional()
+        .describe("Result of 'update-person' or a person-label change."),
+    deleted: z
+        .object({
+        success: z.boolean().optional(),
+        uuid: z.string().optional(),
+        faceId: z.string().optional(),
+    })
+        .optional()
+        .describe("Result of 'delete-person' or 'delete-face-matchmaker'."),
+    warningMsg: z
+        .string()
+        .optional()
+        .describe("A warning from the Rhombus API — the call succeeded, but with a caveat."),
+    note: z
+        .string()
+        .optional()
+        .describe("Diagnostic note about why a result set may be empty, incomplete, or scoped differently than requested. Read it before attributing results to the filters you asked for."),
     error: z.optional(z.string()),
 });

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

@@ -1,28 +1,92 @@
 import { z } from "zod";
-import { createUuidSchema } from "../types.js";
 import DeviceType from "./deviceType.js";
 import { TempUnit } from "../utils/temp.js";
-const filterByObjectSchema = z.object({
-    locationUuids: z
-        .array(createUuidSchema())
-        .nullish()
-        .describe("The UUIDs of the locations to filter by. Set to null or an empty array to not filter by location."),
-});
 export const TOOL_ARGS = {
     entityTypes: z
         .array(z.nativeEnum(DeviceType).describe("The entity type to retreive"))
         .describe("What type of entities to retrieve."),
-    filterBy: z
-        .union([filterByObjectSchema, z.null()])
-        .optional()
-        .transform((v) => v ?? { locationUuids: null })
-        .describe("Additional filters that can be applied to the result. Omit or pass null for no filtering."),
+    detail: z
+        .enum(["core", "full"])
+        .nullish()
+        .transform((v) => v ?? "core")
+        .describe('Level of per-device detail. "core" (default) returns each device\'s key fields: uuid, name, connection/health status, location, camera associations, temperature, door capabilities. "full" returns every field (model, firmware, serial, network info, ...) — when describing a single device, combine it with the filterBy output filter (e.g. [{field:"name", op:"contains", value:"..."}]) to avoid a huge response.'),
     timeZone: z
         .string()
         .describe("The timezone for formatting timestamps. This is necessary for the tool to produce accurate formatted timestamps."),
     tempUnit: z
         .nativeEnum(TempUnit)
         .nullable()
+        .default(null)
         .describe("The unit of temperature to return, if applicable. Default is Celsius."),
 };
 const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+// ---------------------------------------------------------------------------
+// Output schema — drives the filtering proxy's auto-generated catalog of
+// available includeFields / filterBy paths (unbilled: it lands on the param
+// description). Fields mirror what "core" detail actually returns per type.
+// ---------------------------------------------------------------------------
+const ConnectedDeviceSchema = z.object({
+    uuid: z.string().optional(),
+    name: z.string().optional(),
+    connected: z
+        .boolean()
+        .optional()
+        .describe("True = online, false = offline. Filter on this for offline/online questions."),
+    connectionStatus: z
+        .string()
+        .optional()
+        .describe('Raw platform status: GREEN, YELLOW, ORANGE or RED (RED = disconnected).'),
+    healthStatus: z.string().optional(),
+    healthStatusDetails: z.string().optional(),
+    locationUuid: z.string().optional(),
+    floorNumber: z.number().optional(),
+    policyUuid: z.string().optional(),
+});
+const ClimateSensorSchema = ConnectedDeviceSchema.extend({
+    // NUMBER, not a formatted string: the api layer converts the upstream
+    // `temperatureCelcius` with tempFunc() and emits the raw value in whatever
+    // unit `tempUnit` asked for. Declaring it a string made the SDK reject every
+    // environmental-sensor call with "-32602 Output validation error" — the
+    // proxy's deepOptionalizeSchema relaxes required-ness, never scalar types.
+    temperature: z
+        .number()
+        .optional()
+        .describe("Temperature in the unit requested via the tempUnit arg (Celsius by default)."),
+    humidity: z.number().optional(),
+    batteryStatus: z.string().optional(),
+});
+const AccessControlledDoorSchema = z.object({
+    uuid: z.string().optional(),
+    name: z.string().optional(),
+    locationUuid: z.string().optional(),
+    policyUuid: z.string().optional(),
+    remoteUnlockEnabled: z.boolean().optional(),
+    geofenceEnabled: z.boolean().optional(),
+    associatedCameras: z.array(z.string()).optional(),
+});
+export const OUTPUT_SCHEMA = z.object({
+    cameras: z.array(ConnectedDeviceSchema).optional(),
+    camerasCount: z.number().optional(),
+    doorbellCameras: z.array(ConnectedDeviceSchema).optional(),
+    doorbellCamerasCount: z.number().optional(),
+    badgeReaders: z.array(ConnectedDeviceSchema).optional(),
+    badgeReadersCount: z.number().optional(),
+    accessControlledDoors: z.array(AccessControlledDoorSchema).optional(),
+    accessControlledDoorsCount: z.number().optional(),
+    audioGateways: z.array(ConnectedDeviceSchema).optional(),
+    audioGatewaysCount: z.number().optional(),
+    doorStates: z.array(ConnectedDeviceSchema).optional(),
+    doorStatesCount: z.number().optional(),
+    climateStates: z.array(ClimateSensorSchema).optional(),
+    climateStatesCount: z.number().optional(),
+    occupancySensorStates: z.array(ConnectedDeviceSchema).optional(),
+    occupancySensorStatesCount: z.number().optional(),
+    buttonStates: z.array(ConnectedDeviceSchema).optional(),
+    buttonStatesCount: z.number().optional(),
+    keypadStates: z.array(ConnectedDeviceSchema).optional(),
+    keypadStatesCount: z.number().optional(),
+    minimalEnvironmentalGatewayStates: z.array(ConnectedDeviceSchema).optional(),
+    minimalEnvironmentalGatewayStatesCount: z.number().optional(),
+    filterByWarnings: z.array(z.string()).optional(),
+    error: z.string().optional(),
+});

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

@@ -5,7 +5,23 @@ export var GuestManagementRequestType;
     GuestManagementRequestType["GET_ALL_GUESTS"] = "get-all-guests";
     GuestManagementRequestType["GET_ACTIVITY_LOGS"] = "get-activity-logs";
     GuestManagementRequestType["GET_ACTIVITIES_FOR_LOCATION"] = "get-activities-for-location";
+    GuestManagementRequestType["CREATE_GUEST"] = "create-guest";
+    GuestManagementRequestType["DELETE_GUEST"] = "delete-guest";
+    GuestManagementRequestType["GET_GUEST_PASSES"] = "get-guest-passes";
+    GuestManagementRequestType["EXPIRE_GUEST_PASS"] = "expire-guest-pass";
+    GuestManagementRequestType["SUSPEND_GUEST_PASS"] = "suspend-guest-pass";
+    GuestManagementRequestType["UNSUSPEND_GUEST_PASS"] = "unsuspend-guest-pass";
+    GuestManagementRequestType["DELETE_GUEST_PASS"] = "delete-guest-pass";
 })(GuestManagementRequestType || (GuestManagementRequestType = {}));
+/** api2's `GuestTypeEnum`. Anything outside this list is rejected upstream. */
+export const GUEST_TYPES = [
+    "CONTRACTOR",
+    "INTERVIEWER",
+    "GENERAL_VISITOR",
+    "UNPLANNED_VISITOR",
+    "PARTNER",
+    "MEETINGS",
+];
 export const TOOL_ARGS = {
     requestType: z
         .nativeEnum(GuestManagementRequestType)
@@ -13,7 +29,47 @@ export const TOOL_ARGS = {
     locationUuid: z
         .string()
         .nullable()
-        .describe("Location UUID. Required for 'get-activities-for-location'."),
+        .describe("Location UUID. Required for 'get-activities-for-location' and 'create-guest'."),
+    guestFirstName: z
+        .string()
+        .nullable()
+        .describe("The guest's first name. Required for 'create-guest'."),
+    guestLastName: z
+        .string()
+        .nullable()
+        .describe("The guest's last name. Required for 'create-guest'."),
+    guestEmail: z
+        .string()
+        .nullable()
+        .describe("The guest's email address. Required for 'create-guest' and 'delete-guest'. A guest is identified by email, not a UUID, so this has to be exact — read it back to the user before creating, since an invitation may be sent to it."),
+    guestCompanyName: z
+        .string()
+        .nullable()
+        .describe("The guest's company. Optional for 'create-guest'."),
+    guestType: z
+        .enum(GUEST_TYPES)
+        .nullable()
+        .describe(`The kind of visit. Optional for 'create-guest'; defaults to GENERAL_VISITOR. One of: ${GUEST_TYPES.join(", ")}.`),
+    hostUserUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of the Rhombus user hosting the guest. Optional for 'create-guest'. Resolve the host's name with user-tool — do not guess."),
+    accessStartTimeMs: z
+        .number()
+        .nullable()
+        .describe("When the guest's access begins (ms since epoch). Optional for 'create-guest'."),
+    accessEndTimeMs: z
+        .number()
+        .nullable()
+        .describe("When the guest's access ends (ms since epoch). Optional for 'create-guest', but a guest with no end time keeps access indefinitely — say so if it is left unset."),
+    guestPassUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of a guest pass. Required for 'expire-guest-pass', 'suspend-guest-pass', 'unsuspend-guest-pass' and 'delete-guest-pass'. Get it from 'get-guest-passes' — do not guess one."),
+    confirmDelete: z
+        .boolean()
+        .nullable()
+        .describe("Required to be true for 'delete-guest' and 'delete-guest-pass'. Both are irreversible; for a pass, 'expire-guest-pass' ends access while keeping the record and history."),
     startTimeMs: z
         .number()
         .nullable()
@@ -53,5 +109,51 @@ export const OUTPUT_SCHEMA = z.object({
         .array(GuestActivitySchema)
         .optional()
         .describe("List of guest activity log entries"),
+    guestPasses: z
+        .array(z.object({
+        uuid: z.string().optional(),
+        locationUuid: z.string().optional(),
+        lifecycle: z
+            .string()
+            .optional()
+            .describe("ACTIVE, SUSPENDED, EXPIRED or ARCHIVED."),
+        note: z.string().optional(),
+        passStartTimeMs: z.number().optional(),
+        principalType: z.string().optional(),
+    }))
+        .optional()
+        .describe("Guest passes in the organization."),
+    created: z
+        .object({ success: z.boolean().optional(), email: z.string().optional() })
+        .optional()
+        .describe("Result of 'create-guest'."),
+    deleted: z
+        .object({
+        success: z.boolean().optional(),
+        email: z.string().optional(),
+        uuid: z.string().optional(),
+    })
+        .optional()
+        .describe("Result of 'delete-guest' or 'delete-guest-pass'."),
+    guestPassChange: z
+        .object({
+        success: z.boolean().optional(),
+        uuid: z.string().optional(),
+        action: z.string().optional(),
+    })
+        .optional()
+        .describe("Result of a guest pass state change."),
+    lastEvaluatedKey: z
+        .string()
+        .optional()
+        .describe("Pagination cursor — more guest passes exist when this is set."),
+    note: z
+        .string()
+        .optional()
+        .describe("A caveat about this result that the user needs to be told."),
+    warningMsg: z
+        .string()
+        .optional()
+        .describe("A warning from the Rhombus API — the call succeeded, but with a caveat."),
     error: z.string().optional().describe("An error message if the request failed."),
 });

package/dist/types/location-tool-types.js

@@ -1,20 +1,106 @@
 import { z } from "zod";
+export var LocationToolAction;
+(function (LocationToolAction) {
+    LocationToolAction["GET"] = "get";
+    LocationToolAction["CREATE"] = "create";
+    LocationToolAction["UPDATE"] = "update";
+    LocationToolAction["DELETE"] = "delete";
+    LocationToolAction["GET_LABELS"] = "get-labels";
+    LocationToolAction["ADD_LABEL"] = "add-label";
+    LocationToolAction["REMOVE_LABEL"] = "remove-label";
+})(LocationToolAction || (LocationToolAction = {}));
 export const TOOL_ARGS = {
-    action: z.enum(["get", "update", "create", "get-labels"]),
-    locationUpdate: z
-        .object({
-        uuid: z.string(),
-        name: z.string(),
-    })
-        .nullable(),
-    locationName: z.string().nullable().describe("Name for the new location. Required for 'create'."),
-    locationAddress: z.string().nullable().describe("Address for the location. Optional for 'create' and 'update'."),
-    locationUuid: z.string().nullable().describe("UUID of the location. Required for 'update'."),
+    action: z
+        .nativeEnum(LocationToolAction)
+        .describe("'get' = list all locations with their address, timezone and labels; " +
+        "'create' = create a location (requires locationName); " +
+        "'update' = change a location's name, address, timezone and/or labels (requires locationUuid); " +
+        "'delete' = delete a location (requires locationUuid); " +
+        "'get-labels' = list all location labels used in the org; " +
+        "'add-label' / 'remove-label' = attach or detach one label on one location (requires locationUuid and label)."),
+    locationUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of the location. Required for 'update', 'delete', 'add-label' and 'remove-label'. Get it from 'get' — do not guess one."),
+    locationName: z
+        .string()
+        .nullable()
+        .describe("For 'get', optional name search ignoring case, spaces and punctuation (e.g. 'iceblocks' finds 'Ice Blocks - Headquarters'); omit to list all locations. Required for 'create'; for 'update' it is the new name (omit to leave the name unchanged)."),
+    locationAddress: z
+        .string()
+        .nullable()
+        .describe("Street address for the location. Optional for 'create' and 'update'. For 'update', omit to leave the address unchanged."),
+    postalCode: z
+        .string()
+        .nullable()
+        .describe("Postal/ZIP code. Optional for 'update'; omit to leave it unchanged."),
+    countryCode: z
+        .string()
+        .nullable()
+        .describe("Two-letter ISO country code, e.g. \"US\". Optional for 'update'; omit to leave it unchanged."),
+    timezoneId: z
+        .string()
+        .nullable()
+        .describe('IANA timezone id for the location, e.g. "America/Los_Angeles". Optional for \'update\'; omit to leave it unchanged. ' +
+        "A location's timezone decides how its schedules and reports are interpreted, so changing it shifts every schedule at that location — say so before doing it."),
+    label: z
+        .string()
+        .nullable()
+        .describe("A single label name. Required for 'add-label' and 'remove-label'."),
+    confirmDelete: z
+        .boolean()
+        .nullable()
+        .describe("Only for 'delete'. Deleting a location is not reversible and affects every device assigned to it, so 'delete' refuses by default. Set true to delete anyway, after the user has confirmed."),
 };
 const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+const LOCATION_OUTPUT = z.object({
+    uuid: z.string().optional(),
+    name: z.string().optional(),
+    address: z
+        .string()
+        .optional()
+        .describe("The address parts joined for reading. Prefer this over reassembling them."),
+    address1: z.string().optional(),
+    address2: z.string().optional(),
+    postalCode: z.string().optional(),
+    countryCode: z.string().optional(),
+    timezone: z
+        .string()
+        .optional()
+        .describe("IANA timezone id. Schedules and reports at this location are interpreted in it."),
+    labels: z.array(z.string()).optional(),
+    latitude: z.number().optional(),
+    longitude: z.number().optional(),
+    policyUuid: z.string().optional(),
+});
 export const OUTPUT_SCHEMA = z.object({
-    createdLocation: z.object({ uuid: z.string().optional(), success: z.boolean().optional() }).optional(),
-    updatedLocation: z.object({ success: z.boolean().optional() }).optional(),
-    locationLabels: z.array(z.object({ uuid: z.string().optional(), name: z.string().optional() })).optional(),
-    error: z.string().optional(),
+    locations: z.array(LOCATION_OUTPUT).optional().describe("All locations in the organization."),
+    createdLocation: z
+        .object({ uuid: z.string().optional(), success: z.boolean().optional() })
+        .optional(),
+    updated: z
+        .object({ success: z.boolean().optional(), locationUuid: z.string().optional() })
+        .optional(),
+    deleted: z
+        .object({ success: z.boolean().optional(), locationUuid: z.string().optional() })
+        .optional(),
+    labelChanged: z
+        .object({
+        success: z.boolean().optional(),
+        locationUuid: z.string().optional(),
+        label: z.string().optional(),
+    })
+        .optional(),
+    locationLabels: z
+        .array(z.object({ uuid: z.string().optional(), name: z.string().optional() }))
+        .optional(),
+    note: z
+        .string()
+        .optional()
+        .describe("A caveat about this result that the user needs to be told."),
+    warningMsg: z
+        .string()
+        .optional()
+        .describe("A warning from the Rhombus API — the call succeeded, but with a caveat."),
+    error: z.string().optional().describe("An error message if the request failed."),
 });

package/dist/types/lost-badge-tool-types.js

@@ -1,6 +1,20 @@
 import { z } from "zod";
 import { createUuidSchema } from "../types.js";
 import { ISOTimestampFormatDescription } from "../utils/timestampInput.js";
+/**
+ * Description shared by the three lost-badge tools (OnGuard / Elements /
+ * NetBox), which differ only in vendor. Kept short because tool descriptions
+ * are billed on every LLM call even while deferred, and this text is
+ * duplicated across all three siblings; presentation guidance and the
+ * reliability caveat live on the arguments below. See PERF_MASTER_PLAN P2 #4a.
+ */
+export function buildLostBadgeToolDescription(vendor) {
+    return `
+Lost / stolen-badge live response for ${vendor} 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 with clip/still hints, facesAtDoor (the face captured at the door — a recognized name, or UNIDENTIFIED, which on a valid badge is the strongest stolen/shared-badge signal), and sightings of that same face tracked across cameras in time order, ending in lastKnownSighting.
+`;
+}
 export const TOOL_ARGS = {
     area: z.string().nullable().describe("Optional: restrict to events entering this area (full-text)."),
     locationUuids: z.array(createUuidSchema()).nullable().describe("Optional: restrict to these location UUIDs."),
@@ -9,7 +23,8 @@ export const TOOL_ARGS = {
         .string()
         .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
         .nullable()
-        .describe("Start of the window to scan for lost/inactive-badge use (inclusive). " + ISOTimestampFormatDescription),
+        .describe('Start of the window to scan for lost/inactive-badge use (inclusive). Resolve relative phrasing like "in the last hour" with time-tool first, then pass ISO 8601 here. ' +
+        ISOTimestampFormatDescription),
     endTime: z
         .string()
         .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
@@ -18,7 +33,7 @@ export const TOOL_ARGS = {
     faceWindowSeconds: z
         .number()
         .nullable()
-        .describe("± seconds around each badge event to look for the face at the door (default 30)."),
+        .describe("± seconds around each badge event to look for the face at the door (default 30). To present the result: show the door still/clip (camera-tool requestType \"image\" / clips-tool \"createClip\" with the returned hints), the face at the door, and the cross-camera track to the last-known location. Detection and door evidence are reliable; the face track depends on face-recognition coverage, so treat it as investigative, not proof."),
     limit: z.number().nullable().describe("Max badge events to scan in the window (default 50)."),
     timeZone: z
         .string()

package/dist/types/lpr-tool-types.js

@@ -8,6 +8,10 @@ export var LprToolRequestType;
     LprToolRequestType["GET_VEHICLE_LABELS"] = "get-vehicle-labels";
     LprToolRequestType["SEARCH_LICENSE_PLATES"] = "search-license-plates";
     LprToolRequestType["SAVE_VEHICLE"] = "save-vehicle";
+    LprToolRequestType["UPDATE_VEHICLE"] = "update-vehicle";
+    LprToolRequestType["DELETE_VEHICLE"] = "delete-vehicle";
+    LprToolRequestType["ADD_VEHICLE_LABEL"] = "add-vehicle-label";
+    LprToolRequestType["REMOVE_VEHICLE_LABEL"] = "remove-vehicle-label";
 })(LprToolRequestType || (LprToolRequestType = {}));
 export const VehicleEventsArgs = z.object({
     deviceUuidFilter: z
@@ -33,7 +37,7 @@ export const VehicleEventsArgs = z.object({
         message: "Invalid datetime string. Expected ISO 8601 format.",
         offset: true,
     })
-        .describe("The end of the time range (inclusive) for filtering license plate events." +
+        .describe("The start of the time range (inclusive) for filtering license plate events." +
         ISOTimestampFormatDescription),
     endTime: z
         .string()
@@ -41,21 +45,38 @@ export const VehicleEventsArgs = z.object({
         message: "Invalid datetime string. Expected ISO 8601 format.",
         offset: true,
     })
-        .describe("The start of the time range (inclusive) for filtering license plate events." +
+        .describe("The end of the time range (inclusive) for filtering license plate events." +
         ISOTimestampFormatDescription),
 });
 export const TOOL_ARGS = {
     requestType: z
         .nativeEnum(LprToolRequestType)
-        .describe("Org LPR operation (vehicle events, saved vehicles, labels, plate search, save vehicle). Per-camera VOD timeline seekpoints use events-tool (eventType camera)."),
-    vehicleEventsArgs: VehicleEventsArgs.nullable().describe("Only necessary for requestType 'get-vehicle-events'"),
+        .describe(`Org LPR operation (vehicle events, saved vehicles, labels, plate search, save vehicle). Per-camera VOD timeline seekpoints use events-tool (eventType camera).
+- get-vehicle-events: detected plate events. Recognition can be a PARTIAL match — keep that in mind when asserting a plate was seen. When a saved vehicle has a label, its events carry that label.
+- get-saved-vehicles: plates users saved (optionally named/labelled).
+- get-vehicle-labels: the org's vehicle labels. For any label question, best practice is get-vehicle-labels first, then get-vehicle-events.
+Pair events to locations by NAME via location-tool — never show location UUIDs in responses or reports.`),
+    vehicleEventsArgs: VehicleEventsArgs.nullable().describe("Only necessary for requestType 'get-vehicle-events'. Can return a lot of data — if the user gives no time range, 7 days is a reasonable default."),
     timeZone: z
         .string()
         .describe("The timezone for formatting timestamps which should come from the location of the device for the LPR event, or the user's timezone. This is necessary for the tool to produce accurate formatted timestamps."),
     licensePlateQuery: z.string().nullable().describe("License plate number to search. Required for 'search-license-plates'."),
-    vehicleName: z.string().nullable().describe("Name for the vehicle. Required for 'save-vehicle'."),
-    vehicleLicensePlate: z.string().nullable().describe("License plate for the vehicle. Required for 'save-vehicle'."),
-    vehicleDescription: z.string().nullable().describe("Description for the vehicle. Optional for 'save-vehicle'."),
+    vehicleName: z
+        .string()
+        .nullable()
+        .describe("Name for the vehicle. Required for 'save-vehicle'; for 'update-vehicle' it is the new name (omit to leave it unchanged)."),
+    vehicleLicensePlate: z
+        .string()
+        .nullable()
+        .describe("License plate for the vehicle. This is the vehicle's identity — there is no separate UUID. Required for 'save-vehicle', 'update-vehicle', 'delete-vehicle', 'add-vehicle-label' and 'remove-vehicle-label'. A plate cannot be edited: to correct a mistyped plate, 'delete-vehicle' the wrong one and 'save-vehicle' the right one."),
+    vehicleDescription: z
+        .string()
+        .nullable()
+        .describe("Description for the vehicle. Optional for 'save-vehicle'; for 'update-vehicle' it is the new description (omit to leave it unchanged)."),
+    vehicleLabel: z
+        .string()
+        .nullable()
+        .describe("A single vehicle label name. Required for 'add-vehicle-label' and 'remove-vehicle-label'."),
 };
 const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
 // cherry-picked fields from /getVehicleEvents
@@ -108,6 +129,24 @@ export const OUTPUT_SCHEMA = z.object({
     })).optional().describe("License plate search results"),
     saveVehicleResult: z.object({
         success: z.boolean().optional(),
-    }).optional().describe("Result of saving a vehicle"),
+        licensePlate: z.string().optional(),
+    }).optional().describe("Result of saving or updating a vehicle"),
+    deleteVehicleResult: z.object({
+        success: z.boolean().optional(),
+        licensePlate: z.string().optional(),
+    }).optional().describe("Result of deleting a saved vehicle"),
+    vehicleLabelResult: z.object({
+        success: z.boolean().optional(),
+        licensePlate: z.string().optional(),
+        label: z.string().optional(),
+    }).optional().describe("Result of adding or removing a vehicle label"),
+    note: z
+        .string()
+        .optional()
+        .describe("A caveat about this result that the user needs to be told."),
+    warningMsg: z
+        .string()
+        .optional()
+        .describe("A warning from the Rhombus API — the call succeeded, but with a caveat."),
     error: z.string().optional().describe("An error message if the request failed."),
 });