rhombus-node-mcp 0.1.56 → 0.1.57

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

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

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

@@ -0,0 +1,252 @@
+import { deleteCameraPolicy, getCameraPolicies, getCamerasByPolicy, setPolicyOnCameras, updateCameraPolicy, } from "../api/camera-policy-tool-api.js";
+import { CameraPolicyToolRequestType, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/camera-policy-tool-types.js";
+import { parseCameraUuids, parseScheduleConfigs, } from "../types/create-camera-policy-tool-types.js";
+import { createToolStructuredContent, createToolTextContent, extractFromToolExtra, } from "../util.js";
+const TOOL_NAME = "camera-policy-tool";
+const TOOL_DESCRIPTION = `
+This tool reads and manages EXISTING camera alert policies — the rules that decide which camera activities raise an alert, and when.
+
+To CREATE a new camera policy, use create-camera-policy-tool instead. This tool covers everything after creation.
+
+It has the following modes of operation, determined by the "requestType" parameter:
+- ${CameraPolicyToolRequestType.LIST}: List every camera policy with its schedules, trigger activities, and the cameras assigned to it.
+- ${CameraPolicyToolRequestType.GET}: Get one policy in full. Requires policyUuid.
+- ${CameraPolicyToolRequestType.UPDATE}: Rename a policy, change its description, and/or replace its schedule triggers. Requires policyUuid plus at least one of name, description, scheduleConfigs.
+- ${CameraPolicyToolRequestType.DELETE}: Delete a policy. Requires policyUuid. Refuses (without deleting) while cameras are still assigned to it, and lists them — see confirmDeleteInUse.
+- ${CameraPolicyToolRequestType.ASSIGN_CAMERAS}: Assign the policy to cameras. Requires policyUuid and cameraUuids.
+- ${CameraPolicyToolRequestType.UNASSIGN_CAMERAS}: Remove the policy from cameras, leaving them with no policy. Requires policyUuid and cameraUuids.
+
+A camera has at most ONE policy, so assigning a policy to a camera replaces whatever policy it had before. Say so when a camera already has one.
+`;
+/**
+ * Join the camera assignments onto a policy. The camera holds the policyUuid, so
+ * the count is pre-computed here rather than left for the model to derive by
+ * scanning rows — under-enumeration of long tool results is a known failure.
+ */
+function withAssignments(policy, byPolicy) {
+    const cameras = (policy.uuid && byPolicy.get(policy.uuid)) || [];
+    return { ...policy, assignedCameraCount: cameras.length, assignedCameras: cameras };
+}
+const TOOL_HANDLER = async (args, extra) => {
+    const { requestModifiers, sessionId } = extractFromToolExtra(extra);
+    try {
+        switch (args.requestType) {
+            case CameraPolicyToolRequestType.LIST: {
+                const [{ policies, warningMsg }, byPolicy] = await Promise.all([
+                    getCameraPolicies(requestModifiers, sessionId),
+                    getCamerasByPolicy(requestModifiers, sessionId),
+                ]);
+                const enriched = policies.map(policy => withAssignments(policy, byPolicy));
+                const unassigned = enriched.filter(policy => policy.assignedCameraCount === 0);
+                return createToolStructuredContent({
+                    policies: enriched,
+                    warningMsg,
+                    note: enriched.length === 0
+                        ? "This organization has no camera policies. Use create-camera-policy-tool to add one."
+                        : unassigned.length > 0
+                            ? `${unassigned.length} of ${enriched.length} ${unassigned.length === 1 ? "policy is" : "policies are"} assigned to no cameras and therefore never fire: ${unassigned.map(policy => policy.name ?? policy.uuid).join(", ")}.`
+                            : undefined,
+                });
+            }
+            case CameraPolicyToolRequestType.GET: {
+                if (!args.policyUuid) {
+                    return createToolTextContent("policyUuid is required for 'get'.");
+                }
+                const [{ policies }, byPolicy] = await Promise.all([
+                    getCameraPolicies(requestModifiers, sessionId),
+                    getCamerasByPolicy(requestModifiers, sessionId),
+                ]);
+                const policy = policies.find(entry => entry.uuid === args.policyUuid);
+                if (!policy) {
+                    return createToolTextContent(`No camera policy in this organization has the uuid "${args.policyUuid}". Use requestType 'list' to see the policies that exist — do not guess a uuid.`);
+                }
+                return createToolStructuredContent({
+                    policy: withAssignments(policy, byPolicy),
+                });
+            }
+            case CameraPolicyToolRequestType.UPDATE: {
+                if (!args.policyUuid) {
+                    return createToolTextContent("policyUuid is required for 'update'.");
+                }
+                if (!args.name?.trim() && !args.description?.trim() && !args.scheduleConfigs) {
+                    return createToolTextContent("'update' needs at least one of name, description or scheduleConfigs — all were empty, so there is nothing to change.");
+                }
+                // Validate before reading anything, so a malformed input costs no calls.
+                let scheduledTriggers;
+                if (args.scheduleConfigs) {
+                    const parsed = parseScheduleConfigs(args.scheduleConfigs);
+                    if (!parsed.ok) {
+                        return createToolTextContent(`RETRYABLE — nothing was changed. ${parsed.message}`);
+                    }
+                    scheduledTriggers = parsed.value.map(config => ({
+                        scheduleUuid: config.scheduleUuid,
+                        triggerSet: config.activities.map(activity => ({ activity })),
+                    }));
+                }
+                // api2's updateCameraPolicy REPLACES the policy object, so sending only
+                // the changed field would blank the others. Read first and merge.
+                const { policies } = await getCameraPolicies(requestModifiers, sessionId);
+                const existing = policies.find(entry => entry.uuid === args.policyUuid);
+                if (!existing) {
+                    return createToolTextContent(`No camera policy in this organization has the uuid "${args.policyUuid}". Use requestType 'list' to see the policies that exist.`);
+                }
+                const replacedTriggers = scheduledTriggers !== undefined;
+                const mergedTriggers = scheduledTriggers ??
+                    existing.scheduledTriggers?.flatMap(trigger => trigger.scheduleUuid
+                        ? [
+                            {
+                                scheduleUuid: trigger.scheduleUuid,
+                                triggerSet: (trigger.activities ?? []).map(activity => ({
+                                    activity,
+                                })),
+                            },
+                        ]
+                        : []) ??
+                    [];
+                const { updated, warningMsg } = await updateCameraPolicy({
+                    uuid: args.policyUuid,
+                    name: args.name?.trim() || existing.name,
+                    description: args.description?.trim() || existing.description,
+                    scheduledTriggers: mergedTriggers,
+                }, requestModifiers, sessionId);
+                const notes = [];
+                if (replacedTriggers) {
+                    notes.push(`Replaced all schedule triggers — the policy now has ${mergedTriggers.length} ${mergedTriggers.length === 1 ? "trigger" : "triggers"}.`);
+                }
+                if (existing.scheduledTriggers?.length &&
+                    !replacedTriggers &&
+                    existing.scheduledTriggers.some(trigger => !trigger.scheduleUuid)) {
+                    // A trigger with no resolvable scheduleUuid cannot be re-sent, so the
+                    // caller has to know it was dropped rather than preserved.
+                    notes.push("One or more existing schedule triggers had no resolvable schedule and could not be preserved by this update — re-check the policy's schedules.");
+                }
+                return createToolStructuredContent({
+                    updated,
+                    warningMsg,
+                    note: notes.length > 0 ? notes.join(" ") : undefined,
+                });
+            }
+            case CameraPolicyToolRequestType.DELETE: {
+                if (!args.policyUuid) {
+                    return createToolTextContent("policyUuid is required for 'delete'.");
+                }
+                const [{ policies }, byPolicy] = await Promise.all([
+                    getCameraPolicies(requestModifiers, sessionId),
+                    getCamerasByPolicy(requestModifiers, sessionId),
+                ]);
+                const existing = policies.find(entry => entry.uuid === args.policyUuid);
+                if (!existing) {
+                    return createToolTextContent(`No camera policy in this organization has the uuid "${args.policyUuid}". Use requestType 'list' to see the policies that exist.`);
+                }
+                const assigned = byPolicy.get(args.policyUuid) ?? [];
+                if (assigned.length > 0 && !args.confirmDeleteInUse) {
+                    return createToolStructuredContent({
+                        policy: withAssignments(existing, byPolicy),
+                        note: `NOT DELETED — nothing was changed. "${existing.name ?? args.policyUuid}" is still assigned to ` +
+                            `${assigned.length} ${assigned.length === 1 ? "camera" : "cameras"}: ` +
+                            `${assigned.map(camera => camera.name ?? camera.uuid).join(", ")}. Deleting it leaves ` +
+                            `${assigned.length === 1 ? "that camera" : "those cameras"} with no alert policy at all. Tell the user which ` +
+                            `cameras are affected and ask them to confirm, then call this tool again with confirmDeleteInUse: true.`,
+                    });
+                }
+                const { deleted, warningMsg } = await deleteCameraPolicy(args.policyUuid, requestModifiers, sessionId);
+                return createToolStructuredContent({
+                    deleted,
+                    warningMsg,
+                    note: assigned.length > 0
+                        ? `Deleted "${existing.name ?? args.policyUuid}". ${assigned.length} ${assigned.length === 1 ? "camera" : "cameras"} (${assigned.map(camera => camera.name ?? camera.uuid).join(", ")}) now ${assigned.length === 1 ? "has" : "have"} no alert policy.`
+                        : `Deleted "${existing.name ?? args.policyUuid}". No cameras were assigned to it.`,
+                });
+            }
+            case CameraPolicyToolRequestType.ASSIGN_CAMERAS:
+            case CameraPolicyToolRequestType.UNASSIGN_CAMERAS: {
+                const unassigning = args.requestType === CameraPolicyToolRequestType.UNASSIGN_CAMERAS;
+                if (!args.policyUuid) {
+                    return createToolTextContent(`policyUuid is required for '${args.requestType}'.`);
+                }
+                if (!args.cameraUuids) {
+                    return createToolTextContent(`cameraUuids is required for '${args.requestType}'.`);
+                }
+                const parsed = parseCameraUuids(args.cameraUuids);
+                if (!parsed.ok) {
+                    return createToolTextContent(`RETRYABLE — nothing was changed. ${parsed.message}`);
+                }
+                const byPolicy = await getCamerasByPolicy(requestModifiers, sessionId);
+                if (unassigning) {
+                    // Only clear cameras that actually carry THIS policy: writing an empty
+                    // policyUuid to a camera on some other policy would silently strip
+                    // that unrelated policy instead.
+                    const onThisPolicy = new Set((byPolicy.get(args.policyUuid) ?? []).map(camera => camera.uuid));
+                    const notOnPolicy = parsed.value.filter(uuid => !onThisPolicy.has(uuid));
+                    const toClear = parsed.value.filter(uuid => onThisPolicy.has(uuid));
+                    if (toClear.length === 0) {
+                        return createToolStructuredContent({
+                            note: `Nothing was changed — none of the ${parsed.value.length} listed ${parsed.value.length === 1 ? "camera is" : "cameras are"} assigned to this policy. Check the assignment with requestType 'get' first.`,
+                        });
+                    }
+                    const { cameraCount, warningMsg } = await setPolicyOnCameras(toClear, 
+                    // null, not "" — see setPolicyOnCameras: api2 rejects an
+                    // empty string for this RUUID-formatted field.
+                    null, requestModifiers, sessionId);
+                    return createToolStructuredContent({
+                        assigned: { success: true, policyUuid: args.policyUuid, cameraCount },
+                        warningMsg,
+                        note: notOnPolicy.length > 0
+                            ? `Removed the policy from ${cameraCount} ${cameraCount === 1 ? "camera" : "cameras"}, which now ${cameraCount === 1 ? "has" : "have"} no alert policy. SCOPE REDUCED: ${notOnPolicy.length} of the listed cameras were skipped because they were not on this policy (${notOnPolicy.join(", ")}) — their own policies were left alone.`
+                            : `Removed the policy from ${cameraCount} ${cameraCount === 1 ? "camera" : "cameras"}, which now ${cameraCount === 1 ? "has" : "have"} no alert policy.`,
+                    });
+                }
+                // Assigning replaces whatever policy a camera already had; name the
+                // displaced policies so the answer can say what changed.
+                const displaced = new Map();
+                for (const [policyUuid, cameras] of byPolicy) {
+                    if (policyUuid === args.policyUuid)
+                        continue;
+                    for (const camera of cameras) {
+                        if (camera.uuid && parsed.value.includes(camera.uuid)) {
+                            const bucket = displaced.get(policyUuid) ?? [];
+                            bucket.push(camera.name ?? camera.uuid);
+                            displaced.set(policyUuid, bucket);
+                        }
+                    }
+                }
+                const { policies } = await getCameraPolicies(requestModifiers, sessionId);
+                const existing = policies.find(entry => entry.uuid === args.policyUuid);
+                if (!existing) {
+                    return createToolTextContent(`No camera policy in this organization has the uuid "${args.policyUuid}". Use requestType 'list' to see the policies that exist — assigning a non-existent policy would leave the cameras with no policy at all.`);
+                }
+                const { cameraCount, warningMsg } = await setPolicyOnCameras(parsed.value, args.policyUuid, requestModifiers, sessionId);
+                const displacedNote = [...displaced.entries()]
+                    .map(([policyUuid, cameras]) => {
+                    const name = policies.find(entry => entry.uuid === policyUuid)?.name ?? policyUuid;
+                    return `${cameras.join(", ")} (was on "${name}")`;
+                })
+                    .join("; ");
+                return createToolStructuredContent({
+                    assigned: { success: true, policyUuid: args.policyUuid, cameraCount },
+                    warningMsg,
+                    note: displacedNote
+                        ? `Assigned "${existing.name ?? args.policyUuid}" to ${cameraCount} ${cameraCount === 1 ? "camera" : "cameras"}. This REPLACED the policy already on: ${displacedNote}.`
+                        : `Assigned "${existing.name ?? args.policyUuid}" to ${cameraCount} ${cameraCount === 1 ? "camera" : "cameras"}.`,
+                });
+            }
+        }
+    }
+    catch (error) {
+        return createToolStructuredContent({
+            error: error instanceof Error ? error.message : "Unknown error",
+        });
+    }
+    return createToolStructuredContent({
+        error: `Invalid requestType. Valid values are: ${Object.values(CameraPolicyToolRequestType).join(", ")}.`,
+    });
+};
+export function createTool(server) {
+    server.registerTool(TOOL_NAME, {
+        title: "Camera Policies",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, TOOL_HANDLER);
+}

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

@@ -1,73 +1,76 @@
 import { getCameraSettings, getImageForCameraAtTime, getCameraMediaUris, getCameraAIThresholds } from "../api/camera-tool-api.js";
 import { getLogger } from "../logger.js";
-import { BASE_TOOL_ARGS } from "../types/camera-tool-types.js";
+import { BASE_TOOL_ARGS, OUTPUT_SCHEMA } from "../types/camera-tool-types.js";
 import { extractFromToolExtra } from "../util.js";
 const TOOL_NAME = "camera-tool";
+// Tool descriptions are billed on EVERY LLM call even while the tool is
+// deferred behind hosted tool_search, so this string carries only what the
+// model needs to CHOOSE this tool (including the triggers that MUST route
+// here). The step-by-step flows live on the requestType parameter description
+// — unbilled until the tool is loaded, and in front of the model exactly when
+// it is acting. See PERF_MASTER_PLAN P2 #4a.
 const TOOL_DESCRIPTION = `
-This tool can perform some action pertaining to the video stream of a camera. There are four types of requests
-that can be passed into "requestType":
-- image
-- get-settings
-- get-media-uris
-- get-ai-thresholds
+Acts on a camera's video stream. Set "requestType":
+- **image** — a frame from the camera at a given time (timestampISO defaults to ~5 minutes before now for a near-live view; pass a historical timestamp for a past moment, e.g. the time of a badge event). A high-resolution capture of what the camera saw — people, vehicles, license plates, any detectable object — for object recognition, anomaly detection, incident investigation, or situational assessment. Optional crop args zoom into a sub-region.
+- **get-settings** — current configuration of a camera or associated device (sensor, access controller): resolution, bitrate, image/exposure settings, storage. To CHANGE settings use **update-tool** instead.
+- **get-media-uris** — the camera's streaming/playback URIs (LAN and WAN live-stream and VOD URLs, e.g. H.264 and M3U8). Use when the user needs direct stream or playback endpoints.
+- **get-ai-thresholds** — the camera's AI detection threshold configuration (confidence thresholds for detection events). Use when diagnosing why a camera is or isn't generating AI events.
 
-What follows is a description of the behavior of this tool given the requestType "image"
-
-This tool should be used any time someone wants to specify a subset of cameras to use for a task, based on some features that the camera sees.  For example, interior cameras, cameras facing the street, cameras with a view of X, Y, Z, etc.
-
-For instance if someone says "I want X using cameras with Y" then this tool should get a snapshot of the image to answer the question of if the camera satisfies the Y predicate.
-
-This tool captures and returns a real-time snapshot from a designated security camera.
-The image reflects the current scene in the camera's field of view and serves as a contextual
-input source for downstream tasks such as object recognition, anomaly detection, incident investigation,
-or situational assessment. When invoked, the tool provides the following: 
-- Visual Scene Capture: A high-resolution image of what the camera is actively observing, including people, vehicles, license plates, and any detectable objects.
-- Optional zoom: pass cropX, cropY, cropWidth, cropHeight (each a percentage 0-100, origin at the top-left) to return only a sub-region of the frame so you can inspect a detail (e.g. a license plate or a doorway) more closely. Omit them for the full frame. When zooming into a small crop, pass a smaller downscaleFactor (e.g. 1-3) to preserve detail.
-
-What follows is a description of the behavior of this tool given the requestType "get-settings"
-
-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.
+**This tool is REQUIRED, not optional, for two situations** (the exact steps are on the requestType parameter):
+1. **Camera image quality** — "doesn't look great", poor image quality, dark, bright, blurry, washed out, "fix the image", "adjust settings to be optimal", or any mention of image appearance problems: snapshot immediately without asking, then call get-workflows — a guided camera-tuning workflow exists for this; follow its playbook rather than improvising a fix.
+2. **Filtering cameras by what they see** — interior vs exterior, "facing the street", "with a view of X", parking lot, entrance, or any "I want X using cameras with Y": snapshot each candidate camera and judge the predicate from the images.
 `;
 const logger = getLogger("camera-tool");
 const TOOL_ARGS = BASE_TOOL_ARGS;
+// get-settings `detail: "core"` — the faceted config carries geometry/table
+// sub-configs that dwarf the settings anyone reads or edits. Elide those
+// (recursively, so facet nesting doesn't matter) and cap any remaining
+// oversized leaf so the default response stays well under the 5k
+// LLM-compaction threshold. `detail: "full"` skips this entirely.
+const SETTINGS_BLOAT_KEYS = new Set([
+    "metering_config",
+    "motor_config",
+    "ptz_config",
+    "region_for_occupancy",
+    "region_of_interest",
+    "privacy_window_config",
+    "alert_regions",
+]);
+const SETTINGS_VALUE_CHAR_LIMIT = 1_500;
+const OMITTED_PLACEHOLDER = '<omitted at detail:"core" — pass detail:"full" to include>';
+function compactSettings(value) {
+    if (Array.isArray(value)) {
+        const json = JSON.stringify(value);
+        if (json && json.length > SETTINGS_VALUE_CHAR_LIMIT)
+            return OMITTED_PLACEHOLDER;
+        return value.map(compactSettings);
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (SETTINGS_BLOAT_KEYS.has(key)) {
+                out[key] = OMITTED_PLACEHOLDER;
+                continue;
+            }
+            out[key] = compactSettings(child);
+        }
+        return out;
+    }
+    if (typeof value === "string" && value.length > SETTINGS_VALUE_CHAR_LIMIT) {
+        return OMITTED_PLACEHOLDER;
+    }
+    return value;
+}
 const TOOL_HANDLER = async (args, extra) => {
     const { cameraUuid, timestampISO, requestType, cropX, cropY, cropWidth, cropHeight, downscaleFactor } = args;
     if (!cameraUuid) {
+        const ask = {
+            needUserInput: true,
+            commandForUser: "Which camera are you talking about?",
+        };
         return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        needUserInput: true,
-                        commandForUser: "Which camera are you talking about?",
-                    }),
-                },
-            ],
+            content: [{ type: "text", text: JSON.stringify(ask) }],
+            structuredContent: ask,
         };
     }
     // biome-ignore lint/suspicious/noExplicitAny: this will be returned, and can be any type since it will be JSON.stringify'd
