rhombus-node-mcp 0.1.32 → 0.1.34

package/dist/api/automated-prompts-tool-api.js

@@ -0,0 +1,195 @@
+import { postApi } from "../network/network.js";
+import { ChatFollowUpActionEnum, } from "../types/automated-prompts-tool-types.js";
+import { formatIsoWithOffset } from "../util.js";
+function extractNotifyUserUuids(followUpActions) {
+    if (!followUpActions)
+        return undefined;
+    const notifyAction = followUpActions.find((action) => action?.type === ChatFollowUpActionEnum.NOTIFY_USERS);
+    if (!notifyAction)
+        return undefined;
+    const userUuids = notifyAction.userUuids;
+    return userUuids?.filter((u) => u !== null) ?? [];
+}
+function toSummary(prompt, timeZone) {
+    if (!prompt)
+        return undefined;
+    return {
+        uuid: prompt.uuid ?? undefined,
+        prompt: prompt.prompt ?? undefined,
+        responseTemplate: prompt.responseTemplate ?? undefined,
+        frequency: prompt.frequency
+            ? {
+                frequency: prompt.frequency.frequency ?? undefined,
+                unit: prompt.frequency.unit ?? undefined,
+            }
+            : undefined,
+        invokeAt: formatIsoWithOffset(prompt.invokeAtMs, timeZone),
+        permissionGroupUuid: prompt.permissionGroupUuid ?? undefined,
+        notifyUserUuids: extractNotifyUserUuids(prompt.followUpActions),
+        scheduleUuid: prompt.scheduleUuid ?? undefined,
+        orgUuid: prompt.orgUuid ?? undefined,
+    };
+}
+function toHistoryEntry(record, timeZone) {
+    if (!record)
+        return undefined;
+    return {
+        uuid: record.uuid ?? undefined,
+        automatedPromptUuid: record.automatedPromptUuid ?? undefined,
+        query: record.query ?? undefined,
+        response: record.response ?? undefined,
+        queriedAt: formatIsoWithOffset(record.queriedAtMs, timeZone),
+        respondedAt: formatIsoWithOffset(record.respondedAtMs, timeZone),
+        responseType: record.responseType ?? undefined,
+    };
+}
+function buildSettingsBody(input, includeUuid) {
+    const settings = {};
+    if (includeUuid && "promptUuid" in input && input.promptUuid) {
+        settings.uuid = input.promptUuid;
+    }
+    if (input.prompt !== undefined && input.prompt !== null) {
+        settings.prompt = input.prompt;
+    }
+    if (input.responseTemplate !== undefined && input.responseTemplate !== null) {
+        settings.responseTemplate = input.responseTemplate;
+    }
+    if (input.invokeAtMs !== undefined && input.invokeAtMs !== null) {
+        settings.invokeAtMs = input.invokeAtMs;
+    }
+    if (input.frequencyValue !== undefined &&
+        input.frequencyValue !== null &&
+        input.frequencyUnit !== undefined &&
+        input.frequencyUnit !== null) {
+        settings.frequency = {
+            frequency: input.frequencyValue,
+            unit: input.frequencyUnit,
+        };
+    }
+    if (input.permissionGroupUuid !== undefined && input.permissionGroupUuid !== null) {
+        settings.permissionGroupUuid = input.permissionGroupUuid;
+    }
+    if (input.notifyUserUuids !== undefined && input.notifyUserUuids !== null) {
+        settings.followUpActions = input.notifyUserUuids.length
+            ? [
+                {
+                    type: ChatFollowUpActionEnum.NOTIFY_USERS,
+                    userUuids: input.notifyUserUuids,
+                },
+            ]
+            : [];
+    }
+    return settings;
+}
+export async function listAutomatedPrompts(pageRequest, requestModifiers, sessionId, timeZone) {
+    const res = await postApi({
+        route: "/chatbot/automation/getAutomatedPromptsForOrg",
+        body: pageRequest,
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    const settingsList = (res.settingsList ?? [])
+        .map((p) => toSummary(p, timeZone))
+        .filter((s) => s !== undefined);
+    return {
+        settingsList,
+        lastEvaluatedKey: res.lastEvaluatedKey ?? undefined,
+    };
+}
+export async function getAutomatedPrompt(promptUuid, requestModifiers, sessionId, timeZone) {
+    const res = await postApi({
+        route: "/chatbot/automation/getAutomatedPrompt",
+        body: { promptUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    return toSummary(res.settings, timeZone);
+}
+export async function createAutomatedPrompt(input, requestModifiers, sessionId, timeZone) {
+    const settings = buildSettingsBody(input, /*includeUuid*/ false);
+    const res = await postApi({
+        route: "/chatbot/automation/createAutomatedPrompt",
+        body: { settings },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    return toSummary(res.settings, timeZone);
+}
+export async function updateAutomatedPrompt(input, requestModifiers, sessionId, timeZone) {
+    const selectiveUpdate = buildSettingsBody(input, /*includeUuid*/ true);
+    const res = await postApi({
+        route: "/chatbot/automation/updateAutomatedPrompt",
+        body: { selectiveUpdate },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    return toSummary(res.settings, timeZone);
+}
+export async function deleteAutomatedPrompt(promptUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/chatbot/automation/deleteAutomatedPrompt",
+        body: { promptUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    return { ok: true, action: "deleted" };
+}
+export async function getAutomatedPromptChatHistory(promptUuid, pageRequest, requestModifiers, sessionId, timeZone) {
+    const res = await postApi({
+        route: "/chatbot/automation/getAutomatedPromptChatHistory",
+        body: {
+            promptUuid,
+            lastEvaluatedKey: pageRequest.lastEvaluatedKey ?? undefined,
+            maxPageSize: pageRequest.maxPageSize ?? undefined,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    const chatHistory = (res.chatHistory ?? [])
+        .map((r) => toHistoryEntry(r, timeZone))
+        .filter((e) => e !== undefined);
+    return {
+        chatHistory,
+        lastEvaluatedKey: res.lastEvaluatedKey ?? undefined,
+    };
+}
+export async function shareAutomatedPromptResponse(chatUuid, visibility, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/chatbot/automation/shareAutomatedPromptResponse",
+        body: {
+            chatUuid,
+            privacy: { visibility },
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    return { ok: true, action: `visibility set to ${visibility}` };
+}
+export async function verifyJobScheduled(promptUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/chatbot/automation/verifyJobScheduled",
+        body: { promptUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error)
+        throw new Error(JSON.stringify(res));
+    return {
+        scheduleExpression: res.scheduleExpression ?? undefined,
+        scheduleTimezone: res.scheduleTimezone ?? undefined,
+    };
+}

package/dist/api/user-tool-api.js

@@ -58,6 +58,39 @@ export async function getPermissionsForCurrentUser(requestModifiers, sessionId)
             : undefined,
     };
 }
+/**
+ * Keep only non-null string entries from a nullable string[] coming back from
+ * the generated schema types.
+ */
+function cleanStringArray(arr) {
+    if (!arr)
+        return undefined;
+    const cleaned = arr.filter((v) => typeof v === "string");
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * Map a `{ [k]: PermissionEnum }` to a `Record<string, string>` dropping null
+ * values. Returns undefined when the input is nullish so the field is omitted
+ * from the JSON payload entirely (and the filtering proxy's `includeFields`
+ * can omit it without ambiguity).
+ */
+function toStringMap(map) {
+    if (!map)
+        return undefined;
+    const entries = Object.entries(map).filter((pair) => typeof pair[1] === "string");
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function toNestedStringMap(map) {
+    if (!map)
+        return undefined;
+    const result = {};
+    for (const [outer, inner] of Object.entries(map)) {
+        const cleanedInner = toStringMap(inner);
+        if (cleanedInner)
+            result[outer] = cleanedInner;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
 export async function getPermissionGroups(requestModifiers, sessionId) {
     const res = await postApi({
         route: "/permission/getPermissionGroupsForOrg",
@@ -71,7 +104,23 @@ export async function getPermissionGroups(requestModifiers, sessionId) {
     return (res.permissionGroups?.map(group => ({
         uuid: group.uuid ?? undefined,
         name: group.name ?? undefined,
+        description: group.description ?? undefined,
         orgUuid: group.orgUuid ?? undefined,
-        role: group.role ?? undefined,
+        mutable: group.mutable ?? undefined,
+        superAdmin: group.superAdmin ?? undefined,
+        installer: group.installer ?? undefined,
+        inLine: group.inLine ?? undefined,
+        storedInS3: group.storedInS3 ?? undefined,
+        defaultPermissionForNewLocations: group.defaultPermissionForNewLocations ?? undefined,
+        defaultAccessControlPermissionForNewLocations: group.defaultAccessControlPermissionForNewLocations ?? undefined,
+        functionalityList: group.functionalityList ?? undefined,
+        accessibleLocations: cleanStringArray(group.accessibleLocations),
+        assignablePermissionGroups: cleanStringArray(group.assignablePermissionGroups),
+        // Heavy maps — callers should typically prune these out via includeFields.
+        locationAccessMap: toStringMap(group.locationAccessMap),
+        accessControlLocationAccessMap: toStringMap(group.accessControlLocationAccessMap),
+        deviceAccessMap: toStringMap(group.deviceAccessMap),
+        userPermissionGroupAccessMap: toStringMap(group.userPermissionGroupAccessMap),
+        locationGranularAccessMap: toNestedStringMap(group.locationGranularAccessMap),
     })) ?? []);
 }

package/dist/tools/automated-prompts-tool.js

@@ -0,0 +1,145 @@
+import { createAutomatedPrompt, deleteAutomatedPrompt, getAutomatedPrompt, getAutomatedPromptChatHistory, listAutomatedPrompts, shareAutomatedPromptResponse, updateAutomatedPrompt, verifyJobScheduled, } from "../api/automated-prompts-tool-api.js";
+import { AutomatedPromptsRequestType, CreateRequestSchema, DeleteRequestSchema, GetHistoryRequestSchema, GetRequestSchema, ListRequestSchema, OUTPUT_SCHEMA, ShareResponseRequestSchema, TOOL_ARGS, UpdateRequestSchema, VerifyScheduledRequestSchema, } from "../types/automated-prompts-tool-types.js";
+import { createToolStructuredContent, createToolTextContent, extractFromToolExtra, } from "../util.js";
+const TOOL_NAME = "automated-prompts-tool";
+const TOOL_DESCRIPTION = `
+This tool manages Rhombus MIND automated prompts - scheduled chatbot jobs that run a prompt at a recurring interval and store each response. Use it to list, inspect, create, update, delete, page through past responses for, share, or re-verify the schedule of an automated prompt.
+
+Modes (set "requestType"):
+- ${AutomatedPromptsRequestType.LIST}: List all automated prompts in the org. Optional 'lastEvaluatedKey' / 'maxPageSize' for pagination.
+- ${AutomatedPromptsRequestType.GET}: Get a single automated prompt's settings. Requires 'promptUuid'.
+- ${AutomatedPromptsRequestType.CREATE}: Create a new automated prompt. Requires 'prompt', 'invokeAt' (ISO 8601 with offset, must be at least 15 minutes in the future), 'frequencyValue', 'frequencyUnit', and 'permissionGroupUuid'. Optional 'responseTemplate' and 'notifyUserUuids'.
+- ${AutomatedPromptsRequestType.UPDATE}: Selectively update an automated prompt. Requires 'promptUuid'; only the fields you set will be changed. To change the role, the caller must have access to both the current and new role. Pass an empty 'notifyUserUuids' array to clear notifyees.
+- ${AutomatedPromptsRequestType.DELETE}: Delete an automated prompt and all of its stored responses. Requires 'promptUuid'.
+- ${AutomatedPromptsRequestType.GET_HISTORY}: Page through responses generated by an automated prompt. Requires 'promptUuid'. Optional 'lastEvaluatedKey' / 'maxPageSize'.
+- ${AutomatedPromptsRequestType.SHARE_RESPONSE}: Update the visibility of one stored response. Requires 'chatUuid' and 'visibility' (PUBLIC, ORG_WIDE, SELECT_USERS, PRIVATE).
+- ${AutomatedPromptsRequestType.VERIFY_SCHEDULED}: Re-verify that the job is scheduled to trigger; the server reschedules it if missing. Requires 'promptUuid'.
+
+Notes:
+- Use 'user-tool' to look up user UUIDs and resolve them to names/emails. 'notifyUserUuids' must be members of the chosen 'permissionGroupUuid'.
+- 'invokeAt' is an ISO 8601 timestamp; both 'Z' and '+/-HH:mm' offsets are accepted. The tool converts it to milliseconds for the API.
+- Timestamps in the output are ISO 8601 strings with timezone offset (defaults to America/Los_Angeles when no org timezone is available).
+- 'submitTestPrompt' is intentionally not exposed by this tool.
+`;
+function formatZodError(err) {
+    return err.issues
+        .map(issue => {
+        const path = issue.path.join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+function validationErrorResponse(err) {
+    return createToolTextContent(JSON.stringify({ error: formatZodError(err) }));
+}
+const TOOL_HANDLER = async (args, _extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(_extra);
+    try {
+        switch (args.requestType) {
+            case AutomatedPromptsRequestType.LIST: {
+                const parsed = ListRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const { lastEvaluatedKey, maxPageSize } = parsed.data;
+                const result = await listAutomatedPrompts({
+                    lastEvaluatedKey: lastEvaluatedKey ?? undefined,
+                    maxPageSize: maxPageSize ?? undefined,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    settingsList: result.settingsList,
+                    lastEvaluatedKey: result.lastEvaluatedKey,
+                });
+            }
+            case AutomatedPromptsRequestType.GET: {
+                const parsed = GetRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const settings = await getAutomatedPrompt(parsed.data.promptUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({ settings });
+            }
+            case AutomatedPromptsRequestType.CREATE: {
+                const parsed = CreateRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const data = parsed.data;
+                const settings = await createAutomatedPrompt({
+                    prompt: data.prompt,
+                    invokeAtMs: new Date(data.invokeAt).getTime(),
+                    frequencyValue: data.frequencyValue,
+                    frequencyUnit: data.frequencyUnit,
+                    permissionGroupUuid: data.permissionGroupUuid,
+                    responseTemplate: data.responseTemplate ?? undefined,
+                    notifyUserUuids: data.notifyUserUuids ?? undefined,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({ settings });
+            }
+            case AutomatedPromptsRequestType.UPDATE: {
+                const parsed = UpdateRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const data = parsed.data;
+                const settings = await updateAutomatedPrompt({
+                    promptUuid: data.promptUuid,
+                    prompt: data.prompt ?? undefined,
+                    invokeAtMs: data.invokeAt ? new Date(data.invokeAt).getTime() : undefined,
+                    frequencyValue: data.frequencyValue ?? undefined,
+                    frequencyUnit: data.frequencyUnit ?? undefined,
+                    permissionGroupUuid: data.permissionGroupUuid ?? undefined,
+                    responseTemplate: data.responseTemplate ?? undefined,
+                    notifyUserUuids: data.notifyUserUuids ?? undefined,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({ settings });
+            }
+            case AutomatedPromptsRequestType.DELETE: {
+                const parsed = DeleteRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const success = await deleteAutomatedPrompt(parsed.data.promptUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({ success });
+            }
+            case AutomatedPromptsRequestType.GET_HISTORY: {
+                const parsed = GetHistoryRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const data = parsed.data;
+                const result = await getAutomatedPromptChatHistory(data.promptUuid, {
+                    lastEvaluatedKey: data.lastEvaluatedKey ?? undefined,
+                    maxPageSize: data.maxPageSize ?? undefined,
+                }, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    chatHistory: result.chatHistory,
+                    lastEvaluatedKey: result.lastEvaluatedKey,
+                });
+            }
+            case AutomatedPromptsRequestType.SHARE_RESPONSE: {
+                const parsed = ShareResponseRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const { chatUuid, visibility } = parsed.data;
+                const success = await shareAutomatedPromptResponse(chatUuid, visibility, requestModifiers, sessionId);
+                return createToolStructuredContent({ success });
+            }
+            case AutomatedPromptsRequestType.VERIFY_SCHEDULED: {
+                const parsed = VerifyScheduledRequestSchema.safeParse(args);
+                if (!parsed.success)
+                    return validationErrorResponse(parsed.error);
+                const verifyResult = await verifyJobScheduled(parsed.data.promptUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({ verifyResult });
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return createToolStructuredContent({ error: error.message });
+        }
+        return createToolStructuredContent({ error: "Unknown error" });
+    }
+    return createToolStructuredContent({ error: "Invalid request type" });
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+    }, TOOL_HANDLER);
+}

package/dist/tools/camera-tool.js

@@ -29,6 +29,29 @@ What follows is a description of the behavior of this tool given the requestType
 This tool retrieves the current configuration for a specified camera or associated device (e.g., sensor, access controller). The returned JSON object can include detailed camera settings (e.g., resolution, bitrate) and various device-specific configurations (e.g. storage settings).
 
 NOTE: To update camera settings, use the update-tool instead.
+
+---
+
+**AUTOMATIC SNAPSHOT FOR IMAGE QUALITY ISSUES** — When a user mentions camera image quality (darkness, brightness, blur, washed out, "doesn't look great", "fix the image", etc.), you MUST IMMEDIATELY:
+1. Call camera-tool with requestType "image" to capture a snapshot WITHOUT asking first.
+2. Analyze the image to identify quality issues.
+3. Call camera-tool with requestType "get-settings" to check current camera settings.
+4. Propose specific setting changes based on your analysis (store the exact values you plan to change, e.g. img_brightness, wdr_strength).
+5. When the user confirms ("yes", "confirm", "fix it", "apply", "go ahead", "ok", etc.), call update-tool with those stored settings — see update-tool's description for the confirmation flow. NEVER skip the update-tool call.
+
+Examples that REQUIRE the automatic snapshot flow:
+- "This camera's image doesn't look great"
+- "The image quality is poor"
+- "Can you fix the image"
+- "Adjust settings to be optimal"
+- "The camera looks blurry/dark/washed out"
+- Any mention of image appearance problems.
+
+**VISUAL-FEATURE CAMERA FILTERING** — When the user asks for cameras filtered by what they can see (indoors/outdoors, "facing the street", "with a view of X", parking lot, entrance), you MUST:
+1. First get the camera list via get-entity-tool or location-tool.
+2. Then call camera-tool with requestType "image" for EACH candidate camera (in PARALLEL).
+3. Analyze each image to determine if it meets the user's criteria.
+4. Return only the cameras that match.
 `;
 const logger = getLogger("camera-tool");
 const TOOL_ARGS = BASE_TOOL_ARGS;

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

@@ -23,6 +23,20 @@ It has the following modes of operation, determined by the "requestType" paramet
 - ${DoorScheduleExceptionRequestType.UPDATE_EXCEPTION}: Update a door schedule exception. Requires exception (DoorScheduleExceptionType object). If intervals are omitted but defaultState and date range are provided, the tool will generate a full-day interval.
 
 Use get-entity-tool to look up location and door UUIDs when needed.
+
+---
+
+**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 remove or add doors while preserving the others:
+
+1. Call \`find-exceptions\` (or \`get-exception\`) to fetch the exception. The response includes the **full \`doorUuids\` array** for that exception — that IS the current door list.
+2. Compute the new array yourself:
+   - **Remove doors:** filter the existing \`doorUuids\` array, dropping the ones to remove.
+   - **Add doors:** append the new UUIDs to the existing array (deduped).
+   - **Replace wholesale:** just 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 them to leave them 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. The doorUuids array you got back IS the context.
 `;
 function buildDateRangeFilter(args) {
     return {

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

@@ -4,15 +4,14 @@ import { TOOL_ARGS } from "../types/get-entity-tool-types.js";
 import { createToolTextContent, extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "get-entity-tool";
 const TOOL_DESCRIPTION = `
-Retrieves entities (or devices) of certain types.
-Can request multiple entity types at once.
-The return structure is a JSON string that contains the states of the requested entities.
-This data is exact. Whatever entities exist will be returned here.
+Retrieves entities (or devices) of certain types — cameras, doorbell cameras, badge readers, access-controlled doors, audio gateways, door sensors, environmental sensors, motion sensors, buttons, keypads, environmental gateways. Can request multiple entity types at once. The return structure is a JSON string that contains the states (including names, UUIDs, location, model, firmware, connection status) of the requested entities. This data is exact.
 
-This is the primary tool for checking device health and connectivity status. Each device in the response
-includes a "connected" boolean field indicating whether it is currently online (true) or offline (false).
-When asked about device health, offline devices, or connectivity issues, use this tool to fetch all device
-types and check the "connected" field to identify which devices are offline or unreachable.`;
+**Primary use cases:**
+1. **Looking up a device by name.** When the user mentions a specific camera, door, sensor, etc. by name (e.g. "describe camera 1919 Front Door Entrance", "what's the status of HW Lab door"), call this tool with the matching entityType, scan the returned list, and **fuzzy/case-insensitive substring match** the user's reference against the \`name\` field. Don't ask the user to clarify — try this lookup first, and only ask if there are genuinely multiple plausible matches in the results.
+2. **Listing all devices of a type** (cameras, doors, sensors, etc.) for a location or org-wide.
+3. **Checking device health and connectivity.** Each device includes a \`connected\` boolean (true = online, false = offline). For "which devices are offline?" / "is X online?" / health questions, fetch the relevant entityTypes and inspect \`connected\`.
+
+When the user asks to "describe", "look up", "find", "show me", or "tell me about" a named device, this is almost always the right starting tool — call it before asking the user for more specifics.`;
 const TOOL_HANDLER = async (args, extra) => {
     const { entityTypes, timeZone, tempUnit } = args;
     const filterBy = args.filterBy ?? { locationUuids: null };

package/dist/tools/get-org-information-tool.js

@@ -2,7 +2,7 @@ import { getOrg } from "../api/get-org-information-tool-api.js";
 import { TOOL_ARGS } from "../types/get-org-information-tool-types.js";
 const TOOL_NAME = "get-org-information";
 const TOOL_DESCRIPTION = "Get general information about the organization including org name, camera configuration defaults, contact information, and org settings.";
-const TOOL_HANDLER = async (args, extra) => {
+const TOOL_HANDLER = async (_, extra) => {
     const org = await getOrg(extra._meta?.requestModifiers, extra.sessionId);
     return {
         content: [

package/dist/tools/report-tool.js

@@ -6,6 +6,8 @@ const TOOL_NAME = "report-tool";
 const TOOL_DESCRIPTION = `
 **Scope:** This tool returns **aggregated counts and time-series summaries** over specified intervals and scopes. Use **events-tool** when you need raw, event-level data (individual events with timestamps). Use this tool for high-level reports, analytics, and trends—especially over periods of a day or more.
 
+**Interval guidance:** A shorter interval (HOURLY instead of DAILY) gives a better representation of data over time. Balance interval and range so you don't request too much data. For ranges spanning a week or so, HOURLY is appropriate.
+
 ---
 
 **People / occupancy counting strategy**

package/dist/tools/time-tool.js

@@ -1,7 +1,11 @@
 import { parseTimeDescription } from "../api/time-tool-api.js";
 import { TOOL_ARGS } from "../types/time-tool-types.js";
 const TOOL_NAME = "time-tool";
-const TOOL_DESCRIPTION = "This tool is capable of returning the time from a natural language query.  If the user asks about the 'current time' use this tool.  Try to kee time_description as close to the users initial query as possible.  For example if someone says 'was X person seen today?' then time_description should be 'today'.";
+const TOOL_DESCRIPTION = `This tool returns timestamps from natural-language descriptions of time. If the user asks about the "current time", use this tool. Keep time_description as close to the user's original phrasing as possible — e.g. for "was X person seen today?" use time_description "today".
+
+**When to call:** Whenever the user provides a natural-language time description ("today", "5 days ago", "last week", "this morning"), call time-tool to get accurate timestamps. Do not invent timestamps yourself. If you will need a timestamp as input to another tool, call time-tool first; multiple parallel calls are fine.
+
+**Default timezone:** Assume "America/Los_Angeles" unless the user specifies otherwise or device/location context indicates a different one.`;
 const TOOL_HANDLER = async (args, extra) => {
     const { time_description, timezone } = args;
     const result = parseTimeDescription(time_description ?? undefined, timezone ?? undefined, extra);

package/dist/tools/update-tool.js

@@ -27,6 +27,21 @@ Future support planned for:
 - Badge readers
 
 The tool uses elicitation forms for rich user interaction and shows current settings before updates.
+
+---
+
+**CAMERA SETTINGS UPDATE FLOW** — Use this tool for ALL camera settings updates (brightness, contrast, WDR, resolution, audio, LED, etc.).
+- For camera image-quality fixes: provide entityType="camera", entityUuid, and the specific settings to change in cameraVideoSettings.
+- Example for dark image: update-tool(entityType="camera", entityUuid="<uuid>", cameraVideoSettings='{"img_brightness": 0, "wdr_strength": 64}').
+- Example for washed out: update-tool(entityType="camera", entityUuid="<uuid>", cameraVideoSettings='{"img_brightness": -50, "img_contrast": 80}').
+- Saturation matters — saturation 0 yields a grayscale image. Most cameras look best with mid-range values; tune from there.
+
+**CONFIRMATION FLOW (MANDATORY)** — When the conversation history shows you analyzed a camera and proposed fixes, and the user replies with any affirmative ("yes", "confirm", "fix it", "apply", "do it", "go ahead", "proceed", "sure", "ok"):
+1. DO NOT generate any text response first.
+2. IMMEDIATELY call update-tool with the camera settings you previously identified.
+3. Only after update-tool returns successfully, say "Done! Check your camera now…".
+
+NEVER respond saying settings were updated without first calling update-tool — without the call, no changes take effect. Avoid multiple rounds of confirmation; get one confirmation for all proposed changes.
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { entityType, entityUuid, cameraVideoSettings, cameraAudioSettings, cameraDeviceSettings, step, } = args;

package/dist/tools/user-tool.js

@@ -9,9 +9,16 @@ It has the following modes of operation, determined by the "requestType" paramet
 - ${UserToolRequestType.LIST_USERS}: List all users in the organization with their details and roles.
 - ${UserToolRequestType.FIND_BY_EMAIL}: Find a specific user by their email address. Requires the email parameter.
 - ${UserToolRequestType.GET_PERMISSIONS}: Get the permissions for the current API user/token.
-- ${UserToolRequestType.GET_PERMISSION_GROUPS}: List all permission groups defined in the organization.
+- ${UserToolRequestType.GET_PERMISSION_GROUPS}: List all permission groups defined in the organization. Each row can be very large — see below.
 
 User UUIDs returned here can be used with the access-control-tool to look up credentials.
+
+IMPORTANT for '${UserToolRequestType.GET_PERMISSION_GROUPS}':
+Each permission group row includes five access maps whose size scales with the org's locations, devices, and other permission groups. The total payload for 'userPermissionGroupAccessMap' across all rows grows O(N^2) in the number of permission groups. Before calling, decide which fields you actually need and pass them via 'includeFields':
+- Safe/small fields (O(1) per row): 'permissionGroups.uuid', 'permissionGroups.name', 'permissionGroups.description', 'permissionGroups.mutable', 'permissionGroups.superAdmin', 'permissionGroups.installer', 'permissionGroups.defaultPermissionForNewLocations', 'permissionGroups.defaultAccessControlPermissionForNewLocations'.
+- Bounded fields (O(K) per row): 'permissionGroups.functionalityList', 'permissionGroups.accessibleLocations', 'permissionGroups.assignablePermissionGroups'.
+- Heavy fields (O(locations) / O(devices) / O(groups) per row): 'permissionGroups.locationAccessMap', 'permissionGroups.accessControlLocationAccessMap', 'permissionGroups.deviceAccessMap', 'permissionGroups.userPermissionGroupAccessMap', 'permissionGroups.locationGranularAccessMap'. Only request these when you specifically need them for a user.
+Typical usage when just picking a role uuid: 'includeFields: ["permissionGroups.uuid", "permissionGroups.name", "permissionGroups.description"]'.
 `;
 const TOOL_HANDLER = async (args, _extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(_extra);

package/dist/types/automated-prompts-tool-types.js

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import { ISOTimestampFormatDescription } from "../utils/timestampInput.js";
+import { ChatFollowUpActionEnum, ChatVisibilityEnum, FrequencyUnitEnum } from "./schema.js";
+export var AutomatedPromptsRequestType;
+(function (AutomatedPromptsRequestType) {
+    AutomatedPromptsRequestType["LIST"] = "list";
+    AutomatedPromptsRequestType["GET"] = "get";
+    AutomatedPromptsRequestType["CREATE"] = "create";
+    AutomatedPromptsRequestType["UPDATE"] = "update";
+    AutomatedPromptsRequestType["DELETE"] = "delete";
+    AutomatedPromptsRequestType["GET_HISTORY"] = "get-history";
+    AutomatedPromptsRequestType["SHARE_RESPONSE"] = "share-response";
+    AutomatedPromptsRequestType["VERIFY_SCHEDULED"] = "verify-scheduled";
+})(AutomatedPromptsRequestType || (AutomatedPromptsRequestType = {}));
+export const TOOL_ARGS = {
+    requestType: z
+        .enum(AutomatedPromptsRequestType)
+        .describe("The type of automated prompt request to make."),
+    promptUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of the automated prompt. Required for 'get', 'update', 'delete', 'get-history', and 'verify-scheduled'."),
+    chatUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of a chat record (an individual response generated by an automated prompt). Required for 'share-response'."),
+    visibility: z
+        .enum(ChatVisibilityEnum)
+        .nullable()
+        .describe("Visibility for a shared chat response. Required for 'share-response'. One of PUBLIC, ORG_WIDE, SELECT_USERS, PRIVATE."),
+    prompt: z
+        .string()
+        .nullable()
+        .describe("The prompt MIND will execute every time the job runs. Required for 'create', recommended for 'update'."),
+    responseTemplate: z
+        .string()
+        .nullable()
+        .describe("Optional template that guides the shape of MIND's response. Used by 'create' and 'update'."),
+    frequencyValue: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .describe("How many time units between runs (e.g. 1 for 'every 1 day'). Required for 'create' alongside frequencyUnit."),
+    frequencyUnit: z
+        .enum(FrequencyUnitEnum)
+        .nullable()
+        .describe("Unit for the recurrence (HOURS, DAYS, WEEKS, MONTHS). Required for 'create' alongside frequencyValue."),
+    invokeAt: z.iso
+        .datetime({
+        message: "Invalid datetime string. Expected ISO 8601 format.",
+        offset: true,
+    })
+        .nullable()
+        .describe("When the automated prompt should first run. Required for 'create'. Must be at least 15 minutes in the future. " +
+        ISOTimestampFormatDescription),
+    permissionGroupUuid: z
+        .string()
+        .nullable()
+        .describe("UUID of the permission group/role that owns the job. Users in this role (or a higher role) can view and edit the job, and MIND uses this role's permissions when running the prompt. Required for 'create'."),
+    notifyUserUuids: z
+        .array(z.string())
+        .nullable()
+        .describe("User UUIDs to email-notify when MIND finishes a run. These users must be members of the permission group set above. Used by 'create' and 'update'. Pass an empty array to clear existing notifyees on 'update'."),
+    lastEvaluatedKey: z
+        .string()
+        .nullable()
+        .describe("Pagination cursor returned by a previous 'list' or 'get-history' call. Pass to fetch the next page."),
+    maxPageSize: z
+        .number()
+        .int()
+        .positive()
+        .nullable()
+        .describe("Maximum number of items per page for 'list' and 'get-history'."),
+};
+const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+/**
+ * Below is the individual request types schema
+ */
+const invokeAtDatetime = z.iso.datetime({
+    message: "invokeAt must be a valid ISO 8601 timestamp with offset (e.g. 2026-04-22T10:57:00-07:00).",
+    offset: true,
+});
+export const ListRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.LIST),
+    lastEvaluatedKey: z.string().nullish(),
+    maxPageSize: z.number().int().positive().nullish(),
+});
+export const GetRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.GET),
+    promptUuid: z.string().min(1, "promptUuid is required."),
+});
+export const CreateRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.CREATE),
+    prompt: z.string().min(1, "prompt is required."),
+    invokeAt: invokeAtDatetime,
+    frequencyValue: z.number().int().positive(),
+    frequencyUnit: z.enum(FrequencyUnitEnum),
+    permissionGroupUuid: z.string().min(1, "permissionGroupUuid is required."),
+    responseTemplate: z.string().nullish(),
+    notifyUserUuids: z.array(z.string()).nullish(),
+});
+export const UpdateRequestSchema = z
+    .object({
+    requestType: z.literal(AutomatedPromptsRequestType.UPDATE),
+    promptUuid: z.string().min(1, "promptUuid is required."),
+    prompt: z.string().min(1).nullish(),
+    invokeAt: invokeAtDatetime.nullish(),
+    frequencyValue: z.number().int().positive().nullish(),
+    frequencyUnit: z.enum(FrequencyUnitEnum).nullish(),
+    permissionGroupUuid: z.string().min(1).nullish(),
+    responseTemplate: z.string().nullish(),
+    notifyUserUuids: z.array(z.string()).nullish(),
+})
+    .refine(data => (data.frequencyValue == null) === (data.frequencyUnit == null), {
+    message: "frequencyValue and frequencyUnit must be provided together when updating recurrence.",
+    path: ["frequencyValue"],
+});
+export const DeleteRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.DELETE),
+    promptUuid: z.string().min(1, "promptUuid is required."),
+});
+export const GetHistoryRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.GET_HISTORY),
+    promptUuid: z.string().min(1, "promptUuid is required."),
+    lastEvaluatedKey: z.string().nullish(),
+    maxPageSize: z.number().int().positive().nullish(),
+});
+export const ShareResponseRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.SHARE_RESPONSE),
+    chatUuid: z.string().min(1, "chatUuid is required."),
+    visibility: z.enum(ChatVisibilityEnum),
+});
+export const VerifyScheduledRequestSchema = z.object({
+    requestType: z.literal(AutomatedPromptsRequestType.VERIFY_SCHEDULED),
+    promptUuid: z.string().min(1, "promptUuid is required."),
+});
+/* More shared types */
+const FrequencySchema = z
+    .object({
+    frequency: z.number().optional(),
+    unit: z.enum(FrequencyUnitEnum).optional(),
+})
+    .describe("How often the prompt runs.");
+const AutomatedPromptSummarySchema = z
+    .object({
+    uuid: z.string().optional(),
+    prompt: z.string().optional(),
+    responseTemplate: z.string().optional(),
+    frequency: FrequencySchema.optional(),
+    invokeAt: z
+        .string()
+        .optional()
+        .describe("Next run time as an ISO 8601 string with timezone offset."),
+    permissionGroupUuid: z.string().optional(),
+    notifyUserUuids: z.array(z.string()).optional(),
+    scheduleUuid: z.string().optional(),
+    orgUuid: z.string().optional(),
+})
+    .describe("Summary of an automated prompt's settings.");
+const ChatHistoryEntrySchema = z
+    .object({
+    uuid: z.string().optional(),
+    automatedPromptUuid: z.string().optional(),
+    query: z.string().optional(),
+    response: z.string().optional(),
+    queriedAt: z
+        .string()
+        .optional()
+        .describe("When the run started, as an ISO 8601 string with offset."),
+    respondedAt: z
+        .string()
+        .optional()
+        .describe("When the response was generated, as an ISO 8601 string with offset."),
+    responseType: z.string().optional(),
+})
+    .describe("One MIND response generated by an automated prompt run.");
+export const OUTPUT_SCHEMA = z.object({
+    settings: AutomatedPromptSummarySchema.optional().describe("Returned by 'get', 'create', and 'update'."),
+    settingsList: z.array(AutomatedPromptSummarySchema).optional().describe("Returned by 'list'."),
+    lastEvaluatedKey: z
+        .string()
+        .optional()
+        .describe("Pagination cursor for the next page; absent when no more pages."),
+    chatHistory: z.array(ChatHistoryEntrySchema).optional().describe("Returned by 'get-history'."),
+    verifyResult: z
+        .object({
+        scheduleExpression: z.string().optional(),
+        scheduleTimezone: z.string().optional(),
+    })
+        .optional()
+        .describe("Returned by 'verify-scheduled'. Schedule expression and timezone for the next trigger."),
+    success: z
+        .object({
+        ok: z.boolean(),
+        action: z.string(),
+    })
+        .optional()
+        .describe("Returned by 'delete' and 'share-response'."),
+    error: z.string().optional().describe("An error message if the request failed."),
+});
+// Re-export for the api/tool layers so they can build ChatPrivacy follow-ups.
+export { ChatFollowUpActionEnum, ChatVisibilityEnum, FrequencyUnitEnum };

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

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { INCLUDE_FIELDS_ARG, FILTER_BY_ARG } from "../util.js";
 export var UserToolRequestType;
 (function (UserToolRequestType) {
     UserToolRequestType["LIST_USERS"] = "list-users";
@@ -7,16 +6,71 @@ export var UserToolRequestType;
     UserToolRequestType["GET_PERMISSIONS"] = "get-permissions";
     UserToolRequestType["GET_PERMISSION_GROUPS"] = "get-permission-groups";
 })(UserToolRequestType || (UserToolRequestType = {}));
+// NOTE: `includeFields` and `filterBy` are NOT declared here — the
+// `createFilteringProxy` wrapper automatically injects them into every tool's
+// inputSchema and post-processes the handler's output. Declaring them here
+// would be dead code (the proxy overwrites them).
 export const TOOL_ARGS = {
     requestType: z.nativeEnum(UserToolRequestType).describe("The type of user request to make."),
     email: z
         .string()
         .nullable()
         .describe("The email address of the user to find. Required for 'find-by-email'."),
-    includeFields: INCLUDE_FIELDS_ARG,
-    filterBy: FILTER_BY_ARG,
 };
 const TOOL_ARGS_SCHEMA = z.object(TOOL_ARGS);
+// Permission level assigned to a resource for a role. Typed loosely as string
+// because the upstream schema enum (READONLY/ADMIN/LIVEONLY) may grow.
+const PermissionEnumLoose = z.string();
+const PermissionGroupSchema = z
+    .object({
+    uuid: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    orgUuid: z.string().optional(),
+    mutable: z.boolean().optional(),
+    superAdmin: z.boolean().optional(),
+    installer: z.boolean().optional(),
+    inLine: z.boolean().optional(),
+    storedInS3: z.boolean().optional(),
+    defaultPermissionForNewLocations: PermissionEnumLoose.optional(),
+    defaultAccessControlPermissionForNewLocations: PermissionEnumLoose.optional(),
+    functionalityList: z
+        .array(z.string())
+        .optional()
+        .describe("List of functionality flags this role unlocks."),
+    accessibleLocations: z
+        .array(z.string())
+        .optional()
+        .describe("UUIDs of locations this role has any access to."),
+    assignablePermissionGroups: z
+        .array(z.string())
+        .optional()
+        .describe("UUIDs of other permission groups a member of this role may assign to users."),
+    // The five maps below grow with the number of locations / devices /
+    // other permission groups in the org. For large orgs a single row can be
+    // hundreds of KB; use `includeFields` to request only the maps you need.
+    locationAccessMap: z
+        .record(z.string(), PermissionEnumLoose)
+        .optional()
+        .describe("locationUuid -> permission level. Size = O(#locations)."),
+    accessControlLocationAccessMap: z
+        .record(z.string(), PermissionEnumLoose)
+        .optional()
+        .describe("locationUuid -> access-control permission level. Size = O(#locations)."),
+    deviceAccessMap: z
+        .record(z.string(), PermissionEnumLoose)
+        .optional()
+        .describe("deviceUuid -> permission level. Size = O(#devices)."),
+    userPermissionGroupAccessMap: z
+        .record(z.string(), PermissionEnumLoose)
+        .optional()
+        .describe("otherPermissionGroupUuid -> permission level. Total payload across all rows is O(N^2) in the number of permission groups — trim with includeFields."),
+    locationGranularAccessMap: z
+        .record(z.string(), z.record(z.string(), PermissionEnumLoose))
+        .optional()
+        .describe("locationUuid -> (subResourceUuid -> permission level). Size = O(#locations * avg #sub-resources)."),
+})
+    .describe("A permission group (role) definition.");
 export const OUTPUT_SCHEMA = z.object({
     users: z
         .array(z.object({
@@ -49,13 +103,8 @@ export const OUTPUT_SCHEMA = z.object({
         .optional()
         .describe("Current user permissions"),
     permissionGroups: z
-        .array(z.object({
-        uuid: z.string().optional(),
-        name: z.string().optional(),
-        orgUuid: z.string().optional(),
-        role: z.string().optional(),
-    }))
+        .array(PermissionGroupSchema)
         .optional()
-        .describe("List of permission groups"),
+        .describe("List of permission groups in the organization."),
     error: z.string().optional().describe("An error message if the request failed."),
 });

package/dist/util.js

@@ -168,3 +168,21 @@ export function formatTimestamp(timestampMs, timeZone) {
         locale: "en-US",
     });
 }
+/**
+ * Formats a timestamp in milliseconds to an ISO 8601 string with timezone offset.
+ * Format: "2025-04-21T10:57:00.000-07:00"
+ *
+ * Use this when returning timestamps in tool output schemas so the offset is preserved
+ * (rather than the bare "Z" produced by Date.prototype.toISOString()).
+ *
+ * @param timestampMs - Timestamp in milliseconds
+ * @param timeZone - Optional IANA timezone string (defaults to "America/Los_Angeles")
+ * @returns ISO 8601 string with offset, or undefined if input is null/undefined
+ */
+export function formatIsoWithOffset(timestampMs, timeZone) {
+    if (timestampMs === null || timestampMs === undefined)
+        return undefined;
+    return (DateTime.fromMillis(timestampMs)
+        .setZone(timeZone || "America/Los_Angeles")
+        .toISO() ?? undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rhombus-node-mcp",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "MCP server for Rhombus API",
   "keywords": [
     "ai",