rhombus-node-mcp 0.1.55 → 0.1.57

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

@@ -3,8 +3,8 @@ import { createUuidSchema } from "../types.js";
 import { createEpochSchema, ISOTimestampFormatDescription, } from "../utils/timestampInput.js";
 export const TOOL_ARGS = {
     requestType: z
-        .enum(["saved", "expiringSoon", "sharedLiveStreams", "timelapseClips", "clipGroups", "sharedClips", "createClip", "deleteClip"])
-        .describe('The type of data to retrieve. Use "saved" for regular saved clips, "expiringSoon" for clips nearing expiration, "sharedLiveStreams" for all shared live video streams, or "timelapseClips" for all timelapse clips.'),
+        .enum(["saved", "expiringSoon", "sharedLiveStreams", "timelapseClips", "clipGroups", "sharedClips", "createClip", "updateClip", "deleteClip"])
+        .describe('The type of data to retrieve or action to perform. "saved" = regular saved clips; "expiringSoon" = clips nearing expiration; "sharedLiveStreams" = all shared live video streams; "timelapseClips" = all timelapse clips; "clipGroups" = clip groups in the org; "sharedClips" = shared clip groups; "createClip" = save a new clip from a camera (requires spliceRequest); "updateClip" = retitle or re-describe an existing saved clip (requires clipUuid plus clipTitle and/or clipDescription); "deleteClip" = permanently delete a saved clip (requires clipUuid; destructive).'),
     deviceUuidFilters: z
         .array(createUuidSchema())
         .nullable()
@@ -35,7 +35,18 @@ export const TOOL_ARGS = {
         .nullable()
         .describe("The end of the time range for which to retrieve clips. Only clips that occurred BEFORE this timestamp will be returned. Required when requestType is saved or expiringSoon." +
         ISOTimestampFormatDescription),
-    clipUuid: z.string().nullable().describe("UUID of a clip. Required for 'deleteClip'."),
+    clipUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of a saved clip. Required for 'deleteClip' and 'updateClip'."),
+    clipTitle: z
+        .string()
+        .nullable()
+        .describe("Only for 'updateClip': a new title for the clip. Omit to leave the title unchanged."),
+    clipDescription: z
+        .string()
+        .nullable()
+        .describe("Only for 'updateClip': a new description for the clip. Omit to leave the description unchanged."),
     spliceRequest: z.object({
         cameraUuid: z.string().describe("Camera UUID to create clip from"),
         startTimeMs: z.number().describe("Start time in milliseconds"),
@@ -49,6 +60,7 @@ export const ApiPayloadSchema = TOOL_ARGS_SCHEMA.transform((args) => {
         args.requestType === "clipGroups" ||
         args.requestType === "sharedClips" ||
         args.requestType === "createClip" ||
+        args.requestType === "updateClip" ||
         args.requestType === "deleteClip") {
         return {};
     }
@@ -87,4 +99,16 @@ export const OUTPUT_SCHEMA = z.object({
     deleteResult: z.object({
         success: z.boolean().optional(),
     }).optional().describe("Result of deleting a clip"),
+    updateResult: z.object({
+        success: z.boolean().optional(),
+        clipUuid: z.string().optional(),
+    }).optional().describe("Result of updating a clip's title or description"),
+    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."),
 });

package/dist/types/create-camera-policy-tool-types.js

@@ -1,15 +1,6 @@
 import { z } from "zod";
 import { schemas } from "./zod-schemas.js";
-// Base schema for the elicitation request
-export const PolicyInfoSchema = z
-    .object({
-    name: z.string().min(1, "Policy name is required"),
-    description: z.string().optional(),
-    orgUuid: z.string().optional(),
-})
-    .describe("Camera policy information");
-export const TOOL_ARGS = {};
-const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+import { ActivityEnum } from "./schema.js";
 export const ApiPayloadSchema = schemas.Policy_CreateCameraPolicyWSRequest;
 export const OUTPUT_SCHEMA = z.object({
     needUserInput: z.boolean().optional(),
@@ -17,14 +8,6 @@ export const OUTPUT_SCHEMA = z.object({
         .string()
         .optional()
         .describe("The message for this stage in the policy creation process.  This message will be displayed to the user."),
-    requestType: z
-        .enum(["policy-creation-form", "schedule-trigger-configuration", "camera-assignment"])
-        .optional()
-        .describe("The type of form to display to the user as the next step in the policy creation process"),
-    submitAction: z
-        .string()
-        .optional()
-        .describe("The action to take when the user completes the form, corresponds to the tool name to interact with next"),
     policyUuid: z
         .string()
         .optional()
@@ -33,12 +16,278 @@ export const OUTPUT_SCHEMA = z.object({
         .string()
         .optional()
         .describe("The name of the policy that was created during this workflow"),
-    scheduleData: z
-        .array(z.object({
-        uuid: z.string(),
-        name: z.string(),
-    }))
-        .nullable()
-        .optional()
-        .describe("The schedules that were created during this workflow, can be null or undefined if user has not created them yet with schedule-trigger-configuration"),
 });
+// ---------------------------------------------------------------------------
+// scheduleConfigs / cameraUuids parsing
+//
+// Both are free-form STRING params, so nothing machine-enforces their shape:
+// tools are adapted for OpenAI with `strict: false`, and even under `strict:
+// true` a string param's *contents* are never constrained. Every check has to
+// live here, and every message has to name the field, the expected shape, and
+// what was actually received — otherwise the model has nothing to correct and
+// reports the whole workflow as broken (prod 2026-08-04).
+// ---------------------------------------------------------------------------
+/**
+ * The activities the camera-policy workflow offers. This is a curated, camera-
+ * relevant subset of the API's org-wide `ActivityEnum` — it is what we suggest,
+ * NOT what we accept (validation goes against the full enum below, so a
+ * legitimate activity the playbook happens not to list still works).
+ *
+ * Keep in sync with the option list in the private MCP's
+ * `workflows/create-camera-policy.ts` playbook.
+ */
+export const SUGGESTED_CAMERA_ACTIVITIES = [
+    "MOTION",
+    "MOTION_HUMAN",
+    "MOTION_CAR",
+    "MOTION_ANIMAL",
+    "FACE_ALERT",
+    "FACE_UNIDENTIFIED",
+    "LICENSEPLATE_ALERT",
+    "HUMAN_ENTER",
+    "HUMAN_EXIT",
+    "CAR_ENTER",
+    "CAR_EXIT",
+    "POSE_ANOMALOUS",
+    "POSE_FALL",
+    "HELMET_MISSING",
+    "MASK_MISSING",
+    "GLOVES_MISSING",
+    "VISUAL_TAMPER",
+    "TAMPER",
+    "PEOPLECOUNT_HIGH",
+];
+const VALID_ACTIVITIES = new Set(Object.values(ActivityEnum));
+export const SCHEDULE_CONFIGS_EXAMPLE = '[{"scheduleUuid":"Wq1nR0kBS9y_2hZpVvGkAA","activities":["MOTION_HUMAN","MOTION_CAR"]}]';
+const SHAPE_HINT = `Expected a JSON array string of objects, each with a "scheduleUuid" string and an "activities" ` +
+    `array of activity strings — e.g. ${SCHEDULE_CONFIGS_EXAMPLE}. "activities" must be a real JSON ` +
+    `array, NOT a string containing one.`;
+// Rhombus uuids are 22-char base64url. Deliberately loose — this only has to
+// catch the model passing a human-readable NAME ("Business Hours", "Front Door")
+// where a uuid belongs, which otherwise reaches the API and fails there, after
+// the policy has already been created.
+const UUID_LIKE = /^[A-Za-z0-9_-]{10,64}$/;
+function quote(value) {
+    const serialized = typeof value === "string" ? value : JSON.stringify(value);
+    const text = serialized ?? String(value);
+    return text.length > 80 ? `${text.slice(0, 80)}…` : text;
+}
+/**
+ * Accept every unambiguous spelling of "a list of activities" the model
+ * produces, and return null only when the value cannot be read as one.
+ * Tolerated: a real array; a JSON-encoded array (the playbook tells the model to
+ * JSON-encode structured values into the form context, and it then re-embeds the
+ * encoded string); a comma-separated string; the API's own
+ * `[{activity: "..."}]` trigger shape.
+ */
+function coerceActivities(raw) {
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return [];
+        if (trimmed.startsWith("[")) {
+            try {
+                return coerceActivities(JSON.parse(trimmed));
+            }
+            catch {
+                return null;
+            }
+        }
+        return trimmed
+            .split(",")
+            .map(part => part.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(raw)) {
+        const out = [];
+        for (const item of raw) {
+            if (typeof item === "string") {
+                if (item.trim())
+                    out.push(item.trim());
+                continue;
+            }
+            if (item && typeof item === "object") {
+                const activity = item.activity;
+                if (typeof activity === "string" && activity.trim()) {
+                    out.push(activity.trim());
+                    continue;
+                }
+            }
+            return null;
+        }
+        return out;
+    }
+    return null;
+}
+function normalizeActivity(activity) {
+    return activity.trim().toUpperCase().replace(/[\s-]+/g, "_");
+}
+/**
+ * Parse the `scheduleConfigs` JSON string into the trigger configs. Runs BEFORE
+ * any mutation so every failure here is safely retryable.
+ */
+export function parseScheduleConfigs(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `scheduleConfigs is not valid JSON (${error instanceof Error ? error.message : "parse error"}). ` +
+                SHAPE_HINT,
+        };
+    }
+    // Unwrap double (or triple) encoding rather than failing on it.
+    let unwrapAttempts = 0;
+    while (typeof parsed === "string" && unwrapAttempts < 3) {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            return {
+                ok: false,
+                message: `scheduleConfigs decoded to a plain string ("${quote(parsed)}") rather than an array. ${SHAPE_HINT}`,
+            };
+        }
+        unwrapAttempts++;
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return {
+            ok: false,
+            message: `scheduleConfigs must be a JSON array; received ${parsed === null ? "null" : `a ${typeof parsed}`} (${quote(raw)}). ${SHAPE_HINT}`,
+        };
+    }
+    // A single config object instead of a one-element array is unambiguous.
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    const configs = [];
+    const issues = [];
+    entries.forEach((entry, index) => {
+        const label = `scheduleConfigs[${index}]`;
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            issues.push(`${label} is not an object (received ${quote(entry)})`);
+            return;
+        }
+        const fields = entry;
+        const scheduleUuidRaw = fields.scheduleUuid ?? fields.uuid ?? fields.schedule;
+        if (typeof scheduleUuidRaw !== "string" || !scheduleUuidRaw.trim()) {
+            issues.push(`${label}.scheduleUuid is missing or not a string (received ${quote(scheduleUuidRaw)})`);
+            return;
+        }
+        const scheduleUuid = scheduleUuidRaw.trim();
+        if (!UUID_LIKE.test(scheduleUuid)) {
+            issues.push(`${label}.scheduleUuid "${scheduleUuid}" is not a UUID — pass the schedule's uuid, not its name`);
+            return;
+        }
+        const activitiesRaw = fields.activities ?? fields.activity ?? fields.triggerSet;
+        const activities = coerceActivities(activitiesRaw);
+        if (activities === null) {
+            issues.push(`${label}.activities must be an array of activity strings (received ${quote(activitiesRaw)})`);
+            return;
+        }
+        if (activities.length === 0) {
+            issues.push(`${label}.activities is empty — include at least one activity`);
+            return;
+        }
+        const normalized = activities.map(normalizeActivity);
+        const unsupported = normalized.filter(activity => !VALID_ACTIVITIES.has(activity));
+        if (unsupported.length > 0) {
+            issues.push(`${label}.activities contains ${unsupported.length === 1 ? "an unsupported value" : "unsupported values"} ` +
+                `${unsupported.map(value => `"${value}"`).join(", ")} — supported camera activities are ` +
+                `${SUGGESTED_CAMERA_ACTIVITIES.join(", ")}`);
+            return;
+        }
+        configs.push({ scheduleUuid, activities: normalized });
+    });
+    if (issues.length > 0) {
+        return { ok: false, message: `Invalid scheduleConfigs: ${issues.join("; ")}.` };
+    }
+    return { ok: true, value: configs };
+}
+/**
+ * True when `scheduleConfigs` is present but carries no configs — the legacy
+ * step-1 call passes an empty list, and the old `!== "[]"` string compare missed
+ * every other spelling of empty ("[ ]", "[\n]", "\"[]\""), which fell through
+ * into policy creation and could create a DUPLICATE policy.
+ */
+export function isEmptyScheduleConfigs(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    let unwrapAttempts = 0;
+    while (typeof parsed === "string" && unwrapAttempts < 3) {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            return false;
+        }
+        unwrapAttempts++;
+    }
+    return Array.isArray(parsed) && parsed.length === 0;
+}
+/**
+ * Parse `cameraUuids` (comma-separated, or a JSON array the model encoded
+ * instead) into a uuid list. Runs BEFORE any mutation, for the same reason as
+ * the schedule configs: an unparsed camera NAME reaches the API and fails only
+ * after the policy exists, leaving a half-built policy behind.
+ */
+export function parseCameraUuids(raw) {
+    let values;
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("[") || trimmed.startsWith('"[')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return {
+                ok: false,
+                message: `cameraUuids looks like a JSON array but is not valid JSON (${quote(raw)}). Pass a comma-separated list of camera uuids, e.g. "uuidA,uuidB".`,
+            };
+        }
+        let unwrapAttempts = 0;
+        while (typeof parsed === "string" && unwrapAttempts < 3) {
+            try {
+                parsed = JSON.parse(parsed);
+            }
+            catch {
+                break;
+            }
+            unwrapAttempts++;
+        }
+        if (!Array.isArray(parsed) || parsed.some(item => typeof item !== "string")) {
+            return {
+                ok: false,
+                message: `cameraUuids must be a comma-separated list of camera uuids, e.g. "uuidA,uuidB" (received ${quote(raw)}).`,
+            };
+        }
+        values = parsed.map(value => value.trim()).filter(Boolean);
+    }
+    else {
+        values = trimmed
+            .split(",")
+            .map(value => value.trim())
+            .filter(Boolean);
+    }
+    if (values.length === 0) {
+        return {
+            ok: false,
+            message: `cameraUuids contained no camera uuids (received ${quote(raw)}). Pass a comma-separated list of camera uuids, e.g. "uuidA,uuidB".`,
+        };
+    }
+    const invalid = values.filter(value => !UUID_LIKE.test(value));
+    if (invalid.length > 0) {
+        return {
+            ok: false,
+            message: `cameraUuids contains ${invalid.length === 1 ? "a value that is not a uuid" : "values that are not uuids"}: ` +
+                `${invalid.map(value => `"${value}"`).join(", ")} — pass camera uuids, not camera names. ` +
+                `Resolve names to uuids with an entity lookup first.`,
+        };
+    }
+    return { ok: true, value: values };
+}

package/dist/types/door-schedule-exception-tool-types.js

@@ -107,7 +107,15 @@ export const DOOR_SCHEDULE_EXCEPTION_INPUT_SCHEMA = z.union([
 export const TOOL_ARGS = {
     requestType: z
         .nativeEnum(DoorScheduleExceptionRequestType)
-        .describe("The type of door schedule exception request to make."),
+        .describe(`The type of door schedule exception request to make.
+- create-exception: create an exception. Requires 'exception'. If locationUuid is missing but doorUuids are provided, the tool resolves the location automatically.
+- update-exception: update an exception. Requires 'exception' (with uuid). If intervals are omitted but defaultState and date range are provided, the tool generates a full-day interval.
+- delete-exception: requires 'exceptionUuid'.
+- get-exception: requires 'exceptionUuid'.
+- find-exceptions: find exceptions across the organization, optionally filtered by date range.
+- find-exceptions-for-location: requires 'locationUuid'; optional date range filters.
+- find-exceptions-for-door: requires 'doorUuid'; optional date range filters.
+An exception whose scheduled date is in the past is EXPIRED. The web console lets users toggle whether expired exceptions are shown — mirror that behavior when responding (mention expired ones separately or note they are hidden by default).`),
     exceptionUuid: z
         .string()
         .nullable()
@@ -120,27 +128,33 @@ export const TOOL_ARGS = {
         .string()
         .nullable()
         .describe("Door UUID. Required for 'find-exceptions-for-door'."),
-    exception: DOOR_SCHEDULE_EXCEPTION_INPUT_SCHEMA.nullable().describe("DoorScheduleExceptionType object. Required for 'create-exception' and 'update-exception'."),
+    exception: DOOR_SCHEDULE_EXCEPTION_INPUT_SCHEMA.nullable().describe(`DoorScheduleExceptionType object. Required for 'create-exception' and 'update-exception'.
+
+Mutating doorUuids on an existing exception (add/remove/replace doors): 'update-exception' REPLACES doorUuids with whatever you pass — it is not a delta operation. To safely add or remove doors while preserving the others:
+1. Call 'find-exceptions' (or 'get-exception') to fetch the exception — the response includes the FULL doorUuids array; that IS the current door list.
+2. Compute the new array yourself: remove = filter out the UUIDs to drop; add = append the new UUIDs (deduped); replace = use the new set.
+3. Call 'update-exception' with exception.uuid and exception.doorUuids set to your computed array. Other fields (name, dates, intervals, defaultState) are optional — omit to leave unchanged.
+You already have the current door list in the find-exceptions response. Do not ask the user for it, do not claim you need additional lookups, and do not refuse the mutation citing missing context.`),
     localStartDateRangeStart: z.iso
         .datetime({ offset: true })
         .optional()
         .nullable()
-        .describe("Optional date range filter (inclusive) for local start date beginning (yyyy-MM-dd)."),
+        .describe("Optional date range filter (inclusive) for local start date beginning. ISO 8601 datetime with offset, e.g. 2026-07-20T00:00:00Z."),
     localStartDateRangeEnd: z.iso
         .datetime({ offset: true })
         .optional()
         .nullable()
-        .describe("Optional date range filter (inclusive) for local start date end (yyyy-MM-dd)."),
+        .describe("Optional date range filter (inclusive) for local start date end. ISO 8601 datetime with offset, e.g. 2026-07-20T23:59:59Z."),
     localEndDateRangeStart: z.iso
         .datetime({ offset: true })
         .optional()
         .nullable()
-        .describe("Optional date range filter (inclusive) for local end date beginning (yyyy-MM-dd)."),
+        .describe("Optional date range filter (inclusive) for local end date beginning. ISO 8601 datetime with offset, e.g. 2026-07-20T00:00:00Z."),
     localEndDateRangeEnd: z.iso
         .datetime({ offset: true })
         .optional()
         .nullable()
-        .describe("Optional date range filter (inclusive) for local end date end (yyyy-MM-dd)."),
+        .describe("Optional date range filter (inclusive) for local end date end. ISO 8601 datetime with offset, e.g. 2026-07-20T23:59:59Z."),
     includeFields: INCLUDE_FIELDS_ARG,
     filterBy: FILTER_BY_ARG,
 };

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

@@ -3,27 +3,43 @@ export var DoorToolRequestType;
 (function (DoorToolRequestType) {
     DoorToolRequestType["GET_DOOR_CONTROLLER_RULES"] = "get-door-controller-rules";
     DoorToolRequestType["CREATE_DOOR_CONTROLLER_RULE"] = "create-door-controller-rule";
+    DoorToolRequestType["UPDATE_DOOR_CONTROLLER_RULE"] = "update-door-controller-rule";
+    DoorToolRequestType["DELETE_DOOR_CONTROLLER_RULE"] = "delete-door-controller-rule";
     DoorToolRequestType["GET_DOOR_POLICIES"] = "get-door-policies";
     DoorToolRequestType["CREATE_DOOR_POLICY"] = "create-door-policy";
+    DoorToolRequestType["UPDATE_DOOR_POLICY"] = "update-door-policy";
+    DoorToolRequestType["DELETE_DOOR_POLICY"] = "delete-door-policy";
 })(DoorToolRequestType || (DoorToolRequestType = {}));
 export const TOOL_ARGS = {
     requestType: z.nativeEnum(DoorToolRequestType).describe("The type of door operation to perform."),
     doorControllerUuid: z
         .string()
         .nullable()
-        .describe("The UUID of the door controller device. Required for 'get-door-controller-rules' and 'create-door-controller-rule'."),
+        .describe("The UUID of the door controller device. Required for every 'door-controller-rule' operation — a rule is addressed by controller AND rule uuid, never by rule uuid alone."),
+    ruleUuid: z
+        .string()
+        .nullable()
+        .describe("The UUID of the door controller rule. Required for 'update-door-controller-rule' and 'delete-door-controller-rule'. Get it from 'get-door-controller-rules' — do not guess one."),
     ruleConfig: z
         .string()
         .nullable()
-        .describe("JSON string of the door controller rule configuration. Required for 'create-door-controller-rule'."),
+        .describe("JSON string of the door controller rule configuration. Required for 'create-door-controller-rule' and 'update-door-controller-rule'. For an update this is MERGED over the rule's current configuration, so send only the fields being changed."),
+    policyUuid: z
+        .string()
+        .nullable()
+        .describe("The UUID of the door policy. Required for 'update-door-policy' and 'delete-door-policy'. Get it from 'get-door-policies' — do not guess one."),
     policyName: z
         .string()
         .nullable()
-        .describe("The name for the new door policy. Required for 'create-door-policy'."),
+        .describe("The name for the door policy. Required for 'create-door-policy'; for 'update-door-policy' it is the new name (omit to leave the name unchanged)."),
     policyConfig: z
         .string()
         .nullable()
-        .describe("JSON string of door policy configuration. Required for 'create-door-policy'."),
+        .describe("JSON string of door policy configuration. Required for 'create-door-policy'; optional for 'update-door-policy', where it is MERGED over the policy's current configuration so only the fields being changed need sending."),
+    confirmDelete: z
+        .boolean()
+        .nullable()
+        .describe("Required to be true for 'delete-door-policy' and 'delete-door-controller-rule'. Both are irreversible and change how doors behave, so they refuse without it. Confirm with the user first."),
 };
 const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
 export const OUTPUT_SCHEMA = z.object({
@@ -60,5 +76,21 @@ export const OUTPUT_SCHEMA = z.object({
     })
         .optional()
         .describe("Result of creating a door policy"),
+    updated: z
+        .object({ success: z.boolean().optional(), uuid: z.string().optional() })
+        .optional()
+        .describe("Result of an update request"),
+    deleted: z
+        .object({ success: z.boolean().optional(), uuid: z.string().optional() })
+        .optional()
+        .describe("Result of a delete request"),
+    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/entity-lookup-tool-types.js

@@ -2,13 +2,18 @@ import { z } from "zod";
 import { createUuidSchema } from "../types.js";
 import { TempUnit } from "../utils/temp.js";
 export const TOOL_ARGS = {
-    deviceUuids: z.array(createUuidSchema()).describe("The UUIDs of the devices to look up."),
+    deviceUuids: z
+        .array(createUuidSchema())
+        .min(1)
+        .nullable()
+        .describe("The UUIDs of the devices to look up. Pass null to return ALL entities of every type (no UUID filter) and narrow with filterBy/includeFields instead. NEVER invent placeholder UUIDs — an unknown UUID matches nothing and returns empty results."),
     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);

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

@@ -19,21 +19,21 @@ export var EventsToolRequestType;
 export const TOOL_ARGS = {
     eventType: z
         .nativeEnum(EventsToolRequestType)
-        .describe("The type of events to retrieve. " +
-        "access-control: Access control events like unlocks, badge ins, credentials, arrivals. " +
-        "brivo-access-control: Badge/credential events from Brivo-integrated doors. Does not require door UUIDs — automatically looks up which doors are configured via the Brivo integration. " +
-        "environmental-gateway: Environmental gateway events with sensor readings and derived values. " +
-        "climate-sensor: Climate sensor events with temperature, humidity, air quality readings. " +
-        "component-events: All types of component events for a location (most flexible option). " +
-        "camera: Footage seekpoints for one camera—all timeline activity types that camera recorded (human motion, vehicle motion, etc., depending on device/analytics). For org LPR saved vehicles, labels, and plate search APIs, use lpr-tool. " +
-        "button-press: Button press events from button sensors. " +
-        "occupancy: Occupancy sensor events with people count. " +
-        "proximity: Proximity tag events with RSSI readings. " +
-        "doorbell: Doorbell camera events."),
+        .describe("The type of events to retrieve. Every mode takes startTime and endTime (ISO 8601); the per-mode UUID argument is named below and in that argument's own description.\n\n" +
+        "access-control: Access control events (arrivals, badge ins, credentials, unlocks) for the doors in accessControlledDoorUuids. Can return a lot of data — use a narrow time range. The returned `credSource` field says how the event was triggered: REMOTE = Rhombus Key app remote unlock; 'REMOTE (Admin)' = unlock via the Rhombus console or browser/mobile app; BLE_WAVE = user waved a hand over the reader; NFC = user tapped a badge or phone on the reader.\n" +
+        "brivo-access-control: Badge/credential events from Brivo-integrated doors. Does not require door UUIDs — automatically fetches the Brivo integration configuration to determine which locations have Brivo doors mapped. Returns integrationEnabled, brivoDoorsConfigured, the brivoDoors list (Brivo IDs, names, Rhombus location UUIDs), and credential-received events newest first. Events are fetched at the LOCATION level, so results may include events from all access-controlled doors at locations where Brivo is configured.\n" +
+        "environmental-gateway: Environmental gateway events (sensor readings and derived values) for deviceUuid.\n" +
+        "climate-sensor: Climate sensor events (temperature, humidity, air quality, vape/THC detection, battery) for sensorUuid. Cap the row count with limit (default 1000).\n" +
+        "component-events: All component event types for locationUuid — the most flexible option. Narrow it with componentEventTypes (see that argument for the full list; omit it for every type).\n" +
+        "camera: Footage seekpoints for cameraUuid over a window of `duration` seconds starting at startTime — all timeline activity types that camera recorded (human motion, vehicle motion, etc., depending on device/analytics), each with an activity string and timestamp; plate/vehicle/face fields appear when the API provides them. For org LPR saved vehicles, labels, and plate search APIs, use lpr-tool.\n" +
+        "button-press: Button press events from the sensor in buttonSensorUuid.\n" +
+        "occupancy: Occupancy sensor events with people count, for occupancySensorUuid.\n" +
+        "proximity: Proximity tag events with RSSI readings, for proximityTagUuids.\n" +
+        "doorbell: Doorbell camera events for doorbellCameraUuid."),
     startTime: z
         .string()
         .datetime({ message: "Invalid datetime string. Expected ISO 8601 format.", offset: true })
-        .describe("A timestamp representing when to start the search for access control events." +
+        .describe("A timestamp representing when to start the search for access control events. Keep the window as narrow as the question allows (e.g. the last 24 hours) — access-control results are returned newest-first and capped at the newest 500 events per door, so an over-wide window only slows the search without returning more." +
         ISOTimestampFormatDescription),
     endTime: z
         .string()
@@ -51,7 +51,7 @@ export const TOOL_ARGS = {
     sensorUuid: z
         .string()
         .nullable()
-        .describe("The UUID of the climate sensor. Required when eventType is 'climate-sensor'. Can be obtained from the get-entity-tool for SENSOR."),
+        .describe("The UUID of the climate sensor. Required when eventType is 'climate-sensor'. Can be obtained from the get-entity-tool for ENVIRONMENTAL_SENSOR."),
     limit: z
         .number()
         .int()
@@ -61,7 +61,11 @@ export const TOOL_ARGS = {
     locationUuid: z
         .string()
         .nullable()
-        .describe("The UUID of the location. Required when eventType is 'component-events'."),
+        .describe("The UUID of the location. Required when eventType is 'component-events'. Must be a UUID returned by a " +
+        "prior tool call in this conversation (get-entity-tool for LOCATION, or the locationUuid on an " +
+        "access-control-door) — never guess or reuse a UUID from memory. Scoping to a location that has no " +
+        "access-controlled doors silently returns zero door events; to review door activity org-wide, query " +
+        "each location that actually has doors."),
     componentEventTypes: z
         .array(z.nativeEnum(ComponentEventEnumType))
         .nullable()
@@ -76,7 +80,7 @@ export const TOOL_ARGS = {
         "AperioGatewayConnectionStateChangeEvent, AperioDtcEvent, AperioTamperStateEvent."),
     timeZone: z
         .string()
-        .describe("The timezone of the requested locations or devices. This is necessary for the tool to produce accurate formatted timestamps."),
+        .describe("The timezone of the requested locations or devices. This is necessary for the tool to produce accurate formatted timestamps. Formatted event timestamps come back in the device / sensor / location timezone, not necessarily UTC."),
     cameraUuid: z
         .string()
         .nullable()
@@ -164,7 +168,7 @@ export const OUTPUT_SCHEMA = z.object({
             .describe("Number of Brivo doors configured in the integration"),
         brivoDoors: z
             .array(z.object({
-            brivoDoornId: z.string().describe("Brivo's door ID"),
+            brivoDoorId: z.string().describe("Brivo's door ID"),
             doorName: z.string().optional().describe("Brivo door name"),
             locationUuid: z.string().optional().describe("Rhombus location UUID for this door"),
         }))
@@ -371,4 +375,8 @@ export const OUTPUT_SCHEMA = z.object({
         .describe("Doorbell camera events"),
     needUserInput: z.boolean().optional(),
     commandForUser: z.string().optional(),
+    note: z
+        .string()
+        .optional()
+        .describe("Diagnostic note about why a result set may be empty or incomplete. Read it before concluding that no events occurred."),
 });