@@ -86,66 +89,85 @@ const TOOL_HANDLER = async (args, extra) => {
                 downscaleFactor: downscaleFactor ?? null,
             });
             if (!response.success || !response.imageData) {
+                // isError skips output validation, so the failure detail (status,
+                // message) reaches the model instead of being replaced by a -32602.
                 return {
+                    isError: true,
                     content: [{ type: "text", text: JSON.stringify(response) }],
                 };
             }
             logger.debug(`Received image response (base64 length ${response.imageData.length})`);
-            return {
-                content: [
-                    {
-                        type: "image",
-                        data: response.imageData,
-                        mimeType: "image/jpeg",
-                    },
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            success: true,
-                            status: "image-attached",
-                            cameraUuid,
-                            timestampMs,
-                            cropApplied: response.crop ?? null,
-                        }),
-                    },
-                ],
-            };
-        case "get-settings":
+            {
+                const imageStatus = {
+                    success: true,
+                    status: "image-attached",
+                    cameraUuid,
+                    timestampMs,
+                    cropApplied: response.crop ?? null,
+                };
+                return {
+                    content: [
+                        {
+                            type: "image",
+                            data: response.imageData,
+                            mimeType: "image/jpeg",
+                        },
+                        {
+                            type: "text",
+                            text: JSON.stringify(imageStatus),
+                        },
+                    ],
+                    structuredContent: imageStatus,
+                };
+            }
+        case "get-settings": {
             response = await getCameraSettings(cameraUuid, requestModifiers, sessionId);
+            if (!response?.success) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: JSON.stringify(response) }],
+                };
+            }
+            if (args.detail !== "full" && response?.config) {
+                response = { ...response, config: compactSettings(response.config) };
+            }
             return {
                 content: [{ type: "text", text: JSON.stringify(response) }],
+                structuredContent: response,
             };
+        }
+        // Both throw on an api2 rejection (throwIfApiError), which the SDK turns
+        // into an isError result — so the success path is the only one here.
         case "get-media-uris":
             response = await getCameraMediaUris(cameraUuid, requestModifiers, sessionId);
             return {
                 content: [{ type: "text", text: JSON.stringify(response) }],
+                structuredContent: response,
             };
         case "get-ai-thresholds":
             response = await getCameraAIThresholds(cameraUuid, requestModifiers, sessionId);
             return {
                 content: [{ type: "text", text: JSON.stringify(response) }],
+                structuredContent: response,
             };
         default:
-            response = {
-                error: true,
-                status: "missing unknown type from tool call",
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown requestType "${requestType}" — expected one of: image, get-settings, get-media-uris, get-ai-thresholds.`,
+                    },
+                ],
             };
-            break;
     }
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ response }),
-            },
-        ],
-    };
 };
 export function createTool(server) {
     server.registerTool(TOOL_NAME, {
         title: "Cameras",
         description: TOOL_DESCRIPTION,
         inputSchema: TOOL_ARGS,
+        outputSchema: OUTPUT_SCHEMA,
         annotations: { readOnlyHint: true },
     }, TOOL_HANDLER);
 }

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

@@ -1,43 +1,15 @@
 import { createToolStructuredContent, extractFromToolExtra } from "../util.js";
 import { ApiPayloadSchema, OUTPUT_SCHEMA, TOOL_ARGS, } from "../types/clips-tool-types.js";
-import { getSavedClips, getExpiringClips, getSharedLiveStreams, getTimelapseClips, getClipGroups, getSharedClipGroups, createClip, deleteClip, } from "../api/clips-tool-api.js";
+import { getSavedClips, getExpiringClips, getSharedLiveStreams, getTimelapseClips, getClipGroups, getSharedClipGroups, createClip, deleteClip, updateClip, } from "../api/clips-tool-api.js";
 const TOOL_NAME = "clips-tool";
 const TOOL_DESCRIPTION = `
 Retrieves saved video clips from the Rhombus system. Saved clips can be viewed for up to 2 years and are typically found in the "Clips" tab of the "Saved Video" section of the Rhombus Console.
 Clips are either manually saved by the user, or automatically by some defined policy. Therefore, this tool
 is not for looking up the events that have occured.
 
-This tool allows you to:
-* Get saved clips or clips expiring soon (filter by devices, locations, search string, time range).
-* Get all shared live video streams for the organization.
-* Get all timelapse clips for the organization.
-
-Filter options (for saved and expiringSoon only):
-* Specific devices using their UUIDs (deviceUuidFilters).
-* Specific locations using their UUIDs (locationUuidFilters).
-* A simple string search on clip names (searchFilter).
-* A time range: start (timestampISOAfter) and/or end (timestampISOBefore) timestamp in ISO 8601 format.
-
-The tool returns a JSON object with the following structure and important fields:
-* **errorMsg (string | null):** An error message if the request failed.
-* **objecterror (boolean | null):** Indicates if an object-level error occurred.
-* **pageToken (string | null):** A token to be supplied on the next search request to get the next page of results. If this token is null, there is no more data available.
-* **savedClips (array of objects | null):** An array where each object represents a saved video clip. Each clip object contains the following important fields:
-    * **uuid (string):** The unique identifier for the video clip.
-    * **title (string):** The name given to the video clip.
-    * **description (string | null):** An optional description for the clip.
-    * **timestampMs (int64):** The start time of the video clip in milliseconds since epoch.
-    * **createdAtMs (int64):** The creation timestamp of the clip in milliseconds since epoch.
-    * **createdAtTimestamp (string):** The creation timestamp of the clip in ISO 8601 format.
-    * **deviceUuid (string):** The UUID of the primary device (e.g., camera) that recorded the clip.
-    * **deviceUuids (array of strings or null):** A list of UUIDs for all devices associated with the clip.
-    * **durationSec (int32):** The length of the video clip in seconds.
-    * **status (string):** The current processing status of the clip, with possible values such as INITIATING, UPLOADING, RENDERING, FAILED, COMPLETE, OFFLINE, or UNKNOWN.
-    * **userUuid (string | null):** The UUID of the user associated with the clip, if applicable.
-    * **sourceAlertUuid (string | null):** The UUID of the alert that triggered the creation of this clip, if any.
-* **sharedLiveVideoStreams (array):** When requestType is sharedLiveStreams, list of shared live video stream objects.
-* **timelapseClips (array):** When requestType is timelapseClips, list of timelapse clip objects.
+Set "requestType" to: get saved clips or clips expiring soon (filter by devices, locations, name search, and time range); list the org's shared live video streams, timelapse clips, clip groups, or shared clip groups; **createClip** to save a new clip from a camera's footage (video evidence around an event); or **deleteClip** to permanently delete a saved clip — destructive and irreversible, confirm with the user first.
 
+Each saved clip carries uuid, title, description, start and creation timestamps, the recording device(s), durationSec, processing status (INITIATING / UPLOADING / RENDERING / FAILED / COMPLETE / OFFLINE / UNKNOWN), and the alert that triggered it when there was one. Results paginate via pageToken (null when there is no more data).
 `;
 const TOOL_HANDLER = async (args, extra) => {
     const { requestModifiers, sessionId } = extractFromToolExtra(extra);
@@ -61,6 +33,24 @@ const TOOL_HANDLER = async (args, extra) => {
             }
             return createToolStructuredContent(await createClip(args.spliceRequest.cameraUuid, args.spliceRequest.startTimeMs, args.spliceRequest.endTimeMs, requestModifiers, sessionId));
         }
+        case "updateClip": {
+            if (!args.clipUuid) {
+                throw new Error("clipUuid is required for 'updateClip' requestType");
+            }
+            if (!args.clipTitle?.trim() && !args.clipDescription?.trim()) {
+                throw new Error("'updateClip' needs at least one of clipTitle or clipDescription — both were empty, so there is nothing to change");
+            }
+            const { existingTitle, ...result } = await updateClip(args.clipUuid, {
+                title: args.clipTitle?.trim() || undefined,
+                description: args.clipDescription?.trim() || undefined,
+            }, requestModifiers, sessionId);
+            return createToolStructuredContent({
+                ...result,
+                note: result.updateResult
+                    ? `Renamed the clip${existingTitle ? ` "${existingTitle}"` : ""}${args.clipTitle?.trim() ? ` to "${args.clipTitle.trim()}"` : ""}. Fields you did not pass were left as they were.`
+                    : undefined,
+            });
+        }
         case "deleteClip": {
             if (!args.clipUuid) {
                 throw new Error("clipUuid is required for 'deleteClip' requestType");

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

@@ -12,17 +12,25 @@ export function createTool(server) {
                 .array(z.string().describe("UUID string of an individual item"))
                 .describe("An array of UUID strings representing the items to count. Each string should be a valid UUID."),
         },
+        // Every result from a tool with an outputSchema must carry
+        // structuredContent or isError: true — the SDK otherwise replaces the
+        // real message with an opaque -32602 (see CLAUDE.md).
+        outputSchema: {
+            count: z.number().optional().describe("How many UUIDs were provided"),
+        },
         annotations: { readOnlyHint: true },
     }, async ({ uuids }) => {
         try {
             logger.info("Counting UUIDs", uuids);
             return {
                 content: [{ type: "text", text: `Count: ${uuids.length}` }],
+                structuredContent: { count: uuids.length },
             };
         }
         catch (e) {
             const errorMessage = e instanceof Error ? e.message : `Unknown error: ${e}`;
             return {
+                isError: true,
                 content: [{ type: "text", text: `Error counting UUIDs: ${errorMessage}` }],
             };
         